Quarkus の認証メカニズム
Quarkus Security フレームワークは、複数の認証メカニズムをサポートしており、これらを使用してアプリケーションを保護することができます。 また、認証メカニズムを組み合わせることも可能です。
Quarkus アプリケーションを保護するための認証メカニズムを選択する前に、提供される情報を確認してください。 |
サポートされる認証メカニズムの概要
サポートされている認証メカニズムは、Quarkus に組み込まれているものもあれば、エクステンションを追加する必要があるものもあります。 これらのメカニズムについては、次のセクションで詳しく説明します:
次の表は、特定の認証要件と、Quarkus で使用できるサポートされる認証メカニズムを対応付けたものです:
認証要件 | 認証メカニズム |
---|---|
ユーザー名とパスワード |
|
ベアラーアクセストークン |
|
シングルサインオン (SSO) |
|
クライアント証明書 |
|
WebAuthn |
|
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 を破棄します。
@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 |
タイプ |
デフォルト |
---|---|---|
Determines whether the entire permission set is enabled, or not. By default, if the permission set is defined, it is enabled. Environment variable: Show more |
ブーリアン |
|
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: 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: 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: Show more |
list of string |
|
Path specific authentication mechanism which must be used to authenticate a user. It needs to match Environment variable: 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: Show more |
ブーリアン |
|
Whether permission check should be applied on all matching paths, or paths specific for the Jakarta REST resources. Environment variable: Show more |
|
|
The roles that are allowed to access resources protected by this policy. By default, access is allowed to any authenticated user. Environment variable: Show more |
list of string |
|
Add roles granted to the Environment variable: Show more |
Map<String,List<String>> |
|
Permissions granted to the Environment variable: Show more |
Map<String,List<String>> |
|
Permissions granted by this policy will be created with a Environment variable: Show more |
string |
|
Map the For example, if Environment variable: Show more |
Map<String,List<String>> |
|
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:
Environment variable: Show more |
string |
|
Properties file containing the client certificate attribute value to role mappings. Use it only if the mTLS authentication mechanism is enabled with either Properties file is expected to have the Environment variable: Show more |
path |
|
The authentication realm Environment variable: Show more |
string |
|
The login page. Redirect to login page can be disabled by setting Environment variable: Show more |
string |
|
The username field name. Environment variable: Show more |
string |
|
The password field name. Environment variable: Show more |
string |
|
The error page. Redirect to error page can be disabled by setting Environment variable: Show more |
string |
|
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 Environment variable: Show more |
string |
|
Option to control the name of the cookie used to redirect the user back to the location they want to access. Environment variable: Show more |
string |
|
The inactivity (idle) timeout When inactivity timeout is reached, cookie is not renewed and a new login is enforced. Environment variable: Show more |
|
|
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: Show more |
|
|
The cookie that is used to store the persistent session Environment variable: Show more |
string |
|
The cookie path for the session and location cookies. Environment variable: Show more |
string |
|
Set the HttpOnly attribute to prevent access to the cookie via JavaScript. Environment variable: Show more |
ブーリアン |
|
SameSite attribute for the session and location cookies. Environment variable: Show more |
|
|
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: Show more |
期間フォーマットについて
To write duration values, use the standard 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|
相互 TLS 認証
Quarkus には相互 TLS (mTLS) 認証があり、X.509 証明書に基づいてユーザーを認証することができます。
この認証方法を使用するには、まずアプリケーションで SSL/TLS を有効にする必要があります。 詳細は、Quarkus ガイド "HTTP リファレンス" の Supporting secure connections with SSL/TLS を参照してください。
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 the file that holds all the certificates your application trusts. This file also includes information about how your application requests certificates when a client, such as a browser or another service, tries to access one of its protected resources.
Because JKS is no longer the default keystore and truststore format in Quarkus, the framework makes an educated guess based on the file extension:
-
.pem
,.crt
, and.key
are read as PEM certificates and keys. -
.jks
,.keystore
, and.truststore
are read as JKS keystores and truststores. -
.p12
,.pkcs12
, and.pfx
are read as PKCS12 keystores and truststores.
If your file does not use one of these extensions, you must set the format by using the following properties:
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 is becoming less commonly used. Since Java 9, the default keystore format in Java is PKCS12. The most significant difference between JKS and PKCS12 is that JKS is a format specific to Java. In contrast, PKCS12 is a standardized, language-neutral way of storing encrypted private keys and certificates.
Here is an example configuration for enabling 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 | Setting quarkus.http.ssl.client-auth to required makes the server demand client certificates. You can set it to REQUEST if the server should accept requests without a certificate. This setting is useful when supporting multiple authentication methods besides mTLS. |
4 | Defines a policy where only authenticated users can access resources from your application. |
5 | Disables the plain HTTP protocol, requiring all requests to use HTTPS. When you set quarkus.http.ssl.client-auth to required , quarkus.http.insecure-requests is automatically disabled. |
When an incoming request matches a valid certificate in the truststore, your application can obtain the subject by injecting a SecurityIdentity
as follows:
@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 | 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 us assume it contains three entries: alice=user,admin , bob=user and jdoe=tester . |
2 | HTTP セキュリティーポリシーを使用して、リクエストを認可するには SecurityIdentity に user または admin ロールが必要であることを要求します。 |
Given the preceding 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
.
証明書属性を使用して 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 |
OIDC 認証のための追加の Quarkus リソース
Quarkus アプリケーションの安全性を確保するために使用できる OIDC 認証および認可方法の詳細については、以下のリソースを参照してください:
OIDC トピック | Quarkus の情報リソース |
---|---|
ベアラートークン認証メカニズム |
|
認可コードフロー認証メカニズム |
|
OIDC と SAML アイデンティティーブローカー |
|
ベアラートークン認証または認可コードフローメカニズムをサポートする複数のテナント |
|
一般的に使用される OpenID Connect プロバイダーを使用して Quarkus を保護する |
|
Keycloak を使用した認可の一元化 |
|
Keycloak のプログラムによる設定 |
実行時に Quarkus OIDC エクステンションを有効にするには、ビルド時に マルチテナント 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 アダプターを使用して保護する必要があります。
このフィルターは、アクセストークンをダウンストリームサービスに伝播できます。
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
は、認可コードフローとベアラーアクセストークンの両方を使用して、ユーザー情報を要求することもできます。 -
If your bearer tokens must be verified, use
quarkus-oidc
,quarkus-elytron-security-oauth2
, orquarkus-smallrye-jwt
. -
ベアラートークンが JSON Web トークン (JWT) 形式である場合は、上記のリストにある任意のエクステンションを使用できます。
quarkus-oidc
とquarkus-smallrye-jwt
はどちらも、OpenID Connect プロバイダーがキーをローテーションするときに設定されたJsonWebKey
(JWK) の更新をサポートしています。 したがって、リモートトークンイントロスペクションを回避する必要がある場合やプロバイダーがこれをサポートしていない場合は、quarkus-oidc
またはquarkus-smallrye-jwt
を使用して JWT トークンを検証します。 -
To introspect the JWT tokens remotely, you can use
quarkus-oidc
orquarkus-elytron-security-oauth2
for 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
と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 トークンは不透明トークンよりも大幅に長くなります。 その場合もプロバイダーは、トークンクレームとしてトークン関連の状態を保存し、それに署名するか暗号化することで、トークン関連の状態の大部分をクライアントに効果的に委譲します。 |
必要な機能 | 認証メカニズム | ||
---|---|---|---|
|
|
|
|
ベアラー JWT の検証 |
ローカル検証もしくはイントロスペクション |
ローカル検証 |
イントロスペクション |
ベアラー不透明トークンの検証 |
イントロスペクション |
不可 |
イントロスペクション |
JWT トークン検証用の |
可 |
可 |
不可 |
トークンを |
可 |
可 |
可 |
MP JWTとして JWT をインジェクト |
可 |
可 |
不可 |
認可コードフロー |
可 |
不可 |
不可 |
マルチテナンシー |
可 |
不可 |
不可 |
ユーザー情報のサポート |
可 |
不可 |
不可 |
PEM キーフォーマットサポート |
不可 |
可 |
不可 |
SecretKey のサポート |
不可 |
JSON Web Key (JWK) 形式 |
不可 |
内部署名付き暗号化トークン、または暗号化トークン |
イントロスペクション |
ローカル検証 |
イントロスペクション |
カスタムトークン検証 |
不可 |
注入された JWT パーサーを使用 |
不可 |
Cookie としての JWT のサポート |
不可 |
可 |
可 |
認証メカニズムの組み合わせ
異なるソースからユーザー認証情報が提供される場合は、認証メカニズムを組み合わせることができます。
たとえば、組み込みの Basic 認証メカニズムと Quarkus の quarkus-oidc
べアラートークン認証メカニズムを組み合わせることができます。
The authentication process completes as soon as the first SecurityIdentity
is produced by one of the authentication mechanisms.
In some cases it can be required that all registered authentication mechanisms create their SecurityIdentity
.
It can be required when the credentials such as tokens have to be passed over 相互 TLS 認証,
for example, when users are authenticating via Virtual Private Network
, or when the current token has to be bound
to the client certificate for the token verification to succeed, guaranteeing that the token was issued exactly
to the same client which is currently passing this token to Quarkus alongside its client certificate.
In Quarkus such authentication is called inclusive
and you can enable it like this:
quarkus.http.auth.inclusive=true
If the authentication is inclusive then SecurityIdentity
created by the first authentication mechanism can be
injected into the application code.
For example, if both 相互 TLS 認証 and basic authentication mechanism authentications are required,
the 相互 TLS 認証 authentication mechanism will create SecurityIdentity
first.
Additional SecurityIdentity
instances can be accessed as a quarkus.security.identities
attribute on the first
SecurityIdentity
, however, accessing these extra identities directly may not be necessary, for example,
when both 相互 TLS 認証 and OIDC Bearer authentication mechanisms
have been combined and done their authentications, the authenticated bearer token can be injected as a token
credential alongside SecurityIdentity
created by 相互 TLS 認証. This is exemplified below:
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 | This is the SecurityIdentity created by applicable authentication mechanism with the highest priority. |
2 | Other applicable authentication mechanisms performed authentication and are available on the SecurityIdentity . |
Quarkus |
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 認可コードフローメカニズム を使用する場合のみアクセスできます。 |
認証メカニズム^ | アノテーション |
---|---|
Basic 認証メカニズム |
|
フォームベース認証メカニズム |
|
相互 TLS 認証メカニズム |
|
WebAuthn 認証メカニズム |
|
ベアラートークン認証メカニズム |
|
OIDC 認可コードフローメカニズム |
|
SmallRye JWT 認証メカニズム |
|
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 仕様との整合性を保つために、アノテーションの継承に依存するのではなく、常にアノテーションを繰り返すことが推奨されます。 |
HTTP セキュリティーポリシーとの組み合わせ方法
The easiest way to define roles that are allowed to access individual resources is the @RolesAllowed
annotation.
Nevertheless, it is 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 | エンドポイント固有の認証メカニズムの選択後、このポリシーの権限チェックを遅らせます。 |
2 | roles1 権限が、@AuthorizationCodeFlow アノテーションが付けられたエンドポイントのみと一致するようにします。
アノテーションが付いていないエンドポイントは、applies-to=JAXRS オプションによって発生する遅延を回避する必要があります。 |
プロアクティブ認証
Quarkusでは、デフォルトでプロアクティブ認証が有効になっています。 受信リクエストに認証情報がある場合、ターゲットページで認証が必要ない場合でも、リクエストは常に認証されます。 詳細については、Quarkus の プロアクティブ認証 ガイドを参照してください。