トークン交換の使用

この典型的なトークン交換フローを考えてみましょう。

トークン交換には他の多くのユースケースがありますが、上記の例が最も典型的です。

標準トークン交換の場合、token-exchange-standard:v2 はデフォルトで有効になっています。ただし、前の例の requester-client など、トークン交換リクエストを送信するクライアントに対して、標準トークン交換スイッチを有効にする必要もあります。requester-client はコンフィデンシャルクライアントである必要があることに注意してください。また、他のグラントリクエストの場合と同様に、トークン交換リクエストは、クライアントに構成されている適切なクライアント認証方法によって認証される必要があります。

パラメータは、トークン交換仕様に合わせており、次のように説明されています。

成功したレスポンスは、JSON 形式で返されます。他のグラントからのレスポンスと同様のパラメータが含まれています。以下は、より注目すべきパラメータのトークン交換の仕様です。

トークン交換リクエストの scope パラメータは、他のグラントと同じ意味を持ちます。このパラメータはオプションです。省略した場合、リクエストで使用される有効なクライアントスコープは、requester-client のデフォルトのクライアントスコープです。このパラメータを使用する場合、有効なクライアントスコープは、デフォルトのスコープとオプションのクライアントスコープを組み合わせたものです。

デフォルトでは、使用されるクライアントスコープは、オーディエンスドキュメントで指定されているように、使用されるクライアントスコープとクライアントロールに基づいて、トークンの aud クレームにオーディエンスを追加します。

audience パラメータは、オーディエンスのフィルタリングに使用できます。これにより、aud クレームには audience パラメータで指定されたオーディエンスのみが含まれます。同様に、トークン内のクライアントロールもフィルタリングされ、トークンには audience パラメータで指定されたクライアントのクライアントロールのみが含まれます。

さらに、audience パラメータを使用して、クライアントスコープもフィルタリングできる可能性があります。ユーザーのクライアントスコープ権限と同様の方法で機能します。クライアントスコープにクライアントロールが含まれていない場合 (たとえば、ロールがゼロであるか、レルムロールのみが含まれている場合)、クライアントスコープの追加フィルタリングは発生しません。ただし、クライアントスコープにクライアントロールマッピングが含まれている場合は、audience パラメータでリクエストされたクライアントのクライアントロールをいくつか含める必要があります。コンポジットロールも考慮の対象に含まれます。クライアントスコープに audience でリクエストされたクライアントのクライアントロールが含まれていない場合、クライアントスコープはフィルタリングされます。

これらの追加ポイントは、トークン交換の動作を明確にしています。

前のセクションでは、標準トークン交換とレガシートークン交換について詳しく説明しましたが、以下は、2 つのトークン交換方法を比較する全体的な概要です。

Keycloak では、トークン交換は、一連のクレデンシャルまたはトークンを使用して、まったく異なるトークンを取得するプロセスです。クライアントは、信頼性の低いアプリケーションで呼び出したい場合があるため、現在持っているトークンをダウングレードしたい場合があります。クライアントは、Keycloak トークンを、リンクされたソーシャルプロバイダーアカウント用に保存されたトークンと交換したい場合があります。他の Keycloak レルムまたは外部 IDP によって発行された外部トークンを信頼したい場合があります。クライアントは、ユーザーを偽装する必要がある場合があります。Keycloak の現在のトークン交換に関する機能の簡単な概要を次に示します。

Keycloak のトークン交換は、IETF の OAuth トークン交換仕様の非常に緩い実装です。少し拡張したり、一部を無視したり、仕様の他の部分を緩く解釈したりしました。これは、レルムの OpenID Connect トークンエンドポイントでの単純なグラントタイプ呼び出しです。

フォームパラメータ (application/x-www-form-urlencoded) を入力として受け入れ、出力は交換をリクエストしたトークンのタイプによって異なります。トークン交換はクライアントエンドポイントであるため、リクエストは呼び出しクライアントの認証情報を提供する必要があります。パブリッククライアントは、フォームパラメータとしてクライアント識別子を指定します。コンフィデンシャルクライアントは、フォームパラメータを使用してクライアント ID とシークレット、Basic Auth、または管理者がレルムでクライアント認証フローを構成した方法を渡すこともできます。

内部トークンからトークンへの交換では、特定のクライアントに発行された既存のトークンがあり、このトークンを別のターゲットクライアント用に発行された新しいトークンと交換したいと考えています。なぜこれを行う必要があるのでしょうか？これは一般的に、クライアントが自身に発行されたトークンを持っており、アクセストークン内で異なるクレームと権限を必要とする他のアプリケーションに追加のリクエストを行う必要がある場合に発生します。このタイプの交換が必要になる可能性のある他の理由としては、アプリが信頼性の低いアプリを呼び出す必要があり、現在のアクセストークンを伝播したくない場合に「権限のダウングレード」を実行する必要がある場合などがあります。

