The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
一覧に戻る

セキュリティに関するヒントとコツ

Quarkus Security依存関係

io.quarkus:quarkus-security モジュールには、Quarkus Securityの中核となるクラスが含まれています。

ほとんどの場合、すべてのセキュリティエクステンションですでに提供されているため、プロジェクトのビルドファイルに直接追加する必要はありません。しかし、独自のカスタムセキュリティコードを書いたり（例えば、 カスタム Jakarta SecurityContext を登録したり）、 BouncyCastle ライブラリを使用する必要がある場合は、必ず含まれていることを確認してください:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-security</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-security")

HttpAuthenticationMechanism のカスタマイズ

CDI実装Beanを登録することで、 HttpAuthenticationMechanism をカスタマイズすることができます。以下の例では、カスタム認証機能は quarkus-smallrye-jwt によって提供される JWTAuthMechanism に委譲します。 :

@Alternative
@Priority(1)
@ApplicationScoped
public class CustomAwareJWTAuthMechanism implements HttpAuthenticationMechanism {

	private static final Logger LOG = LoggerFactory.getLogger(CustomAwareJWTAuthMechanism.class);

	@Inject
	JWTAuthMechanism delegate;

	@Override
	public Uni<SecurityIdentity> authenticate(RoutingContext context, IdentityProviderManager identityProviderManager) {
	    // do some custom action and delegate
            return delegate.authenticate(context, identityProviderManager);
	}

	@Override
	public Uni<ChallengeData> getChallenge(RoutingContext context) {
		return delegate.getChallenge(context);
	}

	@Override
	public Set<Class<? extends AuthenticationRequest>> getCredentialTypes() {
		return delegate.getCredentialTypes();
	}

	@Override
	public Uni<HttpCredentialTransport> getCredentialTransport() {
		return delegate.getCredentialTransport();
	}

}

複数のHttpAuthenticationMechanism処理

複数の HttpAuthenticationMechanism は組み合わせて使っていくことができます。例えば、HTTP Authorization Basic または Bearer スキーム値として渡されたサービスクライアントの資格情報を検証するためには、 quarkus-smallrye-jwt によって提供される Basic または JWT メカニズムを使う必要がありますし、Keycloak やその他の OpenID Connect プロバイダでユーザを認証するには quarkus-oidc の Authorization Code メカニズムを使用していく必要があります。

このような場合、 SecurityIdentity が作成されるまで、メカニズムが順番にクレデンシャルを検証するように要求されます。認証メカニズムは、優先度の降順でソートされています。 Basic 認証メカニズムの優先順位は最高で 2000 、次いで Authorization Code の優先順位は 1001 、Quarkus が提供する他のすべてのメカニズムの優先順位は 1000 となっています。

例えば、 401 ステータスは Basic または JWT のいずれかのメカニズムによって返され、ユーザーを OpenId Connect プロバイダにリダイレクトする URL は quarkus-oidc によって返されるなど、認証情報が提供されない場合はメカニズム固有のチャレンジが作成されます。

つまり、 Basic と Authorization Code の仕組みが組み合わされた場合、認証情報が提供されなければ 401 が返され、 JWT と Authorization Code の仕組みが組み合わされた場合、リダイレクト URL が返されることになります。

このようなデフォルトのチャレンジ選択ロジックが、あるアプリケーションでまさに必要とされる場合もありますが、時には要件を満たさない場合もあります。そのような場合（あるいは、メカニズムが現在の認証またはチャレンジ要求を処理するように求められる順序を変更したい他の同様の場合）、カスタムメカニズムを作成し、どのメカニズムがチャレンジを作成すべきかを選択することができます。 :

@Alternative (1)
@Priority(1)
@ApplicationScoped
public class CustomAwareJWTAuthMechanism implements HttpAuthenticationMechanism {

	private static final Logger LOG = LoggerFactory.getLogger(CustomAwareJWTAuthMechanism.class);

	@Inject
	JWTAuthMechanism jwt;

