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

Quarkusの認証メカニズム

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

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

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

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

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

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

ユーザー名とパスワード

Basic, フォームベース認証

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

OIDCベアラートークン認証JWTOAuth2

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

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

クライアント証明書

相互TLS認証

WebAuthn

WebAuthn

ケルベロスチケット

Kerberos

For more information, see the following トークン認証メカニズムの比較 table.

組込認証メカニズム

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

Basic認証

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

フォームベース認証

Quarkus provides form-based authentication that works similarly to traditional Servlet form-based authentication. Unlike traditional form authentication, the authenticated user is not stored in an HTTP session because Quarkus does not support clustered HTTP sessions. Instead, the authentication information is stored in an encrypted cookie, which can be read by all cluster members who share the same encryption key.

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

To get started with form authentication, you should have similar settings as described in Enable Basic authentication and property quarkus.http.auth.form.enabled must be set to true.

Simple application.properties with form-base authentication can look similar to this:

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

Configuring user names, secrets, and roles in the application.properties file is appropriate only for testing scenarios. For securing a production application, it is crucial to use a database or LDAP to store this information. For more information you can take a look at Quarkus Security with Jakarta Persistence or other mentioned in Enable Basic authentication.

and application login page will contain HTML form similar to this:

<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

Now that you have disabled redirects for the SPA, you must log in and log out programmatically from your client. Below are examples of JavaScript methods for logging into the j_security_check endpoint and logging out of the application by destroying the cookie.

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);
    });
};

To log out of the SPA from the client, the cookie must be set to quarkus.http.auth.form.http-only-cookie=false so you can destroy the cookie and possibly redirect back to your main page.

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
};

To log out of the SPA from the server, the cookie can be set to quarkus.http.auth.form.http-only-cookie=true and use this example code to destroy the cookie.

@ConfigProperty(name = "quarkus.http.auth.form.cookie-name")
String cookieName;

@Inject
CurrentIdentityAssociation identity;

@POST
public Response logout() {
    if (identity.getIdentity().isAnonymous()) {
        throw new UnauthorizedException("Not authenticated");
    }
    final NewCookie removeCookie = new NewCookie.Builder(cookieName)
            .maxAge(0)
            .expiry(Date.from(Instant.EPOCH))
            .path("/")
            .build();
    return Response.noContent().cookie(removeCookie).build();
}

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

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

Configuration property

デフォルト

If form authentication is enabled.

Environment variable: QUARKUS_HTTP_AUTH_FORM_ENABLED

Show more

boolean

false

The post location.

Environment variable: QUARKUS_HTTP_AUTH_FORM_POST_LOCATION

Show more

string

/j_security_check

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property

タイプ

デフォルト

Properties file containing the client certificate common name (CN) 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=role1,role,…​,roleN format and should be encoded using UTF-8.

Environment variable: QUARKUS_HTTP_AUTH_CERTIFICATE_ROLE_PROPERTIES

Show more

path

The authentication realm

Environment variable: QUARKUS_HTTP_AUTH_REALM

Show more

string

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

The username field name.

Environment variable: QUARKUS_HTTP_AUTH_FORM_USERNAME_PARAMETER

Show more

string

j_username

The password field name.

Environment variable: QUARKUS_HTTP_AUTH_FORM_PASSWORD_PARAMETER

Show more

string

j_password

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

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

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

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

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

The cookie that is used to store the persistent session

Environment variable: QUARKUS_HTTP_AUTH_FORM_COOKIE_NAME

Show more

string

quarkus-credential

The cookie path for the session and location cookies.

Environment variable: QUARKUS_HTTP_AUTH_FORM_COOKIE_PATH

Show more

string

/

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

Environment variable: QUARKUS_HTTP_AUTH_FORM_HTTP_ONLY_COOKIE

Show more

boolean

false

SameSite attribute for the session and location cookies.

Environment variable: QUARKUS_HTTP_AUTH_FORM_COOKIE_SAME_SITE

Show more

strict, lax, none

strict

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

boolean

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

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

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

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

Environment variable: QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__AUTH_MECHANISM

Show more

string

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

boolean

