Quarkus OpenId Connect (OIDC) 詳細設定リファレンス

このビルド時プロパティーは、OIDC エクステンション全体を有効にするかどうかを制御します。ビルド時に無効に設定された場合、OIDC エクステンションは実行時には利用できません。

Quarkus OIDC テナント設定は、単一の OIDC プロバイダー、または複数の OIDC プロバイダーテナントやレルムの中の個々のテナントやレルムに関連付けられた特定の要件を表します。

これら 2 つのプロパティーにより、OIDC テナント設定を有効にするかどうかと、OIDC テナント名を指定できます。

quarkus.oidc.tenant-enabled プロパティーは、単一のデフォルト OIDC テナントを使用している場合でも、例えばコンテナー内の OIDC 統合をコンテナーの起動時にのみアクティブ化すべき場合に役立ちます。

ほとんどの場合、複数の OIDC テナント設定要件があり、OIDC テナント設定を プログラムで 作成しない限り、 quarkus.oidc.tenant-id プロパティーを扱う必要はありません。 application.properties で OIDC テナントを設定する場合、OIDC 設定プロパティーリファレンス ドキュメントからわかるように、テナント ID はテナント固有のプロパティーグループの 3 番目のトークンとして宣言されます。

たとえば、以下の設定は OIDC tenant-1 の設定要件を定義します。

必要な数のテナント設定を構成または作成し、リクエスト時にそれらを解決できます。

詳細は マルチテナンシー セクションを参照してください。

quarkus.oidc.auth-server-url は、主要なベース OIDC URL プロパティーです。

デフォルトでは、 Quarkus OIDC はこの URL に .well-known/openid-configuration パスセグメントを追加し、 OIDC プロバイダーのメタデータを検出します。 ディスカバリーパスは quarkus.oidc.discovery-path でカスタマイズでき、たとえば .well-known/oauth-authorization-server に設定することが可能です。

プロバイダーがメタデータ検出をサポートしていない場合 (ほとんどの OAuth2 プロバイダーはサポートしていません)、またはリモートのディスカバリー呼び出しをスキップして個別の OIDC プロバイダーエンドポイント URL を設定することで起動時間を最適化したい場合は、 quarkus.oidc.discovery-enabled=false でメタデータ検出を無効にできます。

検出された OIDC エンドポイント URL のいずれかをオーバーライドする必要がある場合や、検出された OIDC メタデータに必要なエンドポイント URL が含まれていない場合には、 quarkus.oidc.authorization-path などの個別の OIDC エンドポイント URL を設定することもできます。

これらの URL は、ベースの quarkus.oidc.auth-server-url URL からの相対パス、または絶対 URL のいずれかにできます。

たとえば、 OAuth2 プロバイダーを扱う場合は通常、ディスカバリーを無効にして個別のエンドポイント URL を指定する必要があります。詳細は OAuth2 プロバイダー セクションを参照してください。

設定が必要な個別の OIDC エンドポイント URL は、 OIDC の アプリケーションタイプ と期待されるトークン形式に依存します。

quarkus.oidc.authorization-path 、 quarkus.oidc.token-path 、および quarkus.oidc.end-session-path は、 quarkus.oidc.application-type=web-app で 認可コードフロー 認証が有効な場合にのみ関連します。

quarkus.oidc.jwks-path は JSON Web Key Set (JWKS) を取得するために必要ですが、これはトークンが JSON Web Token (JWT) である場合に限られます。 quarkus.oidc.application-type=web-app の場合、ユーザー認証を表す ID トークンは常に JWT 形式であり、ほとんどの場合、それらを検証するために JWK キーが必要になります。通常はリモートでイントロスペクションされる不透明な (バイナリ) ベアラーアクセストークンを扱う場合は、 JWKS パスは必要ありません。

不透明な (バイナリ) アクセストークンをリモートでイントロスペクションする必要がある場合、そのようなトークンには検証可能な署名が付加されていないため、ほとんどの場合 quarkus.oidc.introspection-path が必要になります。 JWT トークンを扱う場合でも、プロバイダーがリモートイントロスペクションをサポートしているなら、 quarkus.oidc.introspection-path を設定する価値があります。そのような場合、 JWT をローカルで検証するための一致する JWK 検証キーが見つからないときに、フォールバックとして JWT トークンをリモートでイントロスペクションできます。

quarkus.oidc.user-info-path は通常、 認可コードフロー の完了後に、 ID トークンで既に利用可能な情報に加えて、ユーザーに関する詳細情報を得るために UserInfo をリクエストする必要がある場合に必要です。 UserInfo のリクエストは、ベアラーアクセストークンフローでも可能です。

バイナリアクセストークンを発行するもののリモートイントロスペクションをサポートしておらず、標準的な UserInfo もサポートしていない OAuth2 プロバイダーを扱う場合、間接的なアクセストークン検証をサポートするために、 quarkus.oidc.user-info-path で現在のユーザーに関する情報を返す OAuth2 プロバイダー固有のエンドポイントを指す必要があります。詳細は OAuth2 プロバイダー セクションを参照してください。

quarkus.oidc.revoke-path および quarkus.oidc.registration-path は、現在 Quarkus OIDC によって直接使用されていません。 アプリケーションはログアウトやその他のセキュリティーイベント時に トークンを失効させることができます 。 quarkus-oidc を既に使用しているアプリケーションは、 quarkus.oidc.registration-path を使用して OIDC クライアントを動的に登録 できます。

ただし、プロバイダーがメタデータ検出をサポートしている場合、これらの OIDC エンドポイント固有の URL のすべてまたは一部が検出可能である可能性があることを忘れないでください。

保護されたリソースのメタデータへのアクセスについては、 保護されたリソースのメタデータ セクションも参照してください。

OIDC アプリケーションタイプは、現在のリクエストがどのように認証されるかを決定します。

デフォルトの service アプリケーションタイプは、 Quarkus アプリケーションにアクセスするために HTTP Authorization: Bearer <token> ヘッダーとともに bearer アクセストークンが送信される場合に使用されます。たとえば、 シングルページアプリケーション (SPA) は、現在ログインしている SPA ユーザーに代わって Quarkus にアクセスするためにアクセストークンを使用できます。

web-app アプリケーションタイプは、 quarkus-oidc エクステンションが 認可コードフロー を使用してユーザーを Quarkus に対して認証し、セッションクッキーを作成する場合に使用されます。

hybrid アプリケーションタイプは、ベアラーアクセストークンフローと認可コードフローの両方を同時にサポートするために使用できます。 現在のリクエストに HTTP Authorization: Bearer <token> ヘッダーがある場合はベアラーアクセストークンが検証され、それ以外の場合でセッションクッキーが利用できない場合は、ユーザーは認証のために OIDC プロバイダーにリダイレクトされます。

quarkus-oidc エクステンションは、登録された OIDC アプリケーションクライアントを表します。 このクライアントは、トークンの取得、イントロスペクション、または失効を行う際に、 OIDC プロバイダーに対して認証を行う必要があります。

登録された OIDC クライアントにはクライアント ID があり、通常はクライアントシークレットもあります。

JWT ベアラーアクセストークンを受け入れる場合、公開 OIDC JWKS キーセットエンドポイントから利用可能な JWK 検証キーを使用してローカルで検証できるため、 quarkus.oidc.client-id と quarkus.oidc.credentials.secret は両方とも任意です。ただし、この場合でも OIDC ログメッセージの情報をより充実させるために、 quarkus.oidc.client-id を設定することが推奨されます。

quarkus.oidc.client-name はユーザーフレンドリーなクライアント名であり、現在はログメッセージの情報をより充実させるためにのみ使用されます。

quarkus.oidc.application-type=web-app で 認可コードフロー 認証を有効にする場合、 OIDC トークンエンドポイントでクライアント認証が必要なため、現在の認可コードフローを完了するには quarkus.oidc.client-id と quarkus.oidc.credentials.secret (または他のタイプのクライアントクレデンシャル) の設定が必要です。

ベアラーアクセストークンフローと認可コードフローの両方において、トークンをイントロスペクションする必要がある場合、通常はこれら両方のプロパティーが必要になります。

サポートされている OIDC プロバイダークライアント認証オプションの完全な説明については、 クライアント認証オプション セクションも参照してください。

