The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

Quarkus の認証メカニズム

Quarkus Security フレームワークは、複数の認証メカニズムをサポートしており、これらを使用してアプリケーションを保護することができます。 また、認証メカニズムを組み合わせることも可能です。

Quarkus アプリケーションを保護するための認証メカニズムを選択する前に、提供される情報を確認してください。

サポートされる認証メカニズムの概要

サポートされている認証メカニズムは、Quarkus に組み込まれているものもあれば、エクステンションを追加する必要があるものもあります。 これらのメカニズムについては、次のセクションで詳しく説明します:

次の表は、特定の認証要件と、Quarkus で使用できるサポートされる認証メカニズムを対応付けたものです:

Table 1. 認証要件とメカニズム
認証要件 認証メカニズム

ユーザー名とパスワード

Basic, フォームベース認証

ベアラーアクセストークン

OIDC ベアラートークン認証、JWT、OAuth2

シングルサインオン (SSO)

OIDC Code Flow, フォームベース認証

クライアント証明書

相互 TLS 認証

WebAuthn

WebAuthn

Kerberos チケット

Kerberos

詳細は、以下の トークン認証メカニズムの比較 の表をご覧ください。

組込認証メカニズム

Quarkus Security には、次のような組込の認証サポートがあります:

Basic 認証

内蔵の HTTP Basic 認証メカニズムを使用して、Quarkus アプリケーションエンドポイントを保護することができます。 詳細については、次のドキュメントを参照してください:

フォームベース認証

Quarkus は、従来の Servlet フォームベース認証と同様に動作するフォームベース認証を提供します。 従来のフォーム認証とは異なり、Quarkus はクラスター化された HTTP セッションをサポートしていないため、認証されたユーザーは HTTP セッションに保存されません。 代わりに、認証情報は暗号化された Cookie に保存され、同じ暗号化キーを共有するすべてのクラスターメンバーが読み取ることができます。

暗号化を適用するには、 quarkus.http.auth.session.encryption-key プロパティーを追加し、設定する値が 16 文字以上であるようにして下さい。 暗号化キーは SHA-256 を使用してハッシュ化されます。 結果のダイジェストは、Cookie 値の AES-256 暗号化のキーとして使用されます。 Cookie には暗号化された値の一部として有効期限が含まれているため、クラスター内のすべてのノードのクロックが同期されている必要があります。 セッションが使用中であれば、1 分間隔で有効期限が更新された新しい Cookie が生成されます。

フォーム認証を開始するには、Basic 認証を有効にする で説明されているのと同様の設定が必要であり、 quarkus.http.auth.form.enabled プロパティーを true に設定する必要があります。

フォームベース認証を使用した単純な application.properties は次のようになります。

quarkus.http.auth.form.enabled=true

quarkus.http.auth.form.login-page=login.html
quarkus.http.auth.form.landing-page=hello
quarkus.http.auth.form.error-page=

# Define testing user
quarkus.security.users.embedded.enabled=true
quarkus.security.users.embedded.plain-text=true
quarkus.security.users.embedded.users.alice=alice
quarkus.security.users.embedded.roles.alice=user

application.properties ファイルでユーザー名、シークレット、およびロールを設定することは、テストシナリオにのみ適しています。実稼働アプリケーションを保護するには、データベースまたは LDAP を使用してこの情報を格納することが重要です。詳細は、Jakarta Persistence を備えた Quarkus Security または Basic 認証を有効にする に記載されているその他の情報を参照してください。

アプリケーションのログインページには、以下と同様の HTML フォームが含まれます。

<form action="/j_security_check" method="post">
    <label>Username</label>
    <input type="text" placeholder="Username" name="j_username" required>
    <label>Password</label>
    <input type="password" placeholder="Password" name="j_password" required>
    <button type="submit">Login</button>
</form>

シングルページアプリケーション (SPA) では、通常、次の例に示すように、デフォルトのページパスを削除してリダイレクトを回避する必要があります。

# do not redirect, respond with HTTP 200 OK
quarkus.http.auth.form.landing-page=

# do not redirect, respond with HTTP 401 Unauthorized
quarkus.http.auth.form.login-page=
quarkus.http.auth.form.error-page=

# HttpOnly must be false if you want to log out on the client; it can be true if logging out from the server
quarkus.http.auth.form.http-only-cookie=false

SPA のリダイレクトを無効にしたので、クライアントからプログラムによってログインおよびログアウトする必要があります。 以下は、 j_security_check エンドポイントにログインし、Cookie を破棄してアプリケーションからログアウトするための JavaScript メソッドの例です。

const login = () => {
    // Create an object to represent the form data
    const formData = new URLSearchParams();
    formData.append("j_username", username);
    formData.append("j_password", password);

    // Make an HTTP POST request using fetch against j_security_check endpoint
    fetch("j_security_check", {
        method: "POST",
        body: formData,
        headers: {
            "Content-Type": "application/x-www-form-urlencoded",
        },
    })
    .then((response) => {
        if (response.status === 200) {
            // Authentication was successful
            console.log("Authentication successful");
        } else {
            // Authentication failed
            console.error("Invalid credentials");
        }
    })
    .catch((error) => {
        console.error(error);
    });
};

SPA でクライアント側から ログアウトするには、Cookie を quarkus.http.auth.form.http-only-cookie=false に設定して、Cookie を破棄し、 t可能であればメインページにリダイレクトできるようにする必要があります。

const logout= () => {
    // delete the credential cookie, essentially killing the session
    const removeCookie = `quarkus-credential=; Max-Age=0;path=/`;
    document.cookie = removeCookie;

    // perform post-logout actions here, such as redirecting back to your login page
};

SPA でサーバー側から ログアウトするには、Cookie を quarkus.http.auth.form.http-only-cookie=true に設定し、このサンプルコードを使用して Cookie を破棄します。

import io.quarkus.security.identity.CurrentIdentityAssociation;
import io.quarkus.vertx.http.runtime.security.FormAuthenticationMechanism;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.POST;