レルムトークンを、外部アイデンティティプロバイダーによって発行された外部トークンと交換できます。この外部アイデンティティプロバイダーは、管理コンソールの Identity Provider セクション内で設定されている必要があります。現在、OAuth/OpenID Connectベースの外部アイデンティティプロバイダーのみがサポートされており、これにはすべてのソーシャルプロバイダーが含まれます。Keycloakは、外部プロバイダーへのバックチャネル交換を実行しません。したがって、アカウントがリンクされていない場合、外部トークンを取得することはできません。外部トークンを取得できるようにするには、次のいずれかの条件を満たす必要があります。

最後に、外部アイデンティティプロバイダーがトークンを保存するように設定されているか、または上記のいずれかのアクションが、交換する内部トークンと同じユーザーセッションで実行されている必要があります。

アカウントがリンクされていない場合、交換レスポンスには、アカウントを確立するために使用できるリンクが含まれます。これについては、リクエストの作成セクションで詳しく説明します。

外部アイデンティティプロバイダーによって発行された外部トークンを信頼し、内部トークンと交換できます。これは、レルム間をブリッジしたり、ソーシャルプロバイダーからのトークンを信頼したりするために使用できます。新しいユーザーが存在しない場合、レルムにインポートされるという点で、アイデンティティプロバイダーのブラウザログインと同様に機能します。

交換が完了すると、レルム内にユーザーセッションが作成され、requested_token_type パラメータ値に応じて、アクセスおよび/またはリフレッシュトークンを受け取ります。この新しいユーザーセッションは、タイムアウトするか、この新しいアクセストークンを渡してレルムのログアウトエンドポイントを呼び出すまでアクティブなままになることに注意してください。

これらのタイプの変更には、管理コンソールで設定されたアイデンティティプロバイダーが必要です。

内部および外部トークン交換の場合、クライアントはユーザーに代わって別のユーザーになりすますように要求できます。たとえば、サポートエンジニアが問題をデバッグできるように、ユーザーになりすます必要がある管理者アプリケーションがある場合があります。

subject_token を指定せずに、内部トークン交換リクエストを作成できます。これは、クライアントがレルム内の任意のユーザーになりすますことができるため、クライアントに多くの信頼を置くため、直接的なネイキッドなりすましと呼ばれます。交換するサブジェクトトークンを取得することが不可能なアプリケーションをブリッジするために、これが必要になる場合があります。たとえば、LDAPで直接ログインを実行するレガシーアプリケーションを統合している場合があります。その場合、レガシーアプリはユーザー自身を認証できますが、トークンを取得することはできません。

クライアントに交換の許可を付与する場合、必ずしもすべてのクライアントに対して手動でこれらの権限を有効にする必要はありません。クライアントにサービスアカウントが関連付けられている場合、ロールを使用して権限をグループ化し、クライアントのサービスアカウントにロールを割り当てることで交換権限を割り当てることができます。たとえば、naked-exchange ロールを定義すると、そのロールを持つサービスアカウントはネイキッド交換を実行できます。

トークン交換を許可し始めると、注意すべき点と注意すべき点がいくつかあります。

最初の点はパブリッククライアントです。パブリッククライアントは、交換を実行するためにクライアント認証情報を必要としません。有効なトークンを持っている人は誰でも、パブリッククライアントをなりすまし、そのパブリッククライアントが許可されている交換を実行できます。レルムによって管理されている信頼できないクライアントがある場合、パブリッククライアントは権限モデルに脆弱性をもたらす可能性があります。これが、直接的なネイキッド交換がパブリッククライアントを許可せず、呼び出し元クライアントがパブリッククライアントの場合にエラーで中止する理由です。

Facebook、Googleなどによって提供されるソーシャルトークンをレルムトークンと交換することができます。交換トークンが何を行うことを許可されているかに注意し、警戒してください。これらのソーシャルウェブサイトで偽のアカウントを作成することは難しくありません。デフォルトのロール、グループ、およびアイデンティティプロバイダーマッパーを使用して、外部ソーシャルユーザーに割り当てられる属性とロールを制御します。

直接的なネイキッド交換は非常に危険です。呼び出し元クライアントがクライアント認証情報を漏洩させないことに多くの信頼を置いています。これらの認証情報が漏洩した場合、泥棒はシステム内の誰にでもなりすますことができます。これは、既存のトークンを持つ機密クライアントとは対照的です。アクセストークンとクライアント認証情報の2つの認証要素があり、1人のユーザーのみを扱っています。したがって、直接的なネイキッド交換は控えめに使用してください。