Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

第5章 アイデンティティーブローカー API

Red Hat build of Keycloak は、親 IDP にログイン認証を委譲できます。典型的な例としては、Facebook や Google などのソーシャルプロバイダーを使用してユーザーがログインできるようにするケースがあります。既存のアカウントをブローカー化された IDP にリンクすることもできます。このセクションでは、アイデンティティーブローカーに関連するので、アプリケーションが使用する API も一部説明します。

5.1. 外部 IDP トークンの取得
リンクのコピー

Red Hat build of Keycloak を使用すると、外部 IDP を使用して認証プロセスからのトークンと応答を保存できます。これには、IDP の設定ページで Store Token 設定オプションを使用できます。

アプリケーションコードは、これらのトークンを取得し、追加のユーザー情報でプルしたり、外部 IDP でリクエストを安全に呼び出すことを行うことができます。たとえば、アプリケーションは Google トークンを使用して他の Google サービスおよび REST API で呼び出す場合があります。特定のアイデンティティープロバイダーのトークンを取得するには、以下のようにリクエストを送信する必要があります。 

GET /realms/{realm-name}/broker/{provider_alias}/token HTTP/1.1
Host: localhost:8080
Authorization: Bearer <KEYCLOAK ACCESS TOKEN>
Copy to Clipboard Toggle word wrap

アプリケーションは、Red Hat build of Keycloak で認証され、アクセストークンを受け取っている必要があります。このアクセストークンには、ブローカー のクライアントレベルのロール read-token を設定する必要があります。そのため、ユーザーにはこのロールのロールマッピングが必要で、クライアントアプリケーションにそのスコープ内にそのロールがなければなりません。この場合、Red Hat build of Keycloak で保護されたサービスにアクセスする場合には、ユーザー認証時に Red Hat build of Keycloak が発行するアクセストークンを送信する必要があります。ブローカー設定ページでは、Stored Tokens Readable スイッチを有効にして、新たにインポートしたユーザーにこのロールを自動的に割り当てることができます。

これらの外部トークンは、プロバイダーを通じて再度ログインするか、クライアント起点のアカウントリンク API を使用することによって再確立できます。

<_client-initiated-account-linking><title>クライアント起点のアカウントリンク</title>

アプリケーションによっては、Facebook などのソーシャルプロバイダーと統合しても、このようなソーシャルプロバイダー経由でログインするオプションを提供しないようにする場合もあります。Red Hat build of Keycloak は、アプリケーションが既存のユーザーアカウントを特定の外部 IDP にリンクするために使用できるブラウザーベースの API を提供します。これは、クライアント起点のアカウントリンクと呼ばれます。アカウントリンクは OIDC アプリケーションによってのみ開始できます。

アプリケーションがユーザーのブラウザーを Red Hat build of Keycloak サーバーの URL に転送する方法は、ユーザーのアカウントを特定の外部プロバイダー (Facebook など) にリンクするように要求することです。サーバーは外部プロバイダーでログインを開始します。ブラウザーは外部プロバイダーにログインし、サーバーにリダイレクトされます。サーバーはリンクを確立し、確認でアプリケーションにリダイレクトします。

このプロトコルを開始する前に、クライアントアプリケーションが満たさなければならない前提条件があります。

  • 必要なアイデンティティープロバイダーは、管理コンソールでユーザーのレルムに対して設定して有効にする必要があります。
  • ユーザーに account.manage-account または account.manage-account-links ロールマッピングが必要です。
  • アプリケーションには、アクセストークン内で上記のロールのスコープが付与される必要があります。

このプロトコルは、アプリケーション開始アクション(AIA) によって実現されます。クライアントアプリケーションで認証されているユーザーに、アイデンティティープロバイダーにリンクするようにするには、kc_action パラメーターに idp_link:<identity-provider-alias > の値を OIDC 認証 URL に割り当て、ユーザーをこの URL にリダイレクトします。たとえば、my-oidc-provider エイリアスを使用してアイデンティティープロバイダーへのリンクを要求するには、次のようなパラメーターをアタッチします。 

kc_action=idp_link:my-oidc-provider
Copy to Clipboard Toggle word wrap

1. 外部トークンのリフレッシュ
リンクのコピー

プロバイダーにログインして生成した外部トークン(Facebook または GitHub トークンなど)を使用する場合は、アカウントリンク API を再度初期化してこのトークンを更新できます。

2. レガシークライアントが開始したアカウントリンク
リンクのコピー

警告