        @Inject
	OidcAuthenticationMechanism oidc;

	@Override
	public Uni<SecurityIdentity> authenticate(RoutingContext context, IdentityProviderManager identityProviderManager) {
	    return selectBetweenJwtAndOidc(context).authenticate(context, identityProviderManager);
	}

	@Override
	public Uni<ChallengeData> getChallenge(RoutingContext context) {
            return selectBetweenJwtAndOidcChallenge(context).getChallenge(context);
	}

	@Override
	public Set<Class<? extends AuthenticationRequest>> getCredentialTypes() {
            Set<Class<? extends AuthenticationRequest>> credentialTypes = new HashSet<>();
            credentialTypes.addAll(jwt.getCredentialTypes());
            credentialTypes.addAll(oidc.getCredentialTypes());
            return credentialTypes;
	}

        @Override
        public Uni<HttpCredentialTransport> getCredentialTransport(RoutingContext context) {
            return selectBetweenJwtAndOidc(context).getCredentialTransport(context);
        }

        private HttpAuthenticationMechanism selectBetweenJwtAndOidc(RoutingContext context) {
            ....
        }

        private HttpAuthenticationMechanism selectBetweenJwtAndOidcChallenge(RoutingContext context) {
            // for example, if no `Authorization` header is available and no `code` parameter is provided - use `jwt` to create a challenge
        }

}
1 メカニズムを代替Beanとして宣言することで、 OidcAuthenticationMechanism や JWTAuthMechanism ではなく、このメカニズムが使用されることが保証されます。

セキュリティー・アイデンティティのカスタマイズ

内部的には、アイデンティティ プロバイダは、プリンシパル、役割、クライアント(ユーザー)の認証に使用されたクレデンシャル、 およびその他のセキュリティー属性を保持する io.quarkus.security.identity.SecurityIdentity クラスのインスタンスを作成して更新します。 SecurityIdentity をカスタマイズする簡単なオプションは、カスタム SecurityIdentityAugmentor を登録することです。例えば、以下のオーグメンターは、追加のロールを追加します。 :

import io.quarkus.security.identity.AuthenticationRequestContext;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.identity.SecurityIdentityAugmentor;
import io.quarkus.security.runtime.QuarkusSecurityIdentity;
import io.smallrye.mutiny.Uni;

import jakarta.enterprise.context.ApplicationScoped;
import java.util.function.Supplier;

@ApplicationScoped
public class RolesAugmentor implements SecurityIdentityAugmentor {

    @Override
    public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
        return Uni.createFrom().item(build(identity));

        // Do 'return context.runBlocking(build(identity));'
        // if a blocking call is required to customize the identity
    }

    private Supplier<SecurityIdentity> build(SecurityIdentity identity) {
        if(identity.isAnonymous()) {
            return () -> identity;
        } else {
            // create a new builder and copy principal, attributes, credentials and roles from the original identity
            QuarkusSecurityIdentity.Builder builder = QuarkusSecurityIdentity.builder(identity);

            // add custom role source here
            builder.addRole("dummy");
            return builder::build;
        }
    }
}

ここでは、現在の 相互 TLS（mTLS）認証 リクエストで利用可能なクライアント証明書を使用して、さらにロールを追加する方法を示す別の例を紹介します:

import java.security.cert.X509Certificate;
import io.quarkus.security.credential.CertificateCredential;
import io.quarkus.security.identity.AuthenticationRequestContext;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.identity.SecurityIdentityAugmentor;
import io.quarkus.security.runtime.QuarkusSecurityIdentity;
import io.smallrye.mutiny.Uni;

import jakarta.enterprise.context.ApplicationScoped;
import java.util.function.Supplier;
import java.util.Set;

@ApplicationScoped
public class RolesAugmentor implements SecurityIdentityAugmentor {