@Inject
CurrentIdentityAssociation identity;

@POST
public Response logout() {
    if (identity.getIdentity().isAnonymous()) {
        throw new UnauthorizedException("Not authenticated");
    }
    FormAuthenticationMechanism.logout(identity.getIdentity()); (1)
    return Response.noContent().build();
}
1 セッション Cookie を削除してログアウトを実行します。

フォームベース認証の設定には、以下のプロパティーを使用できます:

ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。

Configuration property

タイプ

デフォルト

quarkus.http.auth.permission."permissions".enabled

Determines whether the entire permission set is enabled, or not.

By default, if the permission set is defined, it is enabled.

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__ENABLED

Show more

ブーリアン

quarkus.http.auth.permission."permissions".policy

The HTTP policy that this permission set is linked to.

There are three built-in policies: permit, deny and authenticated. Role based policies can be defined, and extensions can add their own policies.

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__POLICY

Show more

string

required

quarkus.http.auth.permission."permissions".methods

The methods that this permission set applies to. If this is not set then they apply to all methods.

Note that if a request matches any path from any permission set, but does not match the constraint due to the method not being listed then the request will be denied.

Method specific permissions take precedence over matches that do not have any methods set.

This means that for example if Quarkus is configured to allow GET and POST requests to /admin to and no other permissions are configured PUT requests to /admin will be denied.

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__METHODS

Show more

list of string

quarkus.http.auth.permission."permissions".paths

The paths that this permission check applies to. If the path ends in /* then this is treated as a path prefix, otherwise it is treated as an exact match.

Matches are done on a length basis, so the most specific path match takes precedence.

If multiple permission sets match the same path then explicit methods matches take precedence over matches without methods set, otherwise the most restrictive permissions are applied.

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__PATHS

Show more

list of string

quarkus.http.auth.permission."permissions".auth-mechanism

Path specific authentication mechanism which must be used to authenticate a user. It needs to match io.quarkus.vertx.http.runtime.security.HttpCredentialTransport authentication scheme such as 'basic', 'bearer', 'form', etc.

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__AUTH_MECHANISM

Show more

string

quarkus.http.auth.permission."permissions".shared

Indicates that this policy always applies to the matched paths in addition to the policy with a winning path. Avoid creating more than one shared policy to minimize the performance impact.

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__SHARED

Show more

ブーリアン

false

quarkus.http.auth.permission."permissions".applies-to

Whether permission check should be applied on all matching paths, or paths specific for the Jakarta REST resources.

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__APPLIES_TO

Show more

allApply on all matching paths., jaxrsDeclares that a permission check must only be applied on the Jakarta REST request paths. Use this option to delay the permission check if an authentication mechanism is chosen with an annotation on the matching Jakarta REST endpoint. This option must be set if the following REST endpoint annotations are used\: - io.quarkus.oidc.Tenant annotation which selects an OIDC authentication mechanism with a tenant identifier - io.quarkus.vertx.http.runtime.security.annotation.BasicAuthentication which selects the Basic authentication mechanism - io.quarkus.vertx.http.runtime.security.annotation.FormAuthentication which selects the Form-based authentication mechanism - io.quarkus.vertx.http.runtime.security.annotation.MTLSAuthentication which selects the mTLS authentication mechanism - io.quarkus.security.webauthn.WebAuthn which selects the WebAuth authentication mechanism - io.quarkus.oidc.BearerTokenAuthentication which selects the OpenID Connect Bearer token authentication mechanism - io.quarkus.oidc.AuthorizationCodeFlow which selects the OpenID Connect Code authentication mechanism

allApply on all matching paths.

quarkus.http.auth.policy."role-policy".roles-allowed

The roles that are allowed to access resources protected by this policy. By default, access is allowed to any authenticated user.

Environment variable: QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__ROLES_ALLOWED

Show more

list of string

**

quarkus.http.auth.policy."role-policy".roles."role-name"

Add roles granted to the SecurityIdentity based on the roles that the SecurityIdentity already have. For example, the Quarkus OIDC extension can map roles from the verified JWT access token, and you may want to remap them to a deployment specific roles.

Environment variable: QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__ROLES__ROLE_NAME_

Show more

Map<String,List<String>>

quarkus.http.auth.policy."role-policy".permissions."role-name"

Permissions granted to the SecurityIdentity if this policy is applied successfully (the policy allows request to proceed) and the authenticated request has required role. For example, you can map permission perm1 with actions action1 and action2 to role admin by setting quarkus.http.auth.policy.role-policy1.permissions.admin=perm1:action1,perm1:action2 configuration property. Granted permissions are used for authorization with the @PermissionsAllowed annotation.

Environment variable: QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__PERMISSIONS__ROLE_NAME_

Show more

Map<String,List<String>>

quarkus.http.auth.policy."role-policy".permission-class

Permissions granted by this policy will be created with a java.security.Permission implementation specified by this configuration property. The permission class must declare exactly one constructor that accepts permission name (String) or permission name and actions (String, String[]). Permission class must be registered for reflection if you run your application in a native mode.

Environment variable: QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__PERMISSION_CLASS

Show more

string

io.quarkus.security.StringPermission

quarkus.http.auth.roles-mapping."role-name"

Map the SecurityIdentity roles to deployment specific roles and add the matching roles to SecurityIdentity.

For example, if SecurityIdentity has a user role and the endpoint is secured with a 'UserRole' role, use this property to map the user role to the UserRole role, and have SecurityIdentity to have both user and UserRole roles.

Environment variable: QUARKUS_HTTP_AUTH_ROLES_MAPPING__ROLE_NAME_

Show more

Map<String,List<String>>

quarkus.http.auth.certificate-role-attribute

Client certificate attribute whose values are going to be mapped to the 'SecurityIdentity' roles according to the roles mapping specified in the certificate properties file. The attribute must be either one of the Relative Distinguished Names (RDNs) or Subject Alternative Names (SANs). By default, the Common Name (CN) attribute value is used for roles mapping. Supported values are:

  • RDN type - Distinguished Name field. For example 'CN' represents Common Name field. Multivalued RNDs and multiple instances of the same attributes are currently not supported.

  • 'SAN_RFC822' - Subject Alternative Name field RFC 822 Name.

  • 'SAN_URI' - Subject Alternative Name field Uniform Resource Identifier (URI).

  • 'SAN_ANY' - Subject Alternative Name field Other Name. Please note that only simple case of UTF8 identifier mapping is supported. For example, you can map 'other-identifier' to the SecurityIdentity roles. If you use 'openssl' tool, supported Other name definition would look like this: subjectAltName=otherName:1.2.3.4;UTF8:other-identifier

Environment variable: QUARKUS_HTTP_AUTH_CERTIFICATE_ROLE_ATTRIBUTE

Show more

string

CN

quarkus.http.auth.certificate-role-properties

Properties file containing the client certificate attribute value to role mappings. Use it only if the mTLS authentication mechanism is enabled with either quarkus.http.ssl.client-auth=required or quarkus.http.ssl.client-auth=request.

Properties file is expected to have the CN_VALUE=role1,role,…​,roleN format and should be encoded using UTF-8.

Environment variable: QUARKUS_HTTP_AUTH_CERTIFICATE_ROLE_PROPERTIES

Show more

path

quarkus.http.auth.realm

The authentication realm

Environment variable: QUARKUS_HTTP_AUTH_REALM

Show more

string

quarkus.http.auth.form.login-page

The login page. Redirect to login page can be disabled by setting quarkus.http.auth.form.login-page=.

Environment variable: QUARKUS_HTTP_AUTH_FORM_LOGIN_PAGE

Show more

string

/login.html

quarkus.http.auth.form.username-parameter

The username field name.

Environment variable: QUARKUS_HTTP_AUTH_FORM_USERNAME_PARAMETER

Show more

string

j_username

quarkus.http.auth.form.password-parameter

The password field name.

Environment variable: QUARKUS_HTTP_AUTH_FORM_PASSWORD_PARAMETER

Show more

string

j_password

quarkus.http.auth.form.error-page

The error page. Redirect to error page can be disabled by setting quarkus.http.auth.form.error-page=.

Environment variable: QUARKUS_HTTP_AUTH_FORM_ERROR_PAGE

Show more

string

/error.html

quarkus.http.auth.form.landing-page

The landing page to redirect to if there is no saved page to redirect back to. Redirect to landing page can be disabled by setting quarkus.http.auth.form.landing-page=.

Environment variable: QUARKUS_HTTP_AUTH_FORM_LANDING_PAGE

Show more

string

/index.html

quarkus.http.auth.form.location-cookie

Option to control the name of the cookie used to redirect the user back to the location they want to access.

Environment variable: QUARKUS_HTTP_AUTH_FORM_LOCATION_COOKIE

Show more

string

quarkus-redirect-location

quarkus.http.auth.form.timeout

The inactivity (idle) timeout

When inactivity timeout is reached, cookie is not renewed and a new login is enforced.

Environment variable: QUARKUS_HTTP_AUTH_FORM_TIMEOUT

Show more

Duration 

PT30M

quarkus.http.auth.form.new-cookie-interval

How old a cookie can get before it will be replaced with a new cookie with an updated timeout, also referred to as "renewal-timeout".

Note that smaller values will result in slightly more server load (as new encrypted cookies will be generated more often); however, larger values affect the inactivity timeout because the timeout is set when a cookie is generated.

For example if this is set to 10 minutes, and the inactivity timeout is 30m, if a user’s last request is when the cookie is 9m old then the actual timeout will happen 21m after the last request because the timeout is only refreshed when a new cookie is generated.

That is, no timeout is tracked on the server side; the timestamp is encoded and encrypted in the cookie itself, and it is decrypted and parsed with each request.

Environment variable: QUARKUS_HTTP_AUTH_FORM_NEW_COOKIE_INTERVAL

Show more

Duration 

PT1M

quarkus.http.auth.form.cookie-name

The cookie that is used to store the persistent session

Environment variable: QUARKUS_HTTP_AUTH_FORM_COOKIE_NAME

Show more

string

quarkus-credential

quarkus.http.auth.form.cookie-path

The cookie path for the session and location cookies.

Environment variable: QUARKUS_HTTP_AUTH_FORM_COOKIE_PATH

Show more

string

/

quarkus.http.auth.form.http-only-cookie

Set the HttpOnly attribute to prevent access to the cookie via JavaScript.

Environment variable: QUARKUS_HTTP_AUTH_FORM_HTTP_ONLY_COOKIE

Show more

ブーリアン

false

quarkus.http.auth.form.cookie-same-site

SameSite attribute for the session and location cookies.

Environment variable: QUARKUS_HTTP_AUTH_FORM_COOKIE_SAME_SITE

Show more

strict, lax, none

strict

quarkus.http.auth.form.cookie-max-age

Max-Age attribute for the session cookie. This is the amount of time the browser will keep the cookie.

The default value is empty, which means the cookie will be kept until the browser is closed.

Environment variable: QUARKUS_HTTP_AUTH_FORM_COOKIE_MAX_AGE

Show more

Duration 

quarkus.http.auth.inclusive

Require that all registered HTTP authentication mechanisms must attempt to verify the request credentials.

By default, when the inclusive-mode is strict, every registered authentication mechanism must produce SecurityIdentity, otherwise, a number of mechanisms which produce the identity may be less than a total number of registered mechanisms.

All produced security identities can be retrieved using the following utility method:

`io.quarkus.vertx.http.runtime.security.HttpSecurityUtils++#++getSecurityIdentities(io.quarkus.security.identity.SecurityIdentity)`

An injected SecurityIdentity represents an identity produced by the first inclusive authentication mechanism. When the mTLS authentication is required, the mTLS mechanism is always the first mechanism, because its priority is elevated when inclusive authentication

This property is false by default which means that the authentication process is complete as soon as the first SecurityIdentity is created.

This property will be ignored if the path specific authentication is enabled.

Environment variable: QUARKUS_HTTP_AUTH_INCLUSIVE

Show more

ブーリアン

false

quarkus.http.auth.inclusive-mode

Inclusive authentication mode.

Environment variable: QUARKUS_HTTP_AUTH_INCLUSIVE_MODE

Show more

laxAuthentication succeeds if at least one of the registered HTTP authentication mechanisms creates the identity., strictAuthentication succeeds if all the registered HTTP authentication mechanisms create the identity. Typically, inclusive authentication should be in the strict mode when the credentials are carried over mTLS, when both mTLS and another authentication, for example, OIDC bearer token authentication, must succeed. In such cases, SecurityIdentity created by the first mechanism, mTLS, can be injected, identities created by other mechanisms will be available on SecurityIdentity.

strictAuthentication succeeds if all the registered HTTP authentication mechanisms create the identity. Typically, inclusive authentication should be in the strict mode when the credentials are carried over mTLS, when both mTLS and another authentication, for example, OIDC bearer token authentication, must succeed. In such cases, SecurityIdentity created by the first mechanism, mTLS, can be injected, identities created by other mechanisms will be available on SecurityIdentity.
期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。 詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます：

  • 数値の後に h 、 m 、 s が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

相互 TLS 認証

Quarkus には相互 TLS (mTLS) 認証があり、X.509 証明書に基づいてユーザーを認証することができます。

この認証方法を使用するには、まずアプリケーションで SSL/TLS を有効にする必要があります。 詳細は、Quarkus ガイド "HTTP リファレンス" の Supporting secure connections with SSL/TLS を参照してください。

アプリケーションがセキュアな接続を受け入れたら、次のステップは、アプリケーションが信頼するすべての証明書を保持するファイルの名前を使用して quarkus.http.ssl.certificate.trust-store-file プロパティーを設定することです。このファイルには、ブラウザーや他のサービスなどのクライアントが保護されたリソースの 1 つにアクセスしようとしたときに、アプリケーションが証明書を要求する方法に関する情報も含まれています。

JKS は Quarkus のデフォルトのキーストアおよびトラストストア形式ではなくなったため、Quarkus のフレームワークはファイル拡張子に基づいて推測を行います。

  • .pem、 .crt、および .key は PEM 証明書および鍵として読み取られます。

  • .jks、 .keystore、および .truststore は、JKS キーストアおよびトラストストアとして読み取られます。

  • .p12、 .pkcs12、および .pfx は、PKCS12 キーストアおよびトラストストアとして読み取られます。

ファイルでこれらの拡張子が使用されていない場合は、次のプロパティーを使用して形式を設定する必要があります。

quarkus.http.ssl.certificate.key-store-file-type=JKS  # or P12 or PEM
quarkus.http.ssl.certificate.trust-store-file-type=JKS  # or P12 or PEM

JKS は、あまり一般的に使用されなくなっています。Java 9 以降、Java のデフォルトのキーストア形式は PKCS12 です。JKS と PKCS12 の最も大きな違いは、JKS が Java 固有のフォーマットであることです。対照的に、PKCS12 は、暗号化された秘密鍵と証明書を保存するための標準化された言語中立的な方法です。

mTLS を有効にするための設定例を次に示します。

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks (1)
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks (2)
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required (3)
quarkus.http.auth.permission.default.paths=/* (4)
quarkus.http.auth.permission.default.policy=authenticated
quarkus.http.insecure-requests=disabled (5)
1 サーバーの秘密鍵が保存されているキーストア。
2 信頼済み証明書がロードされるトラストストア。
3 quarkus.http.ssl.client-auth を required に設定すると、サーバーがクライアント証明書を要求します。サーバーが証明書なしでリクエストを受け入れる必要がある場合は、これを REQUEST に設定できます。この設定は、mTLS 以外の複数の認証方法をサポートする場合に便利です。
4 認証されたユーザーのみがアプリケーションのリソースにアクセスできるようにするポリシーを定義します。
5 プレーン HTTP プロトコルを無効にし、すべてのリクエストで HTTPS を使用するように要求します。 quarkus.http.ssl.client-auth を required に設定すると、 quarkus.http.insecure-requests が自動的に無効になります。

受信リクエストがトラストストア内の有効な証明書と一致する場合、アプリケーションは次のように SecurityIdentity を注入することでサブジェクトを取得できます。

subject の取得
@Inject
SecurityIdentity identity;

@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
    return String.format("Hello, %s", identity.getPrincipal().getName());
}

次の例に示すコードを使用して証明書を取得することもできます。

証明書の取得
import java.security.cert.X509Certificate;
import io.quarkus.security.credential.CertificateCredential;

CertificateCredential credential = identity.getCredential(CertificateCredential.class);
X509Certificate certificate = credential.getCertificate();

証明書属性をロールにマッピングする

クライアント証明書の情報を使用して、Quarkus SecurityIdentity にロールを追加できます。

クライアント証明書のコモンネーム (CN) 属性を確認した後、 SecurityIdentity に新しいロールを追加できます。 新しいロールを追加する最も簡単な方法は、証明書属性をロールにマッピングする機能に使用することです。

たとえば、以下のように 相互 TLS 認証 を紹介するセクションで表示されるプロパティーを更新できます。

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required
quarkus.http.insecure-requests=disabled

quarkus.http.auth.certificate-role-properties=cert-role-mappings.properties (1)

quarkus.http.auth.permission.certauthenticated.paths=/*   (2)
quarkus.http.auth.permission.certauthenticated.policy=role-policy-cert (2)
quarkus.http.auth.policy.role-policy-cert.roles-allowed=user,admin     (2)
1 cert-role-mappings.properties クラスパスリソースには、 CN=role または CN=role1,role2 などの形式で、ロールへの証明書の CN 値のマップが含まれています。ここで、 alice=user,admin、 bob=user、および jdoe=tester の 3 つのエントリーが含まれていると仮定します。
2 HTTP セキュリティーポリシーを使用して、リクエストを認可するには SecurityIdentity に user または admin ロールが必要であることを要求します。

上記の設定では、クライアント証明書の CN 属性が alice または bob の場合にリクエストが承認され、 jdoe の場合はリクエストが拒否されます。

証明書属性を使用して SecurityIdentity を強化する

自動の 証明書属性をロールにマッピングする オプションが適切でない場合は、いつでも SecurityIdentityAugmentor を登録できます。 カスタム SecurityIdentityAugmentor は、さまざまなクライアント証明書属性の値をチェックし、それに応じて SecurityIdentity を拡張できます。

SecurityIdentity のカスタマイズの詳細は、Quarkus "セキュリティーに関するヒントとコツ" ガイドの セキュリティーアイデンティティーのカスタマイズ セクションを参照してください。

その他のサポートされる認証メカニズム

Quarkus Security は、エクステンションによって、以下の認証メカニズムもサポートしています:

WebAuthn 認証

WebAuthn はパスワードに代わる認証メカニズムです。 新規ユーザーの登録やログインを行うサービスを作成する場合、パスワードの入力を求める代わりに WebAuthn を使用することで、パスワードを置き換えることができます。 詳細については、WebAuthn 認証メカニズムを使用した Quarkus アプリケーションの保護 ガイドを参照してください。

OpenID Connect 認証

OpenID Connect (OIDC) は、OAuth 2.0 プロトコル上で動作する ID レイヤーです。 OIDC は、クライアントアプリケーションが OIDC プロバイダーによって実行された認証に基づいてユーザーの身元を確認し、そのユーザーに関する基本情報を取得することを可能にします。

Quarkus の quarkus-oidc エクステンションは、ベアラートークンと認証コードフローの認証メカニズムをサポートする、リアクティブで相互運用可能なマルチテナント対応の OIDC アダプターを提供します。 Bearer トークン認証メカニズムは、HTTP Authorization ヘッダーからトークンを抽出します。

認可コードフローメカニズムは、ユーザーを OIDC プロバイダーにリダイレクトして、ユーザーのアイデンティティーを認証します。 ユーザーが Quarkus にリダイレクトされた後、メカニズムにより ID、アクセストークン、およびリフレッシュトークンに付与された提供コードを交換して認証プロセスを完了します。

リフレッシュ可能な JSON Web Key (JWK) セットを使用して ID を検証し、JSON Web Token (JWT) トークンにアクセスしたり、リモートでそれらをイントロスペクトしたりできます。 ただし、バイナリートークンとも呼ばれる不透明トークンは、リモートでのみイントロスペクトできます。

Quarkus OIDC エクステンションを使用すると、ベアラートークンと認可コードフロー認証メカニズムの両方が SmallRye JWT 認証 を使用して、JWT トークンを MicroProfile JWT org.eclipse.microprofile.jwt.JsonWebToken として表します。

OIDC 認証のための追加の Quarkus リソース

Quarkus アプリケーションの安全性を確保するために使用できる OIDC 認証および認可方法の詳細については、以下のリソースを参照してください:

OIDC トピック Quarkus の情報リソース

ベアラートークン認証メカニズム

OIDC ベアラートークン認証

認可コードフロー認証メカニズム

OpenID Connect (OIDC) 認可コードフローメカニズム

OIDC と SAML アイデンティティーブローカー

OpenID Connect (OIDC) 認可コードフローと SAML アイデンティティーブローカー

ベアラートークン認証または認可コードフローメカニズムをサポートする複数のテナント

OpenID Connect (OIDC) マルチテナントの使用

一般的に使用される OpenID Connect プロバイダーを使用して Quarkus を保護する

よく知られた OpenID Connect プロバイダーの設定

Keycloak を使用した認可の一元化

OpenID Connect (OIDC) と Keycloak を使用して認可を一元化

Keycloak のプログラムによる設定

Keycloak admin クライアントの使用

実行時に Quarkus OIDC エクステンションを有効にするには、ビルド時に quarkus.oidc.tenant-enabled=false を設定します。 続いて、システムプロパティーを使用して実行時に再度有効にします。

マルチテナント OIDC デプロイメントにおける個々のテナント設定の管理に関する詳細は、"OpenID Connect (OIDC) マルチテナントの使用" ガイドの テナント設定の無効化 セクションを参照してください。

OpenID Connect クライアントとフィルター

quarkus-oidc-client エクステンションは、以下のトークングラントをサポートする OpenID Connect および OAuth2 プロバイダーからアクセストークンを取得し、リフレッシュするための OidcClient を提供します。

  • client-credentials

  • password

  • refresh_token

quarkus-resteasy-client-oidc-filter エクステンションには quarkus-oidc-client エクステンションが必要です。 これは、 OidcClient によって取得されたアクセストークンを HTTP Authorization ヘッダーの Bearer スキーム値として設定する JAX-RS RESTful Web サービス OidcClientRequestFilter を提供します。 このフィルターは、現在の Quarkus エンドポイントに注入された MicroProfile REST クライアント実装に登録できますが、このサービスエンドポイントの認証要件とは関係ありません。 たとえば、パブリックエンドポイントにしたり、mTLS で保護したりできます。

このシナリオでは、Quarkus OpenID Connect アダプターを使用して Quarkus エンドポイントを保護する必要はありません。

quarkus-resteasy-client-oidc-token-propagation エクステンションには quarkus-oidc エクステンションが必要です。 これは、OpenID Connect ベアラートークンまたは認可コードフローアクセストークンを HTTP Authorization ヘッダーの Bearer スキーム値として設定する Jakarta REST TokenCredentialRequestFilter を提供します。 このフィルターは、現在の Quarkus エンドポイントに注入された MicroProfile REST クライアント実装に登録できます。これは、Quarkus OIDC アダプターを使用して保護する必要があります。 このフィルターは、アクセストークンをダウンストリームサービスに伝播できます。

詳しくは、OpenID Connect クライアントとトークン伝搬クイックスタート、OpenID Connect (OIDC) と OAuth2 クライアントとフィルターのリファレンス ガイドをご覧ください。

SmallRye JWT 認証

quarkus-smallrye-jwt エクステンションは、MicroProfile JSON Web Token (JWT) 2.1 の実装と、署名および暗号化された JWT トークンを検証する複数のオプションを提供します。 これらは org.eclipse.microprofile.jwt.JsonWebToken として表されます。

quarkus-smallrye-jwt は quarkus-oidc ベアラートークン認証メカニズムの代替となるもので、Privacy Enhanced Mail (PEM) キーまたは更新可能な JWK キーセットのいずれかを使用して JWT トークンのみを検証します。 quarkus-smallrye-jwt は JWT 生成 API も提供しており、これを使用して signed、 inner-signed、および encrypted の JWT トークンを簡単に作成できます。

詳細は、JWT RBAC の使用 ガイドを参照してください。

OAuth2 認証

quarkus-elytron-security-oauth2 は、Quarkus quarkus-oidc ベアラートークン認証メカニズムエクステンションに対する別の選択肢を提供するものです。 quarkus-elytron-security-oauth2 は Elytron に基づいており、主に不透明トークンをリモートでイントロスペクトすることを目的としています。

詳細は、Quarkus OAuth2 の使用 ガイドを参照してください。

OpenID Connect、SmallRye JWT、OAuth2 認証メカニズムからの選択

次の情報を使用して、Quarkus アプリケーションを保護するために適切なトークン認証メカニズムを選択して下さい。

認証メカニズムのユースケースリスト

  • quarkus-oidc には、ベアラートークンを検証したり、認可コードフローでエンドユーザーを認証したりできる Keycloak などの OpenID Connect プロバイダーが必要です。 どちらの場合も、 quarkus-oidc は指定された OpenID Connect プロバイダーへの接続を必要とします。

  • ユーザー認証に認可コードフローが必要な場合、または複数のテナントをサポートする必要がある場合は、 quarkus-oidc を使用してください。 quarkus-oidc は、認可コードフローとベアラーアクセストークンの両方を使用して、ユーザー情報を要求することもできます。

  • ベアラートークンを検証する必要がある場合は、 quarkus-oidc、 quarkus-elytron-security-oauth2、または quarkus-smallrye-jwt を使用します。

  • ベアラートークンが JSON Web トークン (JWT) 形式である場合は、上記のリストにある任意のエクステンションを使用できます。 quarkus-oidc と quarkus-smallrye-jwt はどちらも、OpenID Connect プロバイダーがキーをローテーションするときに設定された JsonWebKey (JWK) の更新をサポートしています。 したがって、リモートトークンイントロスペクションを回避する必要がある場合やプロバイダーがこれをサポートしていない場合は、 quarkus-oidc または quarkus-smallrye-jwt を使用して JWT トークンを検証します。

  • JWT トークンをリモートでイントロスペクトするには、 quarkus-oidc を使用できます。 または quarkus-elytron-security-oauth2 リモートイントロスペクションを使用して不透明トークンまたはバイナリートークンを検証します。 quarkus-smallrye-jwt は、不透明トークンと JWT トークンの両方のリモートイントロスペクションをサポートしていませんが、代わりに、通常は OpenID Connect プロバイダーから取得されるローカルで利用可能なキーに依存します。

  • quarkus-oidc と quarkus-smallrye-jwt は、エンドポイントコードへの JWT と不透明トークンの注入をサポートします。 注入された JWT トークンは、ユーザーに関する詳細情報を提供します。 すべてのエクステンションには、トークンを Principal として注入できます。

  • quarkus-smallrye-jwt は quarkus-oidc よりも多くの鍵フォーマットをサポートしています。 quarkus-oidc は JWK セットの一部である JWK 形式の鍵のみを使用するのに対し、 quarkus-smallrye-jwt は PEM 鍵をサポートしています。

  • quarkus-smallrye-jwt は、ローカルで署名されたトークン、内部で署名および暗号化されたトークン、および暗号化されたトークンを処理します。 対照的に、 quarkus-oidc と quarkus-elytron-security-oauth2 もそのようなトークンを検証できますが、それらを不透明トークンとして扱い、リモートイントロスペクションを通じて検証します。

  • 不透明トークンや JWT トークンのリモートイントロスペクションのための軽量なライブラリーが必要な場合は、 quarkus-elytron-security-oauth2 を使用してください。

トークン形式として、不透明トークンか JSON Web トークン (JWT) のどちらを使用するかは、アーキテクチャーの検討によって決定されます。 不透明トークンは JWT トークンよりもはるかに短い傾向がありますが、トークンに関連する状態のほとんどをプロバイダーのデータベースで維持する必要があります。 不透明トークンは、事実上データベースポインターです。

JWT トークンは不透明トークンよりも大幅に長くなります。 その場合もプロバイダーは、トークンクレームとしてトークン関連の状態を保存し、それに署名するか暗号化することで、トークン関連の状態の大部分をクライアントに効果的に委譲します。
Table 2. トークン認証メカニズムの比較
必要な機能 認証メカニズム

quarkus-oidc

quarkus-smallrye-jwt

quarkus-elytron-security-oauth2

ベアラー JWT の検証

ローカル検証もしくはイントロスペクション

ローカル検証

イントロスペクション

ベアラー不透明トークンの検証

イントロスペクション

不可

イントロスペクション

JWT トークン検証用の JsonWebKey セットの更新

可

可

不可

トークンを Principal として表現

可

可

可

MP JWTとして JWT をインジェクト

可

可

不可

認可コードフロー

可

不可

不可

マルチテナンシー

可

不可

不可

ユーザー情報のサポート

可

不可

不可

PEM キーフォーマットサポート

不可

可

不可

SecretKey のサポート

不可

JSON Web Key (JWK) 形式

不可

内部署名付き暗号化トークン、または暗号化トークン

イントロスペクション

ローカル検証

イントロスペクション

カスタムトークン検証

不可

注入された JWT パーサーを使用

不可

Cookie としての JWT のサポート

不可

可

可

認証メカニズムの組み合わせ

異なるソースからユーザー認証情報が提供される場合は、認証メカニズムを組み合わせることができます。 たとえば、組み込みの Basic 認証メカニズムと Quarkus の quarkus-oidc べアラートークン認証メカニズムを組み合わせることができます。

認証メカニズムの 1 つによって最初の SecurityIdentity が生成されるとすぐに、認証プロセスが完了します。

統合認証

場合によっては、登録されているすべての認証メカニズムが SecurityIdentity を作成することが必要になることがあります。 これは、トークンなどの認証情報を 相互 TLS 認証 経由で渡す必要がある場合に必要になることがあります。 たとえば、ユーザーが Virtual Private Network 経由で認証している場合や、トークンの検証を成功させるために現在のトークンをクライアント証明書にバインドして、このトークンをクライアント証明書とともに Quarkus に渡している同じクライアントにトークンが正確に発行されたことを保証する場合などです。

Quarkus では、このような認証は inclusive (統合認証) と呼ばれ、次のようにして有効にできます。

quarkus.http.auth.inclusive=true

認証が統合認証である場合、最初の認証メカニズムによって作成された SecurityIdentity は アプリケーションコードに挿入されます。 たとえば、相互 TLS 認証 と基本的な認証メカニズムの認証が必要な場合、相互 TLS 認証 メカニズムが最初に SecurityIdentity を作成します。

統合認証が有効になっている場合、相互 TLS 認証 メカニズムが最も優先され、注入された SecurityIdentity が常に 相互 TLS 認証 を表し、他の認証メカニズムによって提供される SecurityIdentity アイデンティティーにアクセスするために使用できるようになります。

追加の SecurityIdentity インスタンスには、最初の SecurityIdentity の quarkus.security.identities 属性としてアクセスできます。しかし、これらの追加のアイデンティティーに直接アクセスする必要がない場合があります。たとえば、相互 TLS 認証 と OIDC ベアラー認証 メカニズムの両方が組み合わされて認証が行われている場合、認証されたベアラートークンは、相互 TLS 認証 によって作成された SecurityIdentity とともにトークン認証情報として注入できます。以下に例を示します。

package org.acme.security;

import io.quarkus.oidc.AccessTokenCredential;
import io.quarkus.oidc.common.runtime.OidcConstants;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.vertx.http.runtime.security.HttpSecurityUtils;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
public class InclusiveAuthExampleBean {

    @Inject
    SecurityIdentity mtlsIdentity;  (1)

    @Inject
    AccessTokenCredential accessTokenCredential;

    private AccessTokenCredential getAccessTokenCredential() {
        if (doItHardWay()) {
            var securityIdentities = HttpSecurityUtils.getSecurityIdentities(mtlsIdentity);    (2)
            if (securityIdentities != null) {
                SecurityIdentity bearerIdentity = securityIdentities.get(OidcConstants.BEARER_SCHEME);
                if (bearerIdentity != null) {
                    return bearerIdentity.getCredential(AccessTokenCredential.class);
                }
            }
        }
        return accessTokenCredential;
    }

}
1 これは、該当する認証メカニズムによって作成された、最高の優先度を持つ SecurityIdentity です。
2 その他の該当する認証メカニズムは認証を実行し、 SecurityIdentity で利用できます。

Quarkus quarkus-oidc ベアラートークンと smallrye-jwt 認証メカニズムは、両方とも HTTP ベアラートークン認証スキームから抽出されたトークンを検証しようとするため、この 2 つを組み合わせることはできません。

パスベースの認証

HTTP セキュリティーポリシーを使用してパスベース認証を有効にする

次の設定例は、あるリクエストパスに対して、選択可能な単一の認証メカニズムを強制する方法を示しています:

quarkus.http.auth.permission.basic-or-bearer.paths=/service
quarkus.http.auth.permission.basic-or-bearer.policy=authenticated

quarkus.http.auth.permission.basic.paths=/basic-only
quarkus.http.auth.permission.basic.policy=authenticated
quarkus.http.auth.permission.basic.auth-mechanism=basic

quarkus.http.auth.permission.bearer.paths=/bearer-only
quarkus.http.auth.permission.bearer.policy=authenticated
quarkus.http.auth.permission.bearer.auth-mechanism=bearer

auth-mechanism プロパティーの値が、 HttpAuthenticationMechanism がサポートする認証スキーム (たとえば、 basic、 bearer、または form) と一致していることを確認します。

アノテーションを使用して Jakarta REST エンドポイントのパスベース認証を有効にする

アノテーションを使用して、各 Jakarta REST エンドポイントに固有の認証メカニズムを選択できます。 この機能は、REST エンドポイントが一致した後にのみ、 認証メカニズムを選択するためにアノテーションを使用できることから、プロアクティブ認証 が無効化されている場合に限り、有効化されます。 REST エンドポイントごとに認証メカニズムを選択する方法は次のとおりです。

quarkus.http.auth.proactive=false
import io.quarkus.oidc.AuthorizationCodeFlow;
import io.quarkus.vertx.http.runtime.security.annotation.BasicAuthentication;
import jakarta.annotation.security.RolesAllowed;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("hello")
public class HelloResource {

    @GET
    @BasicAuthentication (1) (2)
    @Path("basic")
    public String basicAuthMechanism() {
        return "basic";
    }

    @GET
    @RolesAllowed("admin") (3)
    @AuthorizationCodeFlow (4)
    @Path("code-flow")
    public String codeFlowAuthMechanism() {
        return "code-flow";
    }
}
1 REST エンドポイント /hello/basic には、Basic 認証 を使用する場合のみアクセスできます。
2 @BasicAuthentication アノテーションに標準のセキュリティーアノテーションが付属していない場合は、デフォルトで @Authenticated アノテーションが追加されるため、このエンドポイントには認証が必要です。
3 @AuthorizationCodeFlow アノテーションは、 @RolesAllowed や @PermissionsAllowed などの他の標準セキュリティーアノテーションと組み合わせることができます。
4 REST エンドポイント /hello/code-flow には、OIDC 認可コードフローメカニズム を使用する場合のみアクセスできます。
Table 3. サポートされる認証メカニズムのアノテーション
認証メカニズム^ アノテーション

Basic 認証メカニズム

io.quarkus.vertx.http.runtime.security.annotation.BasicAuthentication

フォームベース認証メカニズム

io.quarkus.vertx.http.runtime.security.annotation.FormAuthentication

相互 TLS 認証メカニズム

io.quarkus.vertx.http.runtime.security.annotation.MTLSAuthentication

WebAuthn 認証メカニズム

io.quarkus.security.webauthn.WebAuthn

ベアラートークン認証メカニズム

io.quarkus.oidc.BearerTokenAuthentication

OIDC 認可コードフローメカニズム

io.quarkus.oidc.AuthorizationCodeFlow

SmallRye JWT 認証メカニズム

io.quarkus.smallrye.jwt.runtime.auth.BearerTokenAuthentication
Quarkus は、認証メカニズムアノテーションが付けられたエンドポイントを自動的に保護します。REST エンドポイントとリソースに標準のセキュリティーアノテーションが存在しない場合は、 io.quarkus.security.Authenticated アノテーションが追加されます。

また、 io.quarkus.vertx.http.runtime.security.annotation.HttpAuthenticationMechanism アノテーションを使用して、そのスキームに基づいて任意の認証メカニズムを選択することも可能です。 quarkus.http.auth.permission.basic.auth-mechanism=custom 設定プロパティーに類似するアノテーションとして、 @HttpAuthenticationMechanism("custom") アノテーションがあります。

さまざまな Jakarta EE 仕様との整合性を保つために、アノテーションの継承に依存するのではなく、常にアノテーションを繰り返すことが推奨されます。

パスベースの認証を有効にするには、統合認証を使用します。

デフォルトでは、Quarkus はパスごとに 1 つの認証メカニズムに対してのみ パスベースの認証 をサポートします。 パスベースの認証に複数の認証メカニズムを使用する必要がある場合は、「セキュリティに関するヒントとコツ」ガイドの 複数の HttpAuthenticationMechanism の処理 セクションに記載されているように、カスタムの HttpAuthenticationMechanism を記述できます。 もう 1 つの方法は、lax モードで 統合認証 を有効にし、登録されているすべての HTTP 認証メカニズムがメカニズム固有の SecurityIdentity を作成したことを確認するカスタムの HttpSecurityPolicy または PermissionChecker を記述することです。

lax モードでの統合認証の有効化
quarkus.http.auth.inclusive-mode=lax (1)
quarkus.http.auth.inclusive=true
1 デフォルトでは、統合認証では、登録されているすべての HTTP 認証メカニズムが SecurityIdentity を作成する必要があります。 ただし、lax モードでは、少なくとも 1 つの登録済み HttpAuthenticationMechanism が SecurityIdentity を作成すると、認証が成功します。

mTLS、Basic、OIDC の 3 つの登録済みメカニズムがあり、 hello メソッドへのアクセスを許可するのに Basic 認証と mTLS 認証のみが成功する必要があると仮定します。 この場合、統合認証を lax モードで有効にすると、次の例に示すように、どのメカニズムがアイデンティティーを生成したかを確認できます。

HTTP 認証メカニズムの確認の例
import io.quarkus.security.PermissionChecker;
import io.quarkus.security.PermissionsAllowed;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.vertx.http.runtime.security.HttpSecurityUtils;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import java.util.Map;

@Path("/hello")
public class HelloResource {

    @PermissionsAllowed("mtls-basic")
    @GET
    public String hello() {
        return "Hello world";
    }

    @PermissionChecker("mtls-basic")
    boolean isMtlsAndBasicAuthentication(SecurityIdentity identity) {
        Map<String, SecurityIdentity> identities = HttpSecurityUtils.getSecurityIdentities(identity);
        if (identities != null) {
            return identities.containsKey("basic") && identities.containsKey("x509"); (1)
        }
        return false;
    }
}
1 mTLS と Basic の両方の認証メカニズムが現在のリクエストを認証したことが確認された場合にのみ、エンドポイントへのアクセスを許可します。

HTTP セキュリティーポリシーとの組み合わせ方法

個々のリソースにアクセスできるロールを定義する最も簡単な方法は、 @RolesAllowed アノテーションを使用することです。 ただし、次の例のように HTTP セキュリティーポリシーを使用することもできます。

quarkus.http.auth.policy.roles1.roles-allowed=user
quarkus.http.auth.permission.roles1.paths=/hello/code-flow
quarkus.http.auth.permission.roles1.applies-to=JAXRS (1)
quarkus.http.auth.permission.roles1.policy=roles1
quarkus.http.auth.permission.roles1.methods=GET (2)
1 エンドポイント固有の認証メカニズムの選択後、このポリシーの権限チェックを遅らせます。
2 roles1 権限が、 @AuthorizationCodeFlow アノテーションが付けられたエンドポイントのみと一致するようにします。 アノテーションが付いていないエンドポイントは、 applies-to=JAXRS オプションによって発生する遅延を回避する必要があります。

プロアクティブ認証

Quarkusでは、デフォルトでプロアクティブ認証が有効になっています。 受信リクエストに認証情報がある場合、ターゲットページで認証が必要ない場合でも、リクエストは常に認証されます。 詳細については、Quarkus の プロアクティブ認証 ガイドを参照してください。

参照

関連コンテンツ

同じトピックについて

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

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

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