Keycloak シングルサインオンの例¶

Keycloak は、モダンなアプリケーションおよび分散型サービス向けのオープンソースの ID 認証およびアクセス制御ソリューションです。

本記事では、構築した Keycloak サーバーを使用して、SAML 2.0 プロトコルを用いて Keycloak ユーザーが Guance 管理コンソールに SSO ログインする方法を説明します。

OpenID Connect プロトコルを使用して Keycloak ユーザーが Guance 管理コンソールに SSO ログインする方法については、Keycloak シングルサインオン（デプロイメントプラン）を参照してください。

前提条件¶

Keycloak サーバーが構築されており、ログインして設定を行えること。

Keycloak 環境がない場合は、以下の手順で構築してください。

sudo yum update         # 更新

sudo yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel      # JDK をインストール

wget https://downloads.jboss.org/keycloak/11.0.2/keycloak-11.0.2.zip   # Keycloak をダウンロード

yum install unzip       # 解凍パッケージをインストール

unzip keycloak-11.0.2.zip       # ダウンロードした Keycloak を解凍

cd keycloak-11.0.2/bin         # bin ディレクトリに移動

./add-user-keycloak.sh -r master -u admin -p admin     # サーバー管理者のログインアカウントとパスワードを作成

nohup bin/standalone.sh -b 0.0.0.0 &     # bin ディレクトリに戻り、バックグラウンドで Keycloak 起動サービスを実行

Keycloak 環境の構築が完了したら、ブラウザで https://IPアドレス:8443/auth にアクセスし、「Administration Console」をクリックして Keycloak 管理コンソールを開きます。

概念¶

以下は、Keycloak 設定プロセスにおける基本概念の説明です。

フィールド	説明
Realm	レルム。ワークスペースのようなもので、ユーザー、認証情報、ロール、ユーザーグループを管理します。レルム間は互いに分離されています。
Clients	クライアント。Keycloak にユーザー認証を要求できるアプリケーションまたはサービスです。
Users	システムにログインできるユーザーアカウントです。ログイン用のメールアドレスと認証情報（Credentials）の設定が必要です。
Credentials	ユーザー ID を検証するための認証情報です。ユーザーアカウントのログインパスワードの設定に使用できます。
Authentication	ユーザーを識別および検証するプロセスです。
Authorization	ユーザーにアクセス権限を付与するプロセスです。
Roles	管理者や一般ユーザーなど、ユーザーの ID タイプを識別するために使用されます。
User role mapping	ユーザーとロールのマッピング関係です。1 人のユーザーに複数のロールを関連付けることができます。
Groups	ユーザーグループを管理します。ロールをグループにマッピングすることをサポートします。

操作手順¶

1. Keycloak レルムを作成する¶

注意: Keycloak にはデフォルトでマスターレルム（Master）があります。新しいレルム（ワークスペースに類似）を作成する必要があります。

1）Keycloak 管理コンソールで、Master > Add realm をクリックします。

2）Add realm ページで、Name にレルム名（例：gcy）を入力し、Create をクリックすると、新しいレルムが作成されます。

2. クライアントを作成し SAML を設定する¶

注意: この手順では、Keycloak クライアントを作成し SAML を設定して、Keycloak と Guance の間の信頼関係を構築します。

1）新しく作成した「gcy」レルムで、Client をクリックし、右側の Create をクリックします。

2）Add Client で以下の内容を入力し、Save をクリックします。

Client ID（エンティティ ID）: https://auth.guance.com/saml/metadata.xml
Client Protocol: SAML を選択
Client SAML Endpoint（アサーション URL）: 一時的に以下を使用: https://auth.guance.com/saml/assertion

注意: この設定は次の手順でメタデータドキュメントを取得するための一時的なものです。Guance で SSO シングルサインオンを有効にした後、正しい エンティティ ID と アサーション URL を取得してから置き換えてください。

クライアント作成後、Settings で先ほど入力したエンティティ ID、プロトコル、アサーション URL が確認できます。以下のパラメータを設定して保存します。

Sign Assertions: ON（IdP から転送されるデータの改ざんを防止し、IdP から SP へのデータの安全性を確保するため）