    @Override
    public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
        return Uni.createFrom().item(build(identity));
    }

    private Supplier<SecurityIdentity> build(SecurityIdentity identity) {
        // create a new builder and copy principal, attributes, credentials and roles from the original identity
        QuarkusSecurityIdentity.Builder builder = QuarkusSecurityIdentity.builder(identity);

        CertificateCredential certificate = identity.getCredential(CertificateCredential.class);
        if (certificate != null) {
            builder.addRoles(extractRoles(certificate.getCertificate()));
        }
        return builder::build;
    }

    private Set<String> extractRoles(X509Certificate certificate) {
        String name = certificate.getSubjectX500Principal().getName();

        switch (name) {
            case "CN=client":
                return Collections.singleton("user");
            case "CN=guest-client":
                return Collections.singleton("guest");
            default:
                return Collections.emptySet();
        }
    }
}

複数のカスタム SecurityIdentityAugmentor が登録されている場合、それらは同等の候補とみなされ、ランダムな順序で呼び出されます。デフォルトの SecurityIdentityAugmentor#priority メソッドを実装することで順番を強制することができます。優先度の高いAugmentors が最初に起動されます。

デフォルトでは、セキュリティ・アイデンティティーを拡張する際に、リクエストコンテキストは有効になりません。これは、リクエストコンテキストを必須とするHibernateなどを使用したい場合、 jakarta.enterprise.context.ContextNotActiveException が発生することを意味します。

解決策は、リクエストコンテキストをアクティブにすることです。次の例では、Hibernate with Panache UserRoleEntity からロールを取得する方法を示しています。

import io.quarkus.security.identity.AuthenticationRequestContext;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.identity.SecurityIdentityAugmentor;
import io.smallrye.mutiny.Uni;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Instance;
import jakarta.inject.Inject;

@ApplicationScoped
public class RolesAugmentor implements SecurityIdentityAugmentor {

    @Inject
    Instance<SecurityIdentitySupplier> identitySupplierInstance;

    @Override
    public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
        if(identity.isAnonymous()) {
            return Uni.createFrom().item(identity);
        }

        // Hibernate ORM is blocking
        SecurityIdentitySupplier identitySupplier = identitySupplierInstance.get();
        identitySupplier.setIdentity(identity);
        return context.runBlocking(identitySupplier);
    }
}
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.runtime.QuarkusSecurityIdentity;

import jakarta.enterprise.context.Dependent;
import jakarta.enterprise.context.control.ActivateRequestContext;
import java.util.function.Supplier;

@Dependent
class SecurityIdentitySupplier implements Supplier<SecurityIdentity> {

    private SecurityIdentity identity;

    @Override
    @ActivateRequestContext
    public SecurityIdentity get() {
        QuarkusSecurityIdentity.Builder builder = QuarkusSecurityIdentity.builder(identity);
        String user = identity.getPrincipal().getName();

        UserRoleEntity.<userRoleEntity>streamAll()
                .filter(role -> user.equals(role.user))
                .forEach(role -> builder.addRole(role.role));

        return builder.build();
    }

    public void setIdentity(SecurityIdentity identity) {
        this.identity = identity;
    }
}

カスタムJakarta REST SecurityContext

Jakarta REST ContainerRequestFilter を使用してカスタムの Jakarta REST SecurityContext を設定する場合、このカスタムのセキュリティコンテキストを Quarkus SecurityIdentity とリンクさせるために @PreMatching アノテーションを追加するなどして、 Jakarta REST の事前一致フェーズで ContainerRequestFilter が実行されるようにします:

import java.security.Principal;

import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.container.ContainerRequestFilter;
import jakarta.ws.rs.container.PreMatching;
import jakarta.ws.rs.core.SecurityContext;
import jakarta.ws.rs.ext.Provider;