false

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

all

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

**

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

List

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

List

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

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

List

期間フォーマットについて

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

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

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

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

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

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

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

相互TLS認証

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

To use this authentication method, you must first enable SSL/TLS for your application. For more information, see the Supporting secure connections with SSL/TLS section of the Quarkus "HTTP reference" guide.

After your application accepts secure connections, the next step is to configure the quarkus.http.ssl.certificate.trust-store-file property with the name of that file that holds all the certificates your application trusts. The specified file also includes information about how your application asks for certificates when a client, such as a browser or other service, tries to access one of its protected resources.

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 The keystore where the server’s private key is located.
2 The truststore from which the trusted certificates are loaded.
3 With the value set to required, the server demands client certificates. Set the value to REQUEST to allow the server to accept requests without a certificate. This setting is beneficial when supporting authentication methods besides mTLS.
4 認証されたユーザーのみがアプリケーションからリソースにアクセスできるようにするポリシーを定義します。
5 You can explicitly disable the plain HTTP protocol, thus requiring all requests to use HTTPS. When you set quarkus.http.ssl.client-auth to required, the system automatically sets quarkus.http.insecure-requests to disabled.

When the incoming request matches a valid certificate in the truststore, your application can obtain the subject by injecting a SecurityIdentity as follows:

subjectの取得
@Inject
SecurityIdentity identity;

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

You can also get the certificate by using the code outlined in the following example:

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

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

Mapping certificate attributes to roles

The information from the client certificate can be used to add roles to Quarkus SecurityIdentity.

You can add new roles to SecurityIdentity after checking a client certificate’s common name (CN) attribute. The easiest way to add new roles is to use a certificate attribute to role mapping feature.

For example, you can update the properties shown in the section which introduces 相互TLS認証 as follows:

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 The cert-role-mappings.properties classpath resource contains a map of certificate’s CN values to roles in the form CN=role or CN=role1,role2, etc. Let’s assume it contains three entries: alice=user,admin, bob=user and jdoe=tester.
2 Use HTTP security policy to require that SecurityIdentity must have either user or admin roles for the requests to be authorized.

Given the preceeding configuration, the request is authorized if the client certificate’s CN attribute is equal to alice or bob and forbidden if it is equal to jdoe.

Using certificate attributes to augment SecurityIdentity

You can always register SecurityIdentityAugmentor if the automatic Mapping certificate attributes to roles option does not suit. Custom SecurityIdentityAugmentor can check the values of different client certificate attributes and augment the SecurityIdentity accordingly.

For more information about customizing SecurityIdentity, see the Security identity customization section in the Quarkus "Security tips and tricks" guide.

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

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

WebAuthn認証

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

OpenID Connect 認証

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

The Quarkus quarkus-oidc extension provides a reactive, interoperable, multitenant-enabled OIDC adapter that supports Bearer token and Authorization Code Flow authentication mechanisms. The Bearer token authentication mechanism extracts the token from the HTTP Authorization header.

The Authorization Code Flow mechanism redirects the user to an OIDC provider to authenticate the user’s identity. After the user is redirected back to Quarkus, the mechanism completes the authentication process by exchanging the provided code that was granted for the ID, access, and refresh tokens.

You can verify ID and access JSON Web Token (JWT) tokens by using the refreshable JSON Web Key (JWK) set or introspect them remotely. However, opaque, also known as binary tokens, can only be introspected remotely.

Using the Quarkus OIDC extension, both the Bearer token and Authorization Code Flow authentication mechanisms use SmallRye JWT 認証 to represent JWT tokens as 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)マルチテナントの使用

Securing Quarkus with commonly used OpenID Connect providers

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

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

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

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

Keycloak admin クライアントの使用

To enable the Quarkus OIDC extension at runtime, set quarkus.oidc.tenant-enabled=false at build time. Then, re-enable it at runtime by using a system property.

For more information about managing the individual tenant configurations in multitenant OIDC deployments, see the Disabling tenant configurations section in the "Using OpenID Connect (OIDC) multi-tenancy" guide.

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

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

  • client-credentials

  • password

  • refresh_token