クライアントシークレットが quarkus.oidc.credentials.secret で設定されている場合、 quarkus.oidc.client-id と共に HTTP Authorization: Basic クレデンシャルペアとして送信されます。しかし、プロバイダーによっては、クライアント ID とシークレットが POST フォームパラメーターとして送信された場合にのみ受け入れることができ、その場合は quarkus.oidc.credentials.client-secret.method=post 設定を使用する必要があります。

quarkus.oidc.credentials.client-secret.provider.* 名前空間の残りの 3 つのプロパティーを使用すると、安全な場所に保存されたシークレットを提供するために、カスタムの CredentialsProvider をどのように使用するかをカスタマイズできます。あるいは、Quarkus 設定システムを使用してシークレットを管理することも可能です。詳細は 設定プロパティーでのシークレット ガイドを参照してください。

クライアントシークレットを送信する代わりに、 Quarkus OIDC は、クライアントシークレットまたは秘密鍵のいずれかで署名された生成済みの JWT 認証トークンを送信することによって、 OIDC プロバイダーに対して認証を行うことができます。

MTLS 認証が必要な場合は、TLS プロパティー セクションを参照してください。

トークンをイントロスペクションする必要がある場合、一部のプロバイダーは、既に設定されている OIDC クライアント ID や OIDC クライアント認証クレデンシャルとは別に、イントロスペクション固有の認証クレデンシャルを要求することがあります。

quarkus.oidc.introspection-credentials.name と quarkus.oidc.introspection-credentials.secret は、プロバイダーがイントロスペクション固有の認証クレデンシャルを必要とする場合にのみ使用する必要があります。この場合、イントロスペクションエンドポイントは client_id パラメーターとして送信される quarkus.oidc.client-id プロパティーも必要とする場合があります。

現在のところ、イントロスペクションクレデンシャルが設定されている場合、それらは HTTP POST フォームパラメーターとしてのみ送信できます。

認可コードフローの初期段階 (第 1 段階) では、Quarkus OIDC が正しいリダイレクト URL を構築し、ユーザーを認証のために OIDC プロバイダーにリダイレクトする必要があります。

quarkus.oidc.authentication.redirect-path 相対パスは、ユーザーが認証チャレンジを完了した後に、OIDC プロバイダーによってリダイレクトされる Quarkus エンドポイントを指します。このエンドポイントの絶対アドレスは、OIDC アプリケーション登録時にコールバック URL として設定したものです。たとえば、Quarkus エンドポイントが https://myservice.com で動作しており、 quarkus.oidc.authentication.redirect-path=service というリダイレクトパスがある場合、絶対コールバック URL は https://myservice.com/service になります。