@Provider
@PreMatching
public class SecurityOverrideFilter implements ContainerRequestFilter {
    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {
        String user = requestContext.getHeaders().getFirst("User");
        String role = requestContext.getHeaders().getFirst("Role");
        if (user != null && role != null) {
            requestContext.setSecurityContext(new SecurityContext() {
                @Override
                public Principal getUserPrincipal() {
                    return new Principal() {
                        @Override
                        public String getName() {
                            return user;
                        }
                    };
                }

                @Override
                public boolean isUserInRole(String r) {
                    return role.equals(r);
                }

                @Override
                public boolean isSecure() {
                    return false;
                }

                @Override
                public String getAuthenticationScheme() {
                    return "basic";
                }
            });
        }

    }
}

認可の無効化

認可を無効にする正当な理由がある場合(テスト時など)は、カスタムの AuthorizationController を登録してください。 :

@Alternative
@Priority(Interceptor.Priority.LIBRARY_AFTER)
@ApplicationScoped
public class DisabledAuthController extends AuthorizationController {
    @ConfigProperty(name = "disable.authorization", defaultValue = "false")
    boolean disableAuthorization;

    @Override
    public boolean isAuthorizationEnabled() {
        return !disableAuthorization;
    }
}

手動テストのために、Quarkusは、開発モードで認証を無効にする便利な設定プロパティを提供します。このプロパティは、上記のカスタム AuthorizationController とまったく同じ効果を持ちますが、開発モードでのみ利用可能です。 :

quarkus.security.auth.enabled-in-dev-mode=false

また、 TestSecurity アノテーションを使ってセキュリティチェックを無効にする方法については、 TestingSecurity Annotationの項を参照してください。

セキュリティー プロバイダの登録

デフォルトのプロバイダ

ネイティブモードで実行している場合、GraalVMネイティブ実行可能ファイル生成のデフォルトの動作は、SSLを有効にしていない限り、メインの「SUN」プロバイダのみを含めるようになっています。SSLを有効にしている場合は、すべてのセキュリティープロバイダが登録されます。SSLを使用していない場合は、 quarkus.security.security-providers プロパティーを使用して、セキュリティープロバイダを名前で選択的に登録することができます。以下の例は、「SunRsaSign」と「SunJCE」のセキュリティープロバイダを登録するための設定を説明しています。 :

セキュリティー プロバイダの設定例
quarkus.security.security-providers=SunRsaSign,SunJCE

BouncyCastle

org.bouncycastle.jce.provider.BouncyCastleProvider JCE プロバイダを登録する必要がある場合は、 BC プロバイダ名を設定してください。 :

セキュリティープロバイダの例 BouncyCastleの設定
quarkus.security.security-providers=BC

そして、BouncyCastleプロバイダ依存関係を追加します。 :

pom.xml
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk18on</artifactId>
</dependency>
build.gradle
implementation("org.bouncycastle:bcprov-jdk18on")

BouncyCastle JSSE

org.bouncycastle.jsse.provider.BouncyCastleJsseProvider JSSE プロバイダを登録して、デフォルトの SunJSSE プロバイダの代わりに使用する必要がある場合は、 BCJSSE というプロバイダ名を設定してください。 :

BouncyCastle JSSE セキュリティープロバイダの設定例
quarkus.security.security-providers=BCJSSE

quarkus.http.ssl.client-auth=REQUIRED

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=password
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=password

そして、BouncyCastleのTLS依存関係を追加します。 :

pom.xml
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bctls-jdk18on</artifactId>
</dependency>
build.gradle
implementation("org.bouncycastle:bctls-jdk18on")

BouncyCastle FIPS

org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider JCE プロバイダを登録する必要がある場合は、 BCFIPS というプロバイダ名を設定してください。 :

BouncyCastle FIPS セキュリティープロバイダの設定例
quarkus.security.security-providers=BCFIPS

そして、BouncyCastle FIPSプロバイダの依存関係を追加します。 :

pom.xml
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bc-fips</artifactId>
</dependency>
build.gradle
implementation("org.bouncycastle:bc-fips")