レガシークライアントが開始したアカウントリンクは、AIA に基づいていないカスタムプロトコルを使用しています。このプロトコルを使用する場合は、従来のクライアントが開始したアカウントリンクが将来の Red Hat build of Keycloak バージョンで削除される可能性があるため、クライアントアプリケーションを上記の AIA ベースのプロトコルに移行することを検討してください。

上記の前提条件のほかにも、レガシークライアント開始アカウントリンクには別の前提条件があります。

  • ユーザーアカウントは、OIDC プロトコルを使用して既存のユーザーとしてログインしている必要があります。
  • アプリケーションは、リダイレクト URL 生成にその情報を必要とするため、アクセストークンへのアクセスが必要です。

ログインを開始するには、アプリケーションは URL を作成し、ユーザーのブラウザーをこの URL にリダイレクトする必要があります。URL は以下のようになります。 

/{auth-server-root}/realms/{realm-name}/broker/{provider}/link?client_id={id}&redirect_uri={uri}&nonce={nonce}&hash={hash}
Copy to Clipboard Toggle word wrap

以下は、各パスおよびクエリーパラメーターの説明です。

provider
これは、管理コンソールの Identity Provider セクションで定義した外部 IDP のプロバイダーエイリアスです。
client_id
これは、アプリケーションの OIDC クライアント ID です。アプリケーションを管理コンソールでクライアントとして登録する場合は、このクライアント ID を指定する必要があります。
redirect_uri
これは、アカウントリンクの確立後にリダイレクトするアプリケーションのコールバック URL です。有効なクライアントのリダイレクト URI パターンである必要があります。つまり、管理コンソールでクライアント登録時に定義した有効な URL パターンのいずれかと一致する必要があります。
nonce
これは、アプリケーションが生成する必要のあるランダムな文字列です。
hash
これは、Base64 URL でエンコードされたハッシュです。このハッシュは、Base64 URL で nonce + token.getSessionState() + token.getIssuedFor() + provider の SHA_256 ハッシュをエンコードすることで生成されます。トークン変数は OIDC アクセストークンから取得されます。基本的に、アクセスするアイデンティティープロバイダーエイリアス、nonce、ユーザーセッション ID、クライアント ID、およびアイデンティティープロバイダーエイリアスを無作為にハッシュ化します。

以下は、アカウントリンクを確立するために URL を生成する Java Servlet コードの例になります。 

   KeycloakSecurityContext session = (KeycloakSecurityContext) httpServletRequest.getAttribute(KeycloakSecurityContext.class.getName());
   AccessToken token = session.getToken();
   String clientId = token.getIssuedFor();
   String nonce = UUID.randomUUID().toString();
   MessageDigest md = null;
   try {
      md = MessageDigest.getInstance("SHA-256");
   } catch (NoSuchAlgorithmException e) {
      throw new RuntimeException(e);
   }
   String input = nonce + token.getSessionState() + clientId + provider;
   byte[] check = md.digest(input.getBytes(StandardCharsets.UTF_8));
   String hash = Base64Url.encode(check);
   request.getSession().setAttribute("hash", hash);
   String redirectUri = ...;
   String accountLinkUrl = KeycloakUriBuilder.fromUri(authServerRootUrl)
                    .path("/realms/{realm-name}/broker/{provider}/link")
                    .queryParam("nonce", nonce)
                    .queryParam("hash", hash)
                    .queryParam("client_id", clientId)
                    .queryParam("redirect_uri", redirectUri).build(realm, provider).toString();
Copy to Clipboard Toggle word wrap

このハッシュを含める理由認証サーバーで、クライアントアプリケーションが要求を開始したことを認識し、その他の不正なアプリが、特定のプロバイダーにリンクされるユーザーアカウントを無作為に要求しないように、ハッシュを含めます。認証サーバーは、最初にログイン時に設定された SSO クッキーをチェックしてユーザーがログインしているかどうかを確認します。その後、現在のログインに基づいてハッシュを再生成し、アプリケーションによって送信されるハッシュにマッチします。

アカウントのリンク後、認証サーバーは redirect_uri にリダイレクトします。リンク要求の処理に問題がある場合は、認証サーバーが redirect_uri にリダイレクトされない場合があります。ブラウザーは、アプリケーションにリダイレクトされるのではなく、エラーページで終了できます。エラー条件があり、認証サーバーがクライアントアプリケーションにリダイレクトするのに十分な安全でない場合には、追加の error クエリーパラメーターが redirect_uri に追加されます。

警告

この API は、アプリケーションで確実に要求を開始されるようにしますが、この操作に対する CSRF 攻撃を完全に防ぐことはできません。このアプリケーションは、CSRF 攻撃ターゲットに対して自己防衛します。

</_client-initiated-account-linking>
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat