Authentication mechanisms in Quarkus
Quarkus Security フレームワークは、複数の認証メカニズムをサポートしており、これらを使用してアプリケーションを保護することができます。 また、認証メカニズムを組み合わせることも可能です。
|
Quarkus アプリケーションを保護するための認証メカニズムを選択する前に、提供される情報を確認してください。 |
サポートされる認証メカニズムの概要
サポートされている認証メカニズムは、Quarkus に組み込まれているものもあれば、エクステンションを追加する必要があるものもあります。 これらのメカニズムについては、次のセクションで詳しく説明します:
次の表は、特定の認証要件と、Quarkus で使用できるサポートされる認証メカニズムを対応付けたものです:
| 認証要件 | 認証メカニズム |
|---|---|
ユーザー名とパスワード |
|
ベアラーアクセストークン |
OIDCベアラートークン認証 、 JWT 、 OAuth2 |
シングルサインオン (SSO) |
|
クライアント証明書 |
|
WebAuthn |
|
Kerberos チケット |
詳細については、以下の トークン認証メカニズム比較 表を参照してください。
組込認証メカニズム
Quarkus Security には、次のような組込の認証サポートがあります:
フォームベース認証
Quarkusは、従来のServletフォームベース認証と同様に動作するフォームベース認証を提供します。 従来のフォーム認証とは異なり、Quarkusはクラスタ化されたHTTPセッションをサポートしていないため、認証されたユーザーはHTTPセッションに保存されません。 代わりに、認証情報は暗号化されたCookieに保存され、同じ暗号化キーを共有するすべてのクラスタメンバーが読み取ることができます。
暗号化を適用するには、 quarkus.http.auth.session.encryption-key プロパティーを追加し、設定する値が 16 文字以上であるようにして下さい。
暗号化キーは SHA-256 を使用してハッシュ化されます。
結果のダイジェストは、Cookie 値の AES-256 暗号化のキーとして使用されます。
Cookie には暗号化された値の一部として有効期限が含まれているため、クラスター内のすべてのノードのクロックが同期されている必要があります。
セッションが使用中であれば、1 分間隔で有効期限が更新された新しい Cookie が生成されます。
シングルページアプリケーション (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=フォームベース認証の設定には、以下のプロパティーを使用できます:
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
|---|---|---|
If form authentication is enabled. Environment variable: Show more |
boolean |
|
The login page. Redirect to login page can be disabled by setting Environment variable: Show more |
string |
|
The post location. 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 where he wants to get access to. 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 as 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 users last request is when the cookie is 9m old then the actual timeout will happen 21m after the last request, as the timeout is only refreshed when a new cookie is generated. In other words 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 |
boolean |
|
SameSite attribute for the session and location cookies. Environment variable: Show more |
|
|
|
期間フォーマットについて
期間の値を書くには、標準の 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|
相互 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 section of the Quarkus "HTTP reference" guide.
アプリケーションが安全な接続を受け入れた後の次のステップは、アプリケーションが信頼するすべての証明書を保持するファイルの名前を使用して quarkus.http.ssl.certificate.trust-store-file プロパティーを設定することです。指定されたファイルには、ブラウザーやその他のサービスなどのクライアントが保護されたリソースの 1 つにアクセスしようとしたときに、アプリケーションが証明書を要求する方法に関する情報も含まれます。
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| 1 | サーバーの秘密鍵が保存されているキーストア。 |
| 2 | 信頼済み証明書がロードされるトラストストア。 |
| 3 | With this value set to required, the server requires certificates from clients.
To relax this requirement so that the server accepts requests without a certificate, set the value to REQUEST.
This option is useful when you are also supporting authentication methods other than mTLS. |
| 4 | 認証されたユーザーのみがアプリケーションからリソースにアクセスできるようにするポリシーを定義します。 |
受信リクエストがトラストストア内の有効な証明書と一致する場合、アプリケーションは次のように SecurityIdentity を注入してサブジェクトを取得できます。
@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();認可
The information from the client certificate can be used to enhance Quarkus SecurityIdentity.
For example, you can add new roles after checking a client certificate subject name, and so on.
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 プロバイダーによって実行された認証に基づいてユーザーの身元を確認し、そのユーザーに関する基本情報を取得することを可能にします。
Quarkus quarkus-oidc エクステンションは、ベアラートークンと認可コードフロー認証メカニズムをサポートする、リアクティブで相互運用可能なマルチテナント対応OIDCアダプタを提供します。
ベアラートークン認証メカニズムは、HTTP Authorizationヘッダーからトークンを抽出します。
認可コードフロー機構は、ユーザーを OIDC プロバイダーにリダイレクトし、ユーザーの ID を認証します。
ユーザーがQuarkusにリダイレクトされた後、このメカニズムは、ID、アクセス、リフレッシュトークンに対して付与されたコードを交換することで、認証プロセスを完了します。
リフレッシュ可能な JSON Web Key (JWK) セットを使用して ID を検証し、JSON Web Token (JWT) トークンにアクセスしたり、リモートでそれらをイントロスペクトしたりできます。 ただし、バイナリートークンとも呼ばれる不透明トークンは、リモートでのみイントロスペクトできます。
|
Using the Quarkus OIDC extension, both the Bearer token and Authorization Code Flow authentication mechanisms use SmallRye JWT authentication to represent JWT tokens as MicroProfile JWT |
OIDC 認証のための追加の Quarkus リソース
Quarkus アプリケーションの安全性を確保するために使用できる OIDC 認証および認可方法の詳細については、以下のリソースを参照してください:
| OIDC トピック | Quarkus の情報リソース |
|---|---|
ベアラートークン認証メカニズム |
|
認可コードフロー認証メカニズム |
|
ベアラートークン認証または認可コードフローメカニズムをサポートする複数のテナント |
|
一般的に使用されているOpenID ConnectプロバイダーによるQuarkusの保護 |
|
Keycloak を使用した認可の一元化 |
|
Keycloak のプログラムによる設定 |
|
To enable the Quarkus OIDC extension at runtime, set マルチテナント OIDC デプロイメントにおける個々のテナント設定の管理に関する詳細は、"OpenID Connect (OIDC) マルチテナントの使用" ガイドの テナント設定の無効化 セクションを参照してください。 |
OpenID Connect クライアントとフィルター
quarkus-oidc-client エクステンションは、以下のトークングラントをサポートする OpenID Connect および OAuth2 プロバイダーからアクセストークンを取得し、リフレッシュするための OidcClient を提供します。
-
client-credentials -
password -
refresh_token
The quarkus-oidc-client-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-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 認証
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 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 アプリケーションを保護するために適切なトークン認証メカニズムを選択して下さい。
-
quarkus-oidcには、ベアラートークンを検証したり、認可コードフローでエンドユーザーを認証したりできる Keycloak などの OpenID Connect プロバイダーが必要です。 どちらの場合も、quarkus-oidcは指定された OpenID Connect プロバイダーへの接続を必要とします。 -
ユーザー認証に認可コードフローが必要な場合、または複数のテナントをサポートする必要がある場合は、
quarkus-oidcを使用してください。quarkus-oidcは、認可コードフローとベアラーアクセストークンの両方を使用して、ユーザー情報を要求することもできます。 -
If your bearer tokens must be verified, use
quarkus-oidc,quarkus-smallrye-jwt, orquarkus-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-oidcandquarkus-smallrye-jwtsupport refreshing theJsonWebKey(JWK) set when the OpenID Connect provider rotates the keys. Therefore, if remote token introspection must be avoided or is unsupported by the providers, usequarkus-oidcorquarkus-smallrye-jwtfor verifying JWT tokens. -
To introspect the JWT tokens remotely, you can use either
quarkus-oidcorquarkus-elytron-security-oauth2because they support verifying the opaque or binary tokens by using remote introspection.quarkus-smallrye-jwtdoes 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 べアラートークン認証メカニズムを組み合わせることができます。
|
Quarkus |
パス固有認証メカニズム
次の設定例は、あるリクエストパスに対して、選択可能な単一の認証メカニズムを強制する方法を示しています:
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=bearerauth-mechanism プロパティの値が、 HttpAuthenticationMechanism がサポートする認証スキーム（例えば、 basic 、 bearer 、 form ）と一致しているようにして下さい。
プロアクティブ認証
Quarkusでは、デフォルトでプロアクティブ認証が有効になっています。 受信リクエストに認証情報がある場合、ターゲットページで認証が必要ない場合でも、リクエストは常に認証されます。 詳細については、Quarkus の プロアクティブ認証 ガイドを参照してください。