BCFIPS プロバイダオプションはネイティブイメージでサポートされていますが、生成されたキーを確認するために java.security.SecureRandom に依存していたアルゴリズムのセルフテストは、これらのテストをパスするために削除されています。以下のクラスが影響を受けます。 : - org.bouncycastle.crypto.general.DSA - org.bouncycastle.crypto.general.DSTU4145 - org.bouncycastle.crypto.general.ECGOST3410 - org.bouncycastle.crypto.general.GOST3410 - org.bouncycastle.crypto.fips.FipsDSA - org.bouncycastle.crypto.fips.FipsEC - org.bouncycastle.crypto.fips.FipsRSA

BouncyCastle JSSE FIPS

デフォルトのSunJSSEプロバイダではなく、 org.bouncycastle.jsse.provider.BouncyCastleJsseProvider JSSEプロバイダを登録して、 org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider と組み合わせて使用する必要がある場合は、 BCFIPSJSSE というプロバイダ名を設定してください。 :

BouncyCastle FIPS JSSE セキュリティープロバイダの設定例
quarkus.security.security-providers=BCFIPSJSSE

quarkus.http.ssl.client-auth=REQUIRED

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=password
quarkus.http.ssl.certificate.key-store-file-type=BCFKS
quarkus.http.ssl.certificate.key-store-provider=BCFIPS
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=password
quarkus.http.ssl.certificate.trust-store-file-type=BCFKS
quarkus.http.ssl.certificate.trust-store-provider=BCFIPS

そして、BouncyCastle FIPSプロバイダを使用するために最適化されたBouncyCastle TLS依存関係:

pom.xml
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bctls-fips</artifactId>
</dependency>

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bc-fips</artifactId>
</dependency>
build.gradle
implementation("org.bouncycastle:bctls-fips")
implementation("org.bouncycastle:bc-fips")

ここでは keystore と truststore のタイプとプロバイダが BCFKS と BCFIPS に設定されていることに注意してください。このタイプとプロバイダでは、以下のようにキーストアを生成することができます。 :

keytool -genkey -alias server -keyalg RSA -keystore server-keystore.jks -keysize 2048 -keypass password -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath $PATH_TO_BC_FIPS_JAR -storetype BCFKS

BCFIPSJSSE プロバイダーオプションは、現在ネイティブイメージではサポートされていません。

SunPKCS11

SunPKCS11 プロバイダーは、暗号化スマートカードやその他のハードウェアセキュリティモジュール、FIPSモードのネットワークセキュリティサービスなど、特定の PKCS#11 実装へのブリッジを提供します。

通常、 SunPKCS11 を扱うには、 PKCS#11 の実装をインストールし、共有ライブラリやトークンスロットなどを参照する設定を生成し、以下のJavaコードを記述する必要があります。 :

import java.security.Provider;
import java.security.Security;

String configuration = "pkcs11.cfg"

Provider sunPkcs11 = Security.getProvider("SunPKCS11");
Provider pkcsImplementation = sunPkcs11.configure(configuration);
// or prepare configuration in the code or read it from the file such as "pkcs11.cfg" and do
// sunPkcs11.configure("--" + configuration);
Security.addProvider(pkcsImplementation);

Quarkusでは、例えばコードを修正することなく、設定レベルのみで同じことを実現することができます。 :

quarkus.security.security-providers=SunPKCS11
quarkus.security.security-provider-config.SunPKCS11=pkcs11.cfg

SunPKCS11 ブリッジプロバイダへのアクセスはネイティブイメージでサポートされていますが、 SunPKCS11 の設定は現在 Quarkus レベルでネイティブイメージでサポートされていないことに注意してください。

Reactive Security

リアクティブな環境でセキュリティーを使用する場合は、SmallRye Context Propagationが必要になるでしょう。 :

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-context-propagation</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-smallrye-context-propagation")

これにより、リアクティブコールバック全体にアイデンティティを伝搬させることができます。また、Quarkusがアイデンティティを伝搬できることを確かにするために、アイデンティティを伝搬できるエグゼキューターを使用していることを確認する必要があります（例: CompletableFuture.supplyAsync を使用しない場合）。詳細については、 Context Propagation Guideを参照してください。

参照

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by