IDP Initiated SSO URL Name: 任意の値（例：gcy）を入力します。入力後、SSO シングルサインオン URL が生成されます（下図参照）。
Base URL: 上記で生成された SSO シングルサインオン URL を入力します（例：/auth/realms/gcy/protocol/saml/clients/gcy）。これは主に Keycloak Clients でアクセスリンクを生成し、Guance に直接シングルサインオンするために使用されます。

3）Clients の Mappers で、Create をクリックし、メールマッピングを作成します。この部分は必須項目です。設定しない場合、SSO シングルサインオンは機能しません。

Create Protocol Mapper ページで、以下の内容を入力して保存します。

Name: 任意の値（例：mail mapper）
Mapper Type: 「User Property」を選択
Property: アイデンティティプロバイダーのサポートするルールに従い、Email を入力
SAML Attribute Name: 必須項目として Email を入力

注意: Guance ではマッピングフィールドが定義されており、アイデンティティプロバイダーのユーザーメールアドレスを関連付けるために Email を入力する必要があります（つまり、アイデンティティプロバイダーはログインユーザーのメールアドレスを Email にマッピングします）。

3. Keycloak メタデータドキュメントを取得する¶

注意: この手順では、Guance でアイデンティティプロバイダーを作成するためのメタデータドキュメントを取得します。

1）Clients の Installation で、Mod Auth Mellon files を選択し、Download をクリックしてメタデータドキュメントをダウンロードします。

2）ダウンロードしたフォルダから、idp-metadata.xml を選択します。

3）Keycloak のメタデータドキュメントは レルム レベルであるため、メタデータドキュメント idp-metadata.xml 内のアクセス URL に、クライアントのパラメータ /clients/<IDP Initiated SSO URL Name> を追加する必要があります。このドキュメントでは IDP Initiated SSO URL Name: gcy と設定したため、xml ファイルに /clients/gcy を追加します（下図参照）。追加後、xml ファイルを保存します。

4. Guance で SSO シングルサインオンを有効にする¶

1）SSO シングルサインオンを有効にするには、Guance ワークスペースの 管理 > メンバー管理 > SSO 管理 で、有効にする をクリックします。

詳細はドキュメント SSO を作成を参照してください。

注意: アカウントのセキュリティを考慮し、Guance ではワークスペースごとに 1 つの SSO のみ設定できます。以前に SAML 2.0 を設定した場合、最後に更新した SAML 2.0 設定が最終的なシングルサインオン検証エントリとして扱われます。

2）手順 3 でダウンロードした メタデータドキュメント をアップロードし、ドメイン名（メールアドレスのドメイン部分） を設定し、ロール を選択すると、アイデンティティプロバイダーの エンティティ ID と アサーション URL を取得できます。ログイン URL を直接コピーしてログインすることもできます。

注意: ドメイン名は、Guance とアイデンティティプロバイダー間でメールドメインのマッピングを行い、シングルサインオンを実現するために使用されます。つまり、ユーザーのメールアドレスのドメイン部分は、Guance に追加されたドメイン名と一致している必要があります。

5. Keycloak で SAML アサーション URL を置き換える¶

1）Keycloak に戻り、手順 2 の エンティティ ID と アサーション URL を更新します。

注意: Guance でシングルサインオンを設定する際、アイデンティティプロバイダーの SAML で設定するアサーション URL は、Guance のものと一致している必要があります。これにより、シングルサインオンが実現します。

6. Keycloak ユーザーを設定する¶

注意: この手順では、Guance でアイデンティティプロバイダーを作成するための承認済みユーザーメールアカウントを設定します。設定した Keycloak ユーザーのメールアカウントを使用して、Guance プラットフォームにシングルサインオンできます。

1）作成した gcy レルムで、User をクリックし、Add user をクリックします。

2）ユーザー名 と メールアドレス を入力します。メールアドレスは必須項目であり、Guance のアイデンティティプロバイダーで設定されたユーザーホワイトリストのメールアドレスと一致している必要があります。これにより、メールマッピングによる Guance へのログインが可能になります。