The quarkus-resteasy-client-oidc-filter extension requires the quarkus-oidc-client extension. It provides JAX-RS RESTful Web Services OidcClientRequestFilter, which sets the access token acquired by OidcClient as the Bearer scheme value of the HTTP Authorization header. This filter can be registered with MicroProfile REST client implementations injected into the current Quarkus endpoint, but it is not related to the authentication requirements of this service endpoint. For example, it can be a public endpoint or be protected with mTLS.

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

The quarkus-resteasy-client-oidc-token-propagation extension requires the quarkus-oidc extension. It provides Jakarta REST TokenCredentialRequestFilter, which sets the OpenID Connect Bearer token or Authorization Code Flow access token as the Bearer scheme value of the HTTP Authorization header. This filter can be registered with MicroProfile REST client implementations injected into the current Quarkus endpoint, which must be protected by using the Quarkus OIDC adapter. This filter can propagate the access token to the downstream services.

SmallRye JWT 認証

The quarkus-smallrye-jwt extension provides a MicroProfile JSON Web Token (JWT) 2.1 implementation and multiple options to verify signed and encrypted JWT tokens. It represents them as org.eclipse.microprofile.jwt.JsonWebToken.

quarkus-smallrye-jwt is an alternative to the quarkus-oidc Bearer token authentication mechanism and verifies only JWT tokens by using either Privacy Enhanced Mail (PEM) keys or the refreshable JWK key set. quarkus-smallrye-jwt also provides the JWT generation API, which you can use to easily create signed, inner-signed, and encrypted JWT tokens.

For more information, see the Using JWT RBAC guide.

OAuth2 認証

quarkus-elytron-security-oauth2 provides an alternative to the Quarkus quarkus-oidc Bearer token authentication mechanism extension. quarkus-elytron-security-oauth2 is based on Elytron and is primarily intended for introspecting opaque tokens remotely.

For more information, see the Quarkus Using OAuth2 guide.

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

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

List of authentication mechanism use cases
  • quarkus-oidc requires an OpenID Connect provider such as Keycloak, which can verify the bearer tokens or authenticate the end users with the Authorization Code flow. In both cases, quarkus-oidc requires a connection to the specified OpenID Connect provider.

  • If the user authentication requires Authorization Code flow, or you need to support multiple tenants, use quarkus-oidc. quarkus-oidc can also request user information by using both Authorization Code Flow and Bearer access tokens.

  • If your bearer tokens must be verified, use quarkus-oidc, quarkus-smallrye-jwt, or quarkus-elytron-security-oauth2.

  • If your bearer tokens are in a JSON web token (JWT) format, you can use any extensions in the preceding list. Both quarkus-oidc and quarkus-smallrye-jwt support refreshing the JsonWebKey (JWK) set when the OpenID Connect provider rotates the keys. Therefore, if remote token introspection must be avoided or is unsupported by the providers, use quarkus-oidc or quarkus-smallrye-jwt to verify JWT tokens.

  • To introspect the JWT tokens remotely, you can use either quarkus-oidc or quarkus-elytron-security-oauth2 because they support verifying the opaque or binary tokens by using remote introspection. quarkus-smallrye-jwt does not support the remote introspection of both opaque or JWT tokens but instead relies on the locally available keys that are usually retrieved from the OpenID Connect provider.

  • quarkus-oidc and quarkus-smallrye-jwt support the JWT and opaque token injection into the endpoint code. Injected JWT tokens provide more information about the user. All extensions can have the tokens injected as Principal.

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

  • quarkus-smallrye-jwt handles locally signed, inner-signed-and-encrypted, and encrypted tokens. In contrast, although quarkus-oidc and quarkus-elytron-security-oauth2 can also verify such tokens, they treat them as opaque tokens and verify them through remote introspection.

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

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

JWT tokens are significantly longer than opaque tokens. Nonetheless, the providers effectively delegate most of the token-associated state to the client by storing it as the token claims and either signing or encrypting them.

Table 2. トークン認証メカニズムの比較
必要な機能 認証メカニズム

quarkus-oidc

quarkus-smallrye-jwt