quarkus.oidc.authentication.response-mode は、OIDC プロバイダーが code などの認可コードフローのプロパティーをどのように返すかを定義します。通常、これらのパラメーターはクエリーパラメーターとして返されます (例: https://myservice.com/service?code=somecode&state=somestate)。これは query レスポンスモードであり、デフォルトでサポートされています。

ただし、これらのパラメーターは、リクエストボディー内の POST フォームペイロードとして直接 Quarkus に返されることもあります。これは、プロバイダーがユーザーに HTML ページを返し、そのページがフォームペイロードを Quarkus に自動送信することで実現されます。 Apple などの一部のプロバイダーは、このレスポンスモードを強制する場合があります。このモードをサポートする必要がある場合は、 quarkus.oidc.authentication.response-mode=form を設定してください。また、この場合、 code やその他のパラメーターはリクエストボディーで送信されるため、 quarkus.oidc.authentication.remove-redirect-parameters=true を設定する必要はありません。

ほとんどの OIDC プロバイダーは、初期リダイレクト URL に scope=openid パラメーターが含まれることを想定しており、Quarkus はデフォルトで常にこれを自動追加するため、 quarkus.oidc.authentication.scopes=openid と設定する必要はありません。しかし、認可コードフローの完了後に (ID およびリフレッシュトークンとともに) 発行されるアクセストークンに対して追加の権限をリクエストするために、追加のスコープまたはカンマ区切りのスコープリストを提供しなければならないことがよくあります。たとえば、Quarkus アプリケーションがユーザーに代わって Google カレンダーを読み取る必要がある場合は、 quarkus.oidc.authentication.scopes=https://www.googleapis.com/auth/calendar.readonly と設定できます。

複数のスコープを OIDC プロバイダーに送信する必要がある場合は、 ` ` スペース文字 (URL エンコードで %20) を使用して複数のスコープ値を区切ります (例: scope=openid%20scope=read)。一部の OAuth2 プロバイダー (特に Strava OAuth2) はカンマ , のセパレーターを想定しているため、その場合は quarkus.oidc.authentication.scope-separator=, などと設定できます。

ほとんどの OAuth2 プロバイダーは openid スコープを認識すると失敗しますが、このスコープはほとんどの OIDC プロバイダーでデフォルトで想定されています。このような場合に、 quarkus.oidc.authentication.add-openid-scope=false を設定する必要があるかもしれません。

通常の scope、 redirect_uri、 state クエリー初期リダイレクトパラメーター以外に、他のパラメーターを含める必要がある場合があります。その場合、マップ形式の quarkus.oidc.authentication.extra-params プロパティーが役立ちます (例: quarkus.oidc.authentication.extra-params.prompt=consent など)。

quarkus.oidc.authentication.forward-params マップパラメーターを使用すると、ユーザーを認証にリダイレクトする前に Quarkus が作成するリダイレクト URI に、元のユーザーリクエスト URL のクエリーパラメーターのうちどれを含めるかを選択できます。このプロパティーの使用には注意が必要です。

quarkus.oidc.authentication.force-redirect-https-scheme は、元のユーザーリクエストが HTTPS 経由で行われたものの、ファイアウォールで終端され Quarkus には http:// スキームとして見える場合に、正しいリダイレクト URI を構築するために使用できます。 quarkus.oidc.authentication.force-redirect-https-scheme=true を設定することで、Quarkus OIDC が現在のリクエスト URL で http:// スキームを検知した場合でも、 https:// スキームを使用するように Quarkus に指示し、ユーザーを HTTPS ベースの OIDC 認可エンドポイントに正しくリダイレクトさせることができます。 adoc:http-reference#reverse-proxy[Forwarded または X-Forwarded ヘッダー] を認識するように Quarkus を設定済みの場合は、このプロパティーの設定は不要な場合があります。

quarkus.oidc.authentication.allow-multiple-code-flows はデフォルトでマルチタブ認証を許可します。たとえば、ユーザーがあるタブで認可コードフローを開始し、要求されたクレデンシャルを入力しようとしている最中に、何らかの中断で完了せず、後に別のタブを開いて別の認可コードフローを開始・完了させたとしても、最初のタブでの元のフローは保留状態のまま残ります。この時、すでに認証済みのユーザーが最初のタブに戻ってそのフローも完了させることができます。このような認証フローの柔軟性が、より厳格な認証ポリシーにとって過剰であると判断される場合は、 quarkus.oidc.authentication.allow-multiple-code-flows=false を設定してください。以下の quarkus.oidc.authentication.fail-on-missing-kid 設定プロパティーの説明も参照してください。

OAuth 2.0 リッチ認可リクエスト (RAR) 仕様により、OAuth2 クライアントアプリケーションは、認可コードフロー中にきめ細かな認可要件を指定できるようになります。従来の OAuth 2.0 スコープのみに頼る代わりに、RAR は必要な権限を JSON として表現し、URL エンコードして authorization_details クエリーパラメーターとして渡します。

quarkus.oidc.authentication.rar.type は、認可詳細のタイプを指定する必須の設定プロパティーです。このタイプは、検証可能なクレデンシャル用の openid_credential のように、リクエストされている認可の種類を識別します。

quarkus.oidc.authentication.rar.simple 設定プロパティーを使用すると、認可詳細の JSON に単純な文字列フィールドを追加できます。

quarkus.oidc.authentication.rar.array 設定プロパティーを使用すると、認可詳細の JSON に配列フィールドを追加できます。

設定プロパティーでは表現できない、より複雑な JSON 構造については、 io.quarkus.oidc.OidcRedirectFilter を使用してください。

認可コードフローの完了段階 (第 2 段階) では、Quarkus OIDC が認可コードを ID、アクセス、およびリフレッシュトークンと交換する必要があります。

quarkus.oidc.code-grant.extra-params は、ユーザーが認証され認可 code を持って Quarkus にリダイレクトされた後、認可コードフローを完了するために OIDC トークンエンドポイントに送信する必要がある追加パラメーターを設定するためのマップ設定プロパティーです。多くの場合、この code と、初期認可コードフローのリダイレクトに含まれていたものと一致する必要がある redirect_uri は、クライアント認証クレデンシャルに加えて、フォームパラメーターとして送信されます。

認可コードフローを完了するために、追加の HTTP ヘッダーを提供しなければならない場合があります。そのような場合は、 quarkus.oidc.code-grant.headers マップ設定プロパティーを使用してください。

quarkus.oidc.authentication.restore-path-after-redirect を使用すると、認可コードフローを開始するために使用された元のリクエストパスを復元できます。たとえば、アプリケーションがセキュアなアクセスを必要とする多くのエンドポイントを提供しており、考えられるすべての初期セキュア Quarkus エンドポイント URL を OIDC コールバック URL として登録することが不可能な場合を想定します。このような場合、 quarkus.oidc.authentication.restore-path-after-redirect=true を設定することで、 quarkus.oidc.authenticaion.redirect-path で設定されたコールバック URL に戻ってきた認証済みユーザーを、Quarkus OIDC に元のリクエスト URL へリダイレクトさせることができます。この場合、コールバック URL は仮想的なものとして扱われるため、それをサポートするための JAX-RS コールバックエンドポイントを割り当てる必要はありません。

quarkus.oidc.authentication.remove-redirect-parameters は、認証済みユーザーが Quarkus にリダイレクトされ、認可コードがトークンと交換され、セッションが確立された後に、追加のリダイレクトを強制します。これは、URL から code や state などの認可コードフロー固有の設定プロパティーを削除するために行われます。アプリケーションが独自のリダイレクトを行わない場合、これらの設定プロパティーは URL クエリーパラメーターとしてブラウザーに表示されたままになる可能性があります。ただし、 code は、認可コードフローを完了するために必要なクライアントクレデンシャルを知っている Quarkus OIDC のみが交換できるワンタイムトークンであることに注意してください。しかし一般的には、これらを削除することが推奨され、デフォルトで行われるべきです。

quarkus.oidc.authentication.nonce-required は、リプレイアタックを防止できる認可コードフローのセキュリティー強化プロパティーです。Quarkus がこれを生成し、初期認証リダイレクト中に nonce=<generated_nonce> クエリーパラメーターを含めるように求められた場合、OIDC プロバイダーは、一致する nonce 値を持つ nonce クレームを含む ID トークンを返さなければなりません。すべての OIDC プロバイダー、特に OAuth2 プロバイダーがデフォルトでこれをサポートしているとは限らないため、デフォルトでは false に設定されています。プロバイダーがこの機能をサポートしている場合は、このプロパティーを true に設定することが RECOMMENDED です。

quarkus.oidc.authentication.pkce-required を使用して、 Proof Key for Code Exchange (PKCE) を有効にできます。 PKCE は、主にブラウザーで実行されるパブリックな SPA OIDC クライアントにとって重要です。通常、Quarkus OIDC は、クライアントシークレットを知っていることを OIDC プロバイダーに証明できる機密性の高い OIDC クライアントとして動作するため、PKCE は厳密には必要ありません。ただし、プロバイダーがすべての認可コードフロークライアントに対して PKCE を強制する場合は、これを有効にする必要があるかもしれません。

認可コードフローが完了すると、Quarkus は現在認証されているユーザーに関する十分な情報を提供できる ID トークン にアクセスできるようになります。しかし、ユーザーの詳細情報を取得するために、OIDC プロバイダーの UserInfo エンドポイントへの追加のリモートリクエストが必要になることがよくあります。

quarkus.oidc.authentication.user-info-required を使用して、追加のリモート UserInfo リクエストを有効にできます。

GitHub のような純粋な OAuth2 プロバイダーを使用する場合、 quarkus.oidc.authentication.user-info-required=true の設定は常に必須です。その理由は、 OAuth2 は ID トークン を提供せず、 アクセストークン のみを提供するためです。OAuth2 のみの世界では、アクセストークンは、それを取得した Quarkus エンドポイントである現在のクライアント自身のためのものではなく、そのエンドポイントが現在のユーザーに代わってダウンストリームサービスにアクセスするためのものです。しかし、Quarkus は現在のユーザーのアイデンティティーにアクセスする必要があるため、このような場合にはこの設定プロパティーを設定する必要があります。ただし、OAuth2 プロバイダーには標準の OIDC UserInfo エンドポイントがないため、現在のユーザーに関する情報を返すプロバイダー固有のエンドポイントを指すように quarkus.oidc.user-info-path を設定する必要があります。たとえば GitHub の場合は https://api.github.com/user です。詳細は OAuth2 プロバイダー セクションを参照してください。

quarkus.oidc.authentication.user-info-required は、Quarkus エンドポイントに quarkus.oidc.UserInfo が注入されていることが検出されると自動的に有効になります。この場合、このプロパティーを 明示的に有効にする必要はありません。

この設定プロパティーは、 UserInfo を使用したアクセストークンの検証 を行う必要がある場合や、ID トークンを返さず、 UserInfo で間接的に検証しなければならないバイナリアクセストークンのみを返す OAuth2 プロバイダーを使用する場合にも、自動的に有効になります。詳細は ID トークンの可用性 セクションを参照してください。

認可コードフローが常に正常に完了するとは限りません。ユーザーが認証チャレンジをキャンセルしたり、正しいクレデンシャルの提供に失敗したりすることがあります。このような場合、 code パラメーターの代わりに、 error と error_description パラメーターが Quarkus に返されます。

認可コードフローが失敗した場合、ユーザーはデフォルトで HTTP 401 ステータスエラーを受け取りますが、何が起こったのかをユーザーに説明する整形されたページを返すことで、より良いユーザー体験を提供できます。 quarkus.oidc.authentication.error-path を使用して、Quarkus OIDC から転送された error および error_description パラメーターにアクセスしてそのようなページを作成できるエンドポイントリソースを指定できます。

quarkus.oidc.authentication.fail-on-missing-state-param は、State Cookie が検出され (これにより、認可コードフローの最初の段階が完了しようとしていることを示唆します)、かつ OIDC プロバイダーから Quarkus OIDC への戻りリダイレクトにおいて、一致する state クエリーパラメーターが見つからない場合に何が起きるべきかを制御するためのものです。 このプロパティーはデフォルトで false に設定されています。これは、あるタブに関連する State Cookie が存在するものの、現在のリクエストが新しいタブの認証リクエストであるようなマルチタブ認証のケースがあるためです (上記の 認可コードフローの開始 セクションにある quarkus.oidc.authentication.allow-multiple-code-flows プロパティーの説明も参照してください)。 また、OIDC プロバイダー側での認証試行に失敗したり中断したりした後、再度 Quarkus にアクセスしようとした際に、残存している State Cookie が原因で説明が難しい HTTP 401 ステータスエラーが発生し、ブラウザーキャッシュのクリアが必要になる事態を回避できるため、OIDC で保護されたエンドポイントの開発とテストがはるかに容易になります。

quarkus.oidc.authentication.fail-on-missing-state-param=true は、セキュリティーを緩和するものではなく、主にユーザー体験に関するものです。何らかの理由で state クエリーパラメーターが欠落しているために認可コードフローを完了できない場合、ユーザーに何も表示されない HTTP 401 レスポンスを返すのではなく、再認証のために OIDC プロバイダーにリダイレクトします。

quarkus.oidc.authentication.fail-on-missing-kid プロパティーは、マルチタブ認証に関連しています。別のタブでの認証によって検証キーのリフレッシュが発生し、現在の ID トークンのキー識別子が見つからなくなったために、セッションの ID トークン署名が検証できなくなり、HTTP 401 が発生することがあります。代わりにユーザーに再認証を求める場合は、このプロパティーを false に設定するとよいでしょう。トークンの署名が検証できない状況は慎重に扱うべきであることを強調するため、デフォルトは true に設定されています。

SPA を使用して認可コードフローの管理を Quarkus OIDC に委譲する場合、多くの OIDC プロバイダーが、ユーザーに認証画面を提示する認可エンドポイントに対して CORS をサポートしていないという事実を回避するために、quarkus.oidc.authentication.java-script-auto-redirect を使用できます。quarkus.oidc.authentication.java-script-auto-redirect=true`を設定すると、SPA の XHR によってこのリダイレクトが管理される際に、OIDC プロバイダー側でのこのようなリダイレクトに対する CORS サポートの欠如によりブロックされる `302 リダイレクトの代わりに、Quarkus に HTTP 499 ステータスを返すよう要求します。SPA は 499 エラーをキャッチし、window API を使用してブラウザースクリプトの制限を回避できます。

JavaScript リクエストチェックのカスタマイズについての詳細は、 JavaScript リクエストチェッカー セクションを参照してください。

OIDC は、ユーザー認証を表す新しいタイプのトークンである ID トークン を追加するため、OAuth2 とは異なります。 quarkus-oidc は ID トークンを返す準拠した OIDC プロバイダーで動作しますが、それを返さない OAuth2 プロバイダーもサポートする必要があります。 quarkus.oidc.authentication.id-token-required=false を使用して、プロバイダーが必須の ID トークンを提供できないことを Quarkus に伝えます。この場合、Quarkus はセッションを表す内部 ID トークンを生成します。また、Quarkus OIDC は、現在のユーザーに関する情報を取得するために、OAuth2 プロバイダー固有の UserInfo エンドポイントパスが quarkus.oidc.user-info-path で設定されていることを期待します。

セッションを作成する必要がありますが、OAuth2 プロバイダーはセッションの有効期間を計算するために使用できる ID トークンを返さないため、 quarkus.oidc.authentication.internal-id-token-lifespan 期間プロパティーを使用してセッションの有効期間を設定できます。OAuth2 サーバーがアクセストークンの expires_in プロパティーを返す場合、 quarkus.oidc.authentication.internal-id-token-lifespan が設定されていなければ、そのプロパティーがセッション有効期間プロパティーとして使用されます。

共通 Cookie プロパティーは、認可コードフローのセッション Cookie と State Cookie の両方に影響を与えます。

quarkus.oidc.authentication.cookie-path および quarkus.oidc.authentication.cookie-domain プロパティーは、State Cookie およびセッション Cookie がどのアプリケーションパスで利用可能になるかを制御します。Cookie パスが広いほど ("/")、アプリケーションの保護されるスペースを広くできます。 /public などのパスで利用可能な公開スペースを扱いやすくするために、これを /secured などのより具体的なパスに制限したい場合があります。また、特定のエンドポイントパスが、特定のプロバイダーで認証されたユーザーのみにアクセス可能であるべき場合にも制限したい場合があります。たとえば、 /keycloak パスは Keycloak で認証されたユーザーのみ、 /google は Google で認証されたユーザーのみがアクセスできるようにします。詳細は マルチテナンシー セクションを参照してください。

quarkus.oidc.authentication.cookie-path-header を使用すると、必要な Cookie パスを動的に設定できます。このプロパティーは慎重に、かつデプロイメントの要件に適合する場合にのみ使用してください。

quarkus.oidc.authentication.cookie-same-site は、セッション Cookie の Same-Site 属性をデフォルトで lax と定義しています。これは、 strict に設定すると一部のデプロイメントで不具合が生じることが判明しているためです。ただし、OIDC プロバイダーがアプリケーションと同じドメインでホストされている場合など、デプロイメントで正常に動作することがわかっている場合は、 strict に設定することが推奨されます。

同様に、 quarkus.oidc.authentication.state-cookie-same-site は State Cookie の Same-Site 属性をデフォルトで lax と定義していますが、デプロイメントで正常に動作することがわかっている場合は strict に設定することが推奨されます。

理想的にはセッション Cookie と State Cookie の両方が同じ Same-Site 属性値を持つべきですが、両方の Cookie に同じ Same-Site strict 値を持たせると、場合によっては問題が発生することも判明しています。

quarkus.oidc.authentication.cookie-suffix を使用して、State Cookie とセッション Cookie の名前をカスタマイズできます。たとえば、 %test.quarkus.oidc.authentication.cookie-suffix=test と設定することで、テストプロファイルにおいてのみセッション Cookie 名に _test サフィックスを付加できます。

quarkus.oidc.authentication.cookie-force-secure は、Quarkus がセキュアでない HTTP プロトコルでリッスンしているが、HTTPS を終端するリバースプロキシの背後で動作している一部のデプロイメントにおいてのみ関係する可能性があります。Quarkus が HTTPS でリッスンしている場合、Cookie は常にセキュアであるため、このプロパティーの影響はありません。

Quarkus OIDC は、2 回のリダイレクト中に Quarkus と OIDC プロバイダー間で渡される state クエリーパラメーターと値が一致しなければならない State Cookie を作成します。実際の状態値に加えて、quarkus.oidc.authentication.nonce-required=true で ID トークンに nonce クレームを含める必要がある場合は nonce 値を、quarkus.oidc.authentication.pkce-required=true で PKCE が必要な場合は Proof Key for Code Exchange (PKCE) の code-verifier を、State Cookie に保持する必要がある場合があります。これらの値は両方とも暗号化される必要があります。このような場合、State Cookie は生成された秘密鍵で暗号化されますが、通常は 32 文字の長さの独自の State Cookie 暗号化シークレットを quarkus.oidc.authentication.state-secret で提供することもできます。

quarkus.oidc.authentication.state-cookie-age は、State Cookie の有効期間を定義します。

セッション Cookie は、認可コードフローの完了後に作成されます。期限切れのセッション Cookie はリフレッシュ可能です。

quarkus.oidc.token.refresh-expired を使用すると、ユーザーセッションが期限切れになり、リフレッシュトークンが利用可能な場合に、ユーザーセッションの自動更新を有効にできます。自動更新を有効にすると、ユーザーは一度認証された後、非常に長い間再認証を求められない可能性があるため、このプロパティーはデフォルトでは有効になっていません。したがって、自動セッション更新を有効にするには、管理者レベルの判断が必要になる場合があります。

かなり長いアイドル期間の後にユーザーに再認証させたい場合は、代わりに quarkus.oidc.authentication.session-expired-path を設定することを検討してください。詳細は以下を参照してください。

quarkus.oidc.token.refresh-token-time-skew は、quarkus.oidc.token.refresh-expired で許可されており、かつセッション Cookie 内の ID トークンがまだ有効である場合に、リフレッシュを強制するために使用できます。このプロパティーを使用すると、まだ有効な ID トークンが今後 1 時間以内に期限切れになる予定の場合にリフレッシュを要求できます。ユーザーセッションを自動リフレッシュしたい場合、このプロパティーを設定することで、セッション Cookie 自体が期限切れになりブラウザーによって削除されることでユーザーがセッションのリフレッシュを逃すリスクを最小限に抑えることができます。SPA を使用している場合は、バックグラウンドスレッドで定期的に Quarkus に ping を送信し、設定された quarkus.oidc.token.refresh-token-time-skew 期間内に ID トークンがまもなく期限切れになると Quarkus が判断した時点でセッションリフレッシュを行うことができます。

たとえば、ID トークンの有効期間が 6 時間であり、したがってセッション Cookie の有効期間も 6 時間であると想定します。ユーザーが期限切れの 1 時間前に Quarkus にアクセスし、その後 2 時間アイドル状態であった場合、セッション Cookie 作成から 7 時間後 (ID トークンと Cookie が期限切れになりブラウザーから削除された 1 時間後) にユーザーが再び Quarkus にアクセスした際、Quarkus OIDC はセッション Cookie を確認できないため、ユーザーに再認証を要求することしかできません。再認証の試行回数を最小限に抑えるには、セッション有効期間をたとえば 3 時間延長することを検討してください。この最後の例のような設定であれば、Quarkus OIDC は期限切れの ID トークンにまだアクセスできる可能性があり、必要に応じて、すぐに新しい認証を要求する代わりに、トークンをリフレッシュしたりユーザーにセッション期限切れページを提示したりといった有用な処理を行うことができます。

quarkus.oidc.token.refresh-token プロパティーは、quarkus.oidc.token.refresh-token-time-skew プロパティーが設定されている場合、自動的に有効になります。

quarkus.oidc.authentication.session-expired-path を使用すると、セッションが期限切れになったユーザーに対して、セッションが期限切れであることを説明し、再認証のためのリンクを提示するページを表示できます。これにより、以前の認証成功からしばらく経って Quarkus アプリケーションにアクセスした際に、予期せぬ OIDC プロバイダーの認証画面が表示されてユーザーが驚くといった状況を避け、ユーザー体験を向上させることができます。

セッション Cookie の管理についての詳細は、認可コードフローのトークンの保存 セクションも参照してください。

認可コードフローの完了後、またはトークンのリフレッシュ後に新しいセッション Cookie が作成される際、HTTP キャッシュ中間サーバーやブラウザーキャッシュによってセッション Cookie がどのように管理されるかを制御する必要がある場合があります。現在、クライアントリクエストチェーンのどこにもセッション Cookie のキャッシュを禁止する Cache-Control no-store ディレクティブのみを設定可能です。

RP-initiated ログアウトでは、ログイン中のユーザーがアプリケーションのログアウトエンドポイントを呼び出すことでログアウトリクエストを開始します。Quarkus OIDC はこのリクエストをインターセプトし、セッション Cookie をクリアして、ユーザーを OIDC プロバイダーのログアウトエンドポイントにリダイレクトします。

quarkus.oidc.logout.path は、ユーザーのログアウトリクエストの送信先となる相対パスです。たとえば、 quarkus.oidc.logout.path=/logout と設定した場合、SPA ページの Logout リンクの宛先を http://localhost:8080/logout にできます。このパスは仮想的なものでもよく、 /logout でリッスンする JAX-RS エンドポイントやルートハンドラーを作成する必要はありません。ただし、 quarkus.oidc.logout.path を有効にするには保護されている必要があるため、詳細は ユーザー主導型ログアウト セクションを参照してください。

quarkus.oidc.logout.post-logout-path は、ログアウトしたユーザーをプロバイダーがリダイレクトさせる公開エンドポイントを指します。たとえば、 quarkus.oidc.logout.post-logout-path=/welcome.html と設定して、ログアウトしたユーザーをアプリケーションのウェルカムページに戻し、そこで再度ログインを選択できるようにすることが可能です。ログアウト後のリダイレクトを機能させるには、通常 OIDC プロバイダー側で http://localhost:8080/welcome.html のような絶対パスのログアウト後 URL を登録する必要があります。このパスは必ず公開エンドポイントである必要があることに注意してください。そうでない場合、ユーザーはログアウトを選択した直後に再度ログインを求められることになります。

quarkus.oidc.logout.post-logout-uri-param と quarkus.oidc.logout.extra-params を使用して、RP-initiated ログアウトのクエリーパラメーターをカスタマイズできます。たとえば Auth0 では、Auth0 固有のログアウトクエリーパラメーターが必要になる場合があります。詳細は ユーザー主導型ログアウト セクションを参照してください。

デフォルトでは、すべてのログアウトパラメーターはログアウト URL のクエリーパラメーターとしてシリアル化されます。一部の OIDC プロバイダーでは、ログアウトパラメーターを HTML フォーム値としてエンコードし、ブラウザーから HTTP POST メソッドおよび application/x-www-form-urlencoded コンテンツタイプで自動送信することを要求する場合があります。その場合は、 quarkus.oidc.logout.logout-mode=form-post を設定してください。

バックチャネルログアウトは、複数のサービス (異なるホストまたはポート上にある可能性もあります) を含む複雑な Quarkus アプリケーションでグローバルログアウトのサポートが必要な場合に使用されます。ユーザーがサービスのいずれかからログアウトを選択すると、他のすべてのサービスからもログアウトされます。OIDC プロバイダーは、サービスのいずれかからのログアウトリクエスト (たとえば RP-initiated のもの) を検出し、他のすべての Quarkus OIDC アプリケーションにバックチャネル通知を送信します。詳細は OIDC バックチャネルログアウト セクションを参照してください。

バックチャネルログアウトオプションをサポートするには、保留中のバックチャネル通知のキャッシュを管理する必要があることに注意してください。これらをクリアするには、バックチャネルログアウトが保留されているユーザーが Quarkus にアクセスする必要があるため、時間がかかる場合があります。アプリケーションが扱うユーザー数が多いほど、キャッシュサイズが大きくなる可能性があります。

quarkus.oidc.logout.backchannel.path は、OIDC プロバイダーがバックチャネルログアウト通知を送信する必要がある相対パスです。

バックチャネル通知にはログアウトトークンが含まれています。認証済みユーザーのいずれかが Quarkus にアクセスしようとしたときに、そのユーザーの ID トークンをこのログアウトトークンと照合できるように、これをキャッシュしておく必要があります。デフォルトでは、サブジェクト (sub) クレーム値を使用して ID トークンとログアウトトークンの照合を行いますが、代わりにセッション ID (sid) クレームを使用することも可能です。

quarkus.oidc.logout.backchannel.token-cache-size、 quarkus.oidc.logout.backchannel.token-cache-time-to-live、および quarkus.oidc.logout.backchannel.clean-up-timer-interval は、バックチャネル通知キャッシュを管理するためのプロパティーです。

フロントチャネルログアウトは、概念的には バックチャネルログアウト と似ていますが、通知がブラウザー経由で Quarkus に転送される点が異なります。詳細は OIDC フロントチャネルログアウト セクションを参照してください。

quarkus.oidc.logout.frontchannel.path は、ブラウザーがフロントチャネルログアウトリクエストを送信する保護されたパスです。

ログアウト後、Quarkus OIDC に Clear-Site-Data レスポンスヘッダーを送信させることが可能です。これには、ブラウザーキャッシュのクリア方法をブラウザーに指示する 1 つ以上のディレクティブが含まれます。

cache、 client-hints、 cookies、 execution-contexts、およびワイルドカード * のディレクティブを設定できます。

ID トークンやアクセストークンは、検証プロセスを開始して成功させるために、復号化したりヘッダーを前処理したりする必要がある場合があります。

OIDC プロバイダーは通常、署名済みの ID トークンやアクセストークンを発行しますが、さらにこれらのトークンを暗号化する場合もあり、Quarkus は検証のためにこれらを復号化する必要があります。復号化が必要なトークンタイプを、ID トークンなら quarkus.oidc.token.decrypt-id-token、アクセストークンなら quarkus.oidc.token.decrypt-access-token で選択してください。

JWE 暗号化が使用されていることを示すドット文字で区切られた 5 つのパートが含まれている場合、ID トークンとアクセストークンの両方が暗号化されているとみなされます。

後方互換性の理由により、 quarkus.oidc.token.decryption-key-location が設定されている場合は ID トークンの復号化が試行されますが、復号キー選択の柔軟性を高めるために、代わりにオプションの quarkus.oidc.token.decrypt-id-token ブール値プロパティーを使用することが推奨されます。

ID トークンまたはアクセストークンの復号化が必要な場合、まず quarkus.oidc.token.decryption-key-location がチェックされます。このプロパティーが設定されていない場合は、利用可能であれば JWT クライアントクレデンシャル キーが使用されます。最後に、復号キーがまだ初期化されていない場合は、設定されたクライアントシークレットが復号キーとして使用されます。

quarkus.oidc.token.customizer-name は、署名の検証前に JWT トークンのヘッダーを前処理できる特定の io.quarkus.oidc.TokenCustomizer 実装を選択するために使用される高度なプロパティーです。主なユースケースは、署名検証を成功させるために nonce ヘッダーを再計算する必要があるレガシーな Azure JWT トークンの検証サポートです。

トークン検証のクレームプロパティーはコアなトークン検証プロセスに影響を与え、トークンクレームやイントロスペクションプロパティーが特定の発行者、オーディエンス、有効期間などの制限を満たす必要があります。

トークンが特定の発行者によって発行されたことを強制することが推奨されます。プロバイダーがディスカバリーをサポートしている場合はトークン発行者が自動検出されますが、そうでない場合は quarkus.oidc.token.issuer に特定の値を設定できます。

トークンが特定のオーディエンス向けであることを強制することが推奨されます。ID トークンは、デフォルトで quarkus.oidc.client-id プロパティーと一致するオーディエンス値を持つ必要があります。ベアラーアクセストークンの場合、オーディエンスは標準化されておらず、例えばターゲットエンドポイントを表す URL になることもあります。可能な場合は、ベアラーアクセストークンも特定のオーディエンス値を持つように制限する必要があります。

quarkus.oidc.token.subject-required を使用して、トークンが一意のサブジェクト値を持つことを強制できます。プロバイダーがトークンにサブジェクトを割り当てる場合は、特に複数の OIDC および OAuth2 プロバイダーを扱い、一意のユーザー識別子を取得したい場合に、これを必須にすることが推奨されます。一部のプロバイダーは常にこれを設定するとは限らないため、このプロパティーはデフォルトでは設定されていません。たとえば、Keycloak の軽量アクセストークンにはサブジェクト (sub) クレームが含まれない場合があります。

quarkus.oidc.token.issued-at-required は、トークンの 発行時刻 (iat) クレームを設定しないプロバイダーを扱う必要がある場合に false に設定できます。

quarkus.oidc.token.age プロパティーを使用すると、有効なトークンをどのくらいの期間使用できるかを強制できます。たとえば、一部のプロバイダーは数ヶ月間有効なトークンを発行することがありますが、ユーザーが非常に長期間有効なアクセストークンで Quarkus にアクセスできるようにしたくない場合はどうすればよいでしょうか。このような場合、トークンの有効期間を 1 日などの妥当な値に設定できます。

quarkus.oidc.token.lifespan-grace プロパティーは、発生しうるクロックスキューによるトークン検証の失敗を避けるためだけにのみ使用されるべきです。

quarkus.oidc.token.token-type は、プロバイダーがタイプ (typ) クレームを設定することがわかっている場合に、トークンタイプを強制するために使用できます。たとえば、Keycloak は JWT 形式で ID トークン、アクセストークン、リフレッシュトークンを発行しますが、SPA が ID トークンをベアラーアクセストークンであるかのように Quarkus に送信するのをどのように防ぐことができますか？ quarkus.oidc.token.token-type=bearer を設定すると、 bearer 値を持つタイプ (typ) クレームを含む JWT アクセストークンのみが受け入れられるように強制されます。

quarkus.oidc.token.principal-claim を使用すると、Java Security Principal および MicroProfile JWT JsonWebToken API でプリンシパル名を取得する際に使用されるトークンクレームをカスタマイズできます。デフォルトでは、upn、preferred_username、sub といったクレームがプリンシパル名の検索に使用されますが、一部のトークンでは name またはその他のクレームに含まれている場合があります。その場合、quarkus.oidc.token.principal-claim=name などと設定できます。

quarkus.oidc.token.required-claims マッププロパティーを使用すると、トークンに特定の文字列クレーム値が含まれているかどうかの追加の簡単なチェックを提供できます。

JWT トークン検証のカスタマイズについての詳細は、 Jose4 Validator セクションも参照してください。

デフォルトでは、Quarkus は利用可能な検証キーを使用して、OIDC プロバイダーと利用可能なキーセットによってサポートされている非対称アルゴリズムで JWT トークンの署名を検証します。たとえば、JWK セットに RS256 または PS256 アルゴリズムのいずれかで作成された RSA 署名を検証できる公開鍵が含まれている場合、そのアルゴリズムで署名されたトークンを受け入れることができます。ただし、RS512 などの特定のアルゴリズムのみを使用する必要があるポリシーがある場合は、quarkus.oidc.token.signature-algorithm=RS512 を使用してこれを強制します。

Quarkus OIDC には プライマリー トークンという概念があります。ベアラーアクセストークンは、ベアラーアクセストークンフローで使用される唯一のトークンであり、外部クライアントが Quarkus にアクセスするために使用されるため、プライマリートークンです。ベアラーアクセストークンは 常に検証されます。ID トークンは認可コードフローにおける プライマリー トークンであり、現在認証されているユーザーを表します。ID トークンは 常に検証されます。

コードフローアクセストークンは、認可コードフローを完了した現在の Quarkus アプリケーションにアクセスするために使用されるものではないため、プライマリートークンではありません。OIDC であろうと OAuth2 であろうと、コードフローアクセストークンは現在認証されているユーザーに代わって別のサービスにアクセスするために使用されるものです。たとえば、プロバイダーへの認証リダイレクト中に openid スコープを送信すると、アクセストークンが発行され、Quarkus アプリケーションはそのユーザーに代わってこのプロバイダーから UserInfo を取得するために使用できます。

それを検証するのは、この Quarkus アプリケーションがコードフローアクセストークンを使用してアクセスする必要がある OIDC プロバイダー、またはダウンストリームの Quarkus サービスのいずれかの役割です。これが、コードフローアクセストークンがバイナリトークンとして提供されることが多い理由の 1 つです。

ただし、通常 JWT 形式であるコードフローアクセストークンを、ロールやアプリケーションに関連するその他の情報のソースとして使用することを想定してアプリケーションを設計した場合は、quarkus.oidc.authentication.verify-access-token=true を設定してください。Quarkus は、アプリケーションコードに @IdToken 修飾子のない JsonWebToken が注入されていることを検出した場合、アプリケーションがコードフローアクセストークンへのアクセスを意図していると判断し、このプロパティーを自動的に有効にします。

入ってくるベアラーアクセストークンがバイナリ形式である場合や、リモートイントロスペクションエンドポイントが利用できない OAuth2 プロバイダーでユーザーをログインさせ、Quarkus がバイナリのアクセストークンしか受け取らない場合、このバイナリトークンをどのように検証すればよいでしょうか。

唯一のオプションは、有効なアクセストークンを UserInfo エンドポイントに転送する必要がある際に、このバイナリトークンを使用して OIDC 標準または OAuth2 プロバイダー固有の UserInfo エンドポイントへのアクセスを試みることによる間接的なアクセストークン検証です。必要に応じて quarkus.oidc.token.verify-access-token-with-user-info=true を設定してください。

詳細は OAuth2 プロバイダー セクションも参照してください。

JWT トークンの署名を検証する必要がある場合、そのトークンのキー識別子 (kid) ヘッダー値を使用して、ローカルの検証用公開鍵セットから一致する JWK キーを検索します。しかし、プロバイダーは定期的に署名鍵ペアをリサイクルし、新たに発行するトークンに新しい秘密鍵で署名し始める傾向があるため、ある時点でローカルの鍵セットに現在の JWT を検証するための一致する公開鍵がなくなる可能性があります。この場合、Quarkus は検証キーセットの更新を試みますが、ランダムなトークンの大量送信によってリモートへの JWK セット更新リクエストが過剰に発生するリスクを最小限に抑えるため、quarkus.oidc.token.forced-jwk-refresh-interval で指定された期間は追加の JWK キーセット更新試行をブロックします。

一部の OIDC プロバイダーはリモートトークンイントロスペクションエンドポイントをサポートしており、Quarkus はキーセットを更新した後でも一致する JWK 検証キーが見つからない場合、JWT トークンのイントロスペクションにフォールバックします。しかし、プロバイダーがイントロスペクションエンドポイントをサポートしているからといって、デプロイメントポリシーでリモート JWT トークンイントロスペクションが禁止されている場合があります。トークンに機密性の高いクレームが含まれている可能性や、パフォーマンス上の理由があるためです。特に、たとえば ID トークンはリモートでイントロスペクションできず、JWK キーでローカルに検証するしかないことが分かっている場合はそうでしょう。リモートイントロスペクションに JWT トークンを送信したくない場合は、quarkus.oidc.token.allow-jwt-introspection=false を設定してください。

一方で、quarkus.oidc.token.require-jwt-introspection-only は、現在の JWT トークンが有効かどうかの判断を OIDC プロバイダー自身のみが行うように強制します。これは例えば、現在のトークンが既に失効していることを即座に認識したい場合などに有効です。この場合、Quarkus が JWKs エンドポイントを検出して、結局使用されない検証キーを取得するのを防ぐために、quarkus.oidc.discovery-enabled=false でディスカバリーも無効にすることが一般的です。

quarkus.oidc.token.allow-opaque-token-introspection は、セキュリティーを強化するためのプロパティーです。Quarkus OIDC はデフォルトで、送られてくるあらゆるアクセストークンの検証を試みます。しかし、JWT トークンを扱う場合、特に quarkus.oidc.token.allow-jwt-introspection=false でローカルのみでの検証を優先している場合に、アプリケーションが想定していないバイナリ (不透明) アクセストークンが送信されたらどうなるでしょうか。quarkus.oidc.token.allow-opaque-token-introspection=false を設定することで、混乱を招く可能性のあるリモートイントロスペクションの呼び出しを防止し、不透明トークンを受信した際に即座に検証エラーを発生させることができます。

デフォルトでは、トークンの groups 配列クレームにロールが含まれていることが期待されます。トークンが Keycloak によって発行された場合に備えて、realm_access/roles および realm_access/<client-id>/roles クレームもチェックされます。しかし、トークンにロールを含む別のカスタムクレームがある場合は、quarkus.oidc.roles.role-claim-path でそれを指定できます。これを使用して、最上位の配列クレームや、/ パスセパレーターを使用したネストされたクレームを選択できます。名前空間で修飾されたクレーム名には、必ず quarkus.oidc.roles.role-claim-path="http://auth0.customroles/roles" のように二重引用符を使用してください。

scope クレームをロールのソースとして扱いたい場合、scope クレーム内のスペースで区切られた各値がロール名となります。しかし、複数のロール値を含む文字列クレームは、カンマ , やその他の文字で区切られている場合もあります。そのような場合には quarkus.oidc.roles.role-claim-separator=, などを使用してください。

デフォルトではプライマリートークンがロールのソースとなります。認可コードフローでは ID トークンのロールがチェックされ、ベアラートークンフローではアクセストークンのロールがチェックされます。アプリケーションで認可コードフローを使用しており、プライマリーな ID トークンではなくアクセストークンをチェックする必要がある場合は、quarkus.oidc.roles.source=access_token と設定できます。ベアラーアクセストークンを扱う場合は、このプロパティーを設定する必要はありません。

ロールが UserInfo レスポンスに含まれている場合もあります。その場合は quarkus.oidc.roles.source=userinfo を設定してください。

トークンバインディングは、アクセストークンを送信者に制限するためのツールです。

quarkus.oidc.token.binding.certificate=true を使用すると、 RFC 8705: Mutual TLS token binding 仕様に記載されているように、ベアラーアクセストークンを送信元の MTLS クライアントに制限できます。

詳細は 相互 TLS トークンバインディング セクションを参照してください。

Demonstrating Proof of Possession (DPoP) バインディングを有効にする方法の詳細は、 ベアラートークンヘッダー セクションも参照してください。

ベアラーアクセストークンの送信には、通常 Bearer スキームを用いた HTTP Authorization ヘッダーが使用されます。例: Authorization: Bearer <token>。

場合によっては、ヘッダーとスキームの両方をカスタマイズする必要があります。

どの HTTP ヘッダーにベアラーアクセストークンを含めるかをカスタマイズするために、 quarkus.oidc.token.header と quarkus.oidc.token.authorization-scheme を使用できます。ヘッダーをカスタマイズでき、HTTP Authorization が使用される場合はスキームもカスタマイズ可能です。

たとえば、 quarkus.oidc.token.authorization-scheme=DPoP を設定することで、 Authorization: DPoP <token> として送信される DPoP アクセストークンを受け入れることができます。詳細は Demonstrating Proof of Possession セクションを参照してください。

トークンバインディング セクションも参照してください。

リモートトークンイントロスペクションと UserInfo の結果を複数のリクエスト間で共有することで、すべてのトークンに対して毎回リモートイントロスペクションや UserInfo の呼び出しを行うことを避けることができます。そうすることでアプリケーションは即時のトークンステータスの変更、たとえばトークンの失効や無効化、あるいは現在のユーザーがこのトークンを発行した組織に実際にはもう所属していないなどの状態を見逃し、キャッシュされたトークンイントロスペクションまたは UserInfo 情報が古くなる可能性があります。したがって、トークンイントロスペクションと UserInfo の結果をキャッシュすることに関連するプロパティーは、リスクを慎重に評価した上でユーザーが有効にする必要があります。

Quarkus OIDC は、 すべて の OIDC テナントに対してデフォルトのトークンイントロスペクションおよび UserInfo キャッシュを提供します。たとえば、GitHub と Strava の OAuth2 認証をサポートしている場合、GitHub と Strava の UserInfo レスポンスを同じデフォルトキャッシュに保存でき、GitHub または Strava のアクセストークンをキーとして使用します。このキャッシュは quarkus.oidc.default-token-cache-enabled ビルド時プロパティーによってデフォルトで有効になりますが、トークンイントロスペクションまたは UserInfo (あるいはその両方) をこのキャッシュに保存することを選択しない限り、エントリーは追加されません。

quarkus.oidc.allow-token-introspection-cache と quarkus.oidc.allow-user-info-cache を使用して、 OIDC テナント単位 でトークンイントロスペクションと UserInfo 結果のキャッシュをそれぞれ有効にできます。

quarkus.oidc.token-cache.max-size、 quarkus.oidc.token-cache.time-to-live、および quarkus.oidc.token-cache.clean-up-timer-interval は、デフォルトのトークンイントロスペクションと UserInfo キャッシュを管理するためのプロパティーです。

トークンイントロスペクションと UserInfo 結果キャッシュの両方のカスタマイズについての詳細は、 トークンイントロスペクションキャッシュ および UserInfo キャッシュ セクションも参照してください。

quarkus.oidc.cache-user-info-in-idtoken は、セッションクッキー内で内部 ID トークンが生成され暗号化される OAuth2 プロバイダーを使用する場合に利用可能なキャッシュ最適化オプションです。この場合、UserInfo の JSON を暗号化前の生成された ID トークンに直接保存できるため、サーバー側で UserInfo キャッシュを保持する必要がなくなります。

場合によっては、入ってくる JWT トークンに一致する検証キーが全くなく、イントロスペクションもできないことがあります。これらのトークンには x5c クレームのみが含まれており、そこにはトークンの署名を検証するために使用できる公開鍵を含む証明書チェーンが含まれています。たとえば、SCIM プロビジョニングエージェント、WebAuthn システムがこのようなトークンを生成することがあります。

Quarkus OIDC は、この公開鍵を含むトークンの証明書チェーンをアプリケーションが信頼することを証明できるまで、トークン内にインライン化された公開鍵を使用することはできません。

quarkus.oidc.certificate-chain.trust-store-file が利用可能であり、 少なくとも ルート証明書を含むファイルを指している必要があります。このトラストストアへのアクセスを容易にするために、 quarkus.oidc.certificate-chain.trust-store-password および quarkus.oidc.certificate-chain.trust-store-file-type を使用できます。

quarkus.oidc.certificate-chain.trust-store-cert-alias を使用して、トークンの証明書チェーンのルート証明書に一致する特定の証明書を選択できます。

quarkus.oidc.certificate-chain.leaf-certificate-name は、トラストストアにリーフチェーン証明書が含まれていることを要求することもできます。

Quarkus OIDC はルート証明書の一致を強制し、さらに他の証明書チェーンチェックを実行して、チェーン内の各証明書が期限切れでなく、チェーン内の次の証明書によって (ルート証明書を除く) 正しく署名されていることを確認します。

追加の証明書チェーンチェックの提供に関する詳細は、 証明書チェーンの検証 セクションも参照してください。

quarkus.oidc.public-key はインラインの公開検証鍵を含むことができ、OIDC テストに使用されます。

Oidc startup event を監視し、 OicTenantConfig ビルダー API を使用して 1 つ以上の OIDC テナントを登録できます。

TenantConfigResolver を登録し、 OicTenantConfig ビルダー API を使用して、リクエストパスやヘッダーなどのリクエストプロパティーを追加のヒントとして使用したり、外部ソースから一致する設定を取得したりして、設定を動的に構築できます。

このビルド時プロパティーは、 quarkus-smallrye-health 依存関係が含まれている場合に OIDC Provider Health Readiness Check を登録するために使用できます。ヘルスチェックが登録されると、HTTP HEAD を使用して、設定されたすべての OIDC テナントの well-known な OIDC プロバイダー設定エンドポイントに ping を送信します。

個々の OIDC テナントのステータスは、 OK 、 Not Ready 、 Disabled 、 Unknown 、および Error です。

OIDC ヘルスチェックのステータスは、少なくとも 1 つの OIDC テナントのステータスが OK であれば UP になり、それ以外の場合は DOWN になります。

ベアラーアクセストークンのサポートを開始するために必要なプロパティーは 1 つだけです。

この単一のプロパティーの組み合わせは、OIDC プロバイダーがメタデータディスカバリーをサポートし、送られてくるベアラーアクセストークンが、プロバイダーの JWK エンドポイントから取得した鍵で検証可能な JWT 形式である場合に機能します。

開発モード でベアラーアクセストークンを使い始めるために、何も設定する必要はありません。

認可コードフローを開始するには、4 つのプロパティーが必要です。

このプロパティーの組み合わせは、OIDC プロバイダーがメタデータディスカバリーをサポートしている場合に機能します。

アプリケーションのセキュアな領域が単一の URL よりも広い場合、特定のコールバック URL のみが登録可能であることを要求する OIDC プロバイダーをサポートするために、多くの場合 redirect-path プロパティーを追加する必要があります (例: quarkus.oidc.authentication.redirect-path=/callback)。

開発モード で認可コードフローを開始するには、 quarkus.oidc.application-type=web-app を設定するだけです。

厳格なベアラーアクセストークンのサポートとは、issuer、audience、およびその他の主要なクレームが特定の値に設定されているか、または利用可能であることを強制することを意味します。

厳格な認可コードフローのサポートとは、issuer、audience、およびその他の主要なクレームが特定の値に設定されているか、または利用可能であることを強制することを意味します。

何をもって厳格なベアラーアクセストークンまたは認可コードフローのサポートとするかは、デプロイメントによって大きく異なります。たとえば、ある OIDC プロバイダーは MTLS クライアント認証を必要とし、別のプロバイダーは DPoP バインディングや PKCE サポートを必要とする場合があります。組み合わせが多すぎるため、このドキュメントですべてをカバーすることはできません。

より厳格でタイトな OIDC 設定の作成に関するさらなるガイダンスが必要な場合は、私たちがお手伝いします。Issue を作成したり、Quarkus Discussions や Zulip の users チャネルでチームに連絡したりしてください。

上記の トークンロール セクションで説明したように、デフォルトではトークンの groups クレームがアイデンティティーロールのチェックに使用されます。また、ロールを含むカスタムクレームを設定で選択することもできます。ただし、現在のトークンアイデンティティーに関連付けられたロールと権限を正しく判断するために、追加のカスタマイズやチェックが必要になる場合があります。

プライマリー ID またはアクセストークンから作成されたアイデンティティーをオーグメントするために、io.quarkus.security.identity.SecurityIdentityAugmentor を使用します。

その他の認可制御オプションについては、 HttpSecurityPolicy および PermissionChecker セクションも参照してください。

トークンイントロスペクションと UserInfo キャッシュ セクションで説明されているデフォルトのキャッシュ実装の代わりに、カスタムのトークンイントロスペクションキャッシュ実装をサポートするために quarkus.oidc.TokenIntrospectionCache プロバイダーを登録できます。

トークンイントロスペクションと UserInfo キャッシュ セクションで説明されているデフォルトのキャッシュ実装の代わりに、カスタムの UserInfo キャッシュ実装をサポートするために quarkus.oidc.UserInfoCache プロバイダーを登録できます。

上記の 認可コードフローのトークンの保存 セクションで説明したように、Quarkus OIDC は、認可コードフロートークンを保存するためのステートレス (デフォルト) およびステートフルなオプションをすでに提供しています。独自のカスタム io.quarkus.oidc.TokenStateManager 実装を提供することもできます。

OIDC フィルターを使用して、すべての OIDC エンドポイントへのリクエストとレスポンスを監視できます。

OIDC リダイレクト要求をインターセプトすることもできます。

SPA 統合 セクションで説明されているように、一部の OIDC プロバイダーが認可エンドポイントの CORS をサポートしていないという事実に対処するため、Quarkus OIDC はエラーを返して SPA の認可コードフローを開始し、それをインターセプトすることができます。

Quarkus OIDC がこれを行うには、リクエストが SPA から来たものであるかどうかを知る必要があります。デフォルトでは、値が JavaScript または XMLHttpRequest に設定された X-Requested-With リクエストヘッダーが利用可能かどうかをチェックします。

カスタムの quarkus.oidc.JavaScriptRequestChecker リクエストチェッカーを使用した JavaScript リクエストチェックのカスタマイズに関する詳細は、 SPA との統合 ドキュメントを参照してください。

ログアウト セクションで説明されているログアウト設定は、標準的な OIDC ログアウトメカニズムをサポートしており、Quarkus エンドポイントが OIDC プロバイダーとログアウトプロセスを調整します。ローカルセッション Cookie をクリアするためだけに ローカルログアウト を行いたい場合もあります。

認証、ログアウトなどに関連する OIDC イベントを監視できます。詳細は OIDC イベントのリスニング セクションを参照してください。

現在のベアラーまたは認可コードフローのアクセストークンをダウンストリームサービスに伝播する必要がある場合は、 Quarkus OIDC トークン伝播機能 を使用してください。伝播する必要のあるトークンを交換することができます。

たとえばローカルログアウトの場合などに、アクセストークンを失効させる必要があるかもしれません。詳細は トークンの失効 セクションを参照してください。

OAuth2 Protected Resource Metadata 仕様は、OAuth 2.0 クライアントが OAuth 2.0 保護リソースと対話するために必要な情報を取得できるメタデータ形式を定義しています。

Quarkus OIDC は初期の 保護されたリソースのメタデータ サポートを提供しており、Quarkus エンドポイントがそのエンドポイントを保護する OIDC または OAuth2 プロバイダーの URL を返せるようにします。その結果、保護されたリソースのメタデータを要求したクライアントは、認可サーバー URL などのプロパティーを使用して、プロバイダーのメタデータを検出し、そのプロバイダーと連携するためのブートストラップを自身で行うことができます。たとえば、SPA ユーザーをログインさせ、ベアラーアクセストークンを使用して彼らに代わって Quarkus にアクセスすることができます。

quarkus.oidc.resource-metadata.enabled プロパティーは Quarkus OIDC が保護されたリソースのメタデータを返せるようにするもので、デフォルトでは無効になっています。その理由は、エンドポイントを保護している認可サーバーのリストを公開クライアントに見せることはセキュリティー情報の漏洩とみなされる可能性があるためであり、そのような情報を公開することが安全であると考えられる場合にのみ有効にすべきです。

quarkus.oidc.resource-metadata.resource は保護されたリソース識別子を表します。 OAuth2 Protected Resource Metadata 仕様に従って、公開されるメタデータ内では HTTPS ベースの URL として提示される必要があり、この URL の構造はクライアントが保護されたリソースのメタデータにアクセスするために使用した well-known URL と整合していなければなりません。

quarkus.oidc.resource-metadata.resource は絶対 URL として設定できます。

相対パスとして設定されている場合は、現在のリクエスト URL のホストとポートに追加され、リソース識別子 URL が構築されます。まったく設定されていない場合は、デフォルトのテナント ID でない限り、テナント ID が現在のリクエスト URL のホストとポートに追加され、リソース識別子 URL が構築されます。

デフォルトでは、 quarkus.oidc.resource-metadata.resource が設定されていない場合、保護されたリソースメタデータのルートは /.well-known/oauth-protected-resource という相対アドレスで利用可能です。

quarkus.oidc.resource-metadata.resource を相対値に設定すると、保護されたリソースメタデータルートのアドレスに影響します。たとえば、デフォルトの OIDC テナントに対して quarkus.oidc.resource-metadata.resource=resource と設定すると、その保護されたリソースメタデータルートは /.well-known/oauth-protected-resource/resource で利用可能になります。

リソース識別子 URL のスキームは、デフォルトで HTTPS に設定されています。 quarkus.oidc.resource-metadata.force-https-scheme=false を設定すると HTTP URL スキームを有効にでき、これは単純なデモやテストで特に役立ちます。

quarkus.oidc.resource-metadata.authorization-server を使用すると、リソースメタデータに含まれる認可サーバー URL をカスタマイズできます。デフォルトでは quarkus.oidc.auth-server-url の URL が含まれますが、OIDC プロキシが実際の OIDC プロバイダーを仲介するような一部のケースでは、代わりに OIDC プロキシの URL を返すことが必要になります。

Quarkus OIDC が動作に使用する OIDC プロバイダーのメタデータの詳細については、 メタデータ も参照してください。