quarkus-elytron-security-oauth2

ベアラーJWTの検証

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

ローカル検証

イントロスペクション

ベアラー不透明Tokenの検証

イントロスペクション

No

イントロスペクション

Refreshing JsonWebKey set to verify JWT tokens

Yes

Yes

No

トークンを Principal として表現

Yes

Yes

Yes

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

Yes

Yes

No

認可コードフロー

Yes

No

No

マルチテナンシー

Yes

No

No

ユーザー情報のサポート

Yes

No

No

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

No

Yes

No

SecretKey のサポート

No

JSON Web Key(JWK)フォーマットで

No

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

イントロスペクション

ローカル検証

イントロスペクション

カスタムトークン検証

No

注入されたJWTパーサーで

No

クッキーとしてのJWTのサポート

No

Yes

Yes

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

If different sources provide the user credentials, you can combine authentication mechanisms. For example, you can combine the built-in Basic and the Quarkus quarkus-oidc Bearer token authentication mechanisms.

You cannot combine the Quarkus quarkus-oidc Bearer token and smallrye-jwt authentication mechanisms because both mechanisms attempt to verify the token extracted from the HTTP Bearer token authentication scheme.

Use HTTP Security Policy to enable path-based authentication

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

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 がサポートする認証スキーム(例えば、 basicbearerform )と一致しているようにして下さい。

Use annotations to enable path-based authentication for Jakarta REST endpoints

It is possible to use annotations to select an authentication mechanism specific to each Jakarta REST endpoint. This feature is only enabled when プロアクティブ認証 is disabled due to the fact that the annotations can only be used to select authentication mechanisms after a REST endpoint has been matched. Here is how you can select an authentication mechanism per a REST endpoint basis:

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 The REST endpoint /hello/basic can only ever be accessed by using the Basic認証.
2 This endpoint requires authentication, because when no standard security annotation accompanies the @BasicAuthentication annotation, the @Authenticated annotation is added by default.
3 The @AuthorizationCodeFlow annotation can be combined with any other standard security annotation like @RolesAllowed, @PermissionsAllowed and others.
4 The REST endpoint /hello/code-flow can only ever be accessed by using the OIDC authorization code flow mechanism.
Table 3. Supported authentication mechanism annotations
Authentication mechanism^ アノテーション

Basic authentication mechanism

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

Form-based authentication mechanism

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

Mutual TLS authentication mechanism

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

WebAuthn authentication mechanism

io.quarkus.security.webauthn.WebAuthn

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

io.quarkus.oidc.BearerTokenAuthentication

OIDC authorization code flow mechanism

io.quarkus.oidc.AuthorizationCodeFlow

SmallRye JWT authentication mechanism

io.quarkus.smallrye.jwt.runtime.auth.BearerTokenAuthentication

Quarkus automatically secures endpoints annotated with the authentication mechanism annotation. When no standard security annotation is present on the REST endpoint and resource, the io.quarkus.security.Authenticated annotation is added for you.

It is also possible to use the io.quarkus.vertx.http.runtime.security.annotation.HttpAuthenticationMechanism annotation to select any authentication mechanism based on its scheme. Annotation-based analogy to the quarkus.http.auth.permission.basic.auth-mechanism=custom configuration property is the @HttpAuthenticationMechanism("custom") annotation.

For consistency with various Jakarta EE specifications, it is recommended to always repeat annotations instead of relying on annotation inheritance.

How to combine it with HTTP Security Policy

The easiest way to define roles that are allowed to access individual resources is the @RolesAllowed annotation. Nevertheless, it’s also possible to use the HTTP Security Policy like in the example below:

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 Delay this policy’s permission check after the endpoint-specific authentication mechanism has been selected.
2 Make the roles1 permission match only the endpoint annotated with the @AuthorizationCodeFlow annotation. Unannotated endpoints must avoid the delay caused by the applies-to=JAXRS option.

プロアクティブ認証

Proactive authentication is enabled in Quarkus by default. This means that if an incoming request has a credential, the request will always be authenticated, even if the target page does not require authentication. For more information, see the Quarkus Proactive authentication guide.

関連コンテンツ