Keycloak での仲介アイデンティティプロバイダーとしての MS AD FS 3.0 の設定方法
2017年3月23日 Hynek Mlnařík 著
このドキュメントでは、Microsoft Active Directory Federation Services 3.0 を Keycloak の仲介アイデンティティプロバイダーとして初期設定を行う方法をご案内します。
前提条件
- 2 台のサーバーホスト
- Active Directory Federation Services (AD FS) がインストールされた Microsoft Windows Server 2012。この記事では、AD ドメインは DOMAIN.NAME という名前になります。
- Keycloak サーバー。これは一般的にどこにでも配置できますが、ここでは別のホストで実行されていることを想定しています。
- DNS 設定
- この記事では、Windows ホスト名は fs.domain.name となります。
- この記事では、Keycloak ホスト名は kc.domain.name となります。
Keycloak サーバーの設定
Keycloak サーバーは SSL/TLS トランスポート用に設定されています。これは AD FS が通信するために必須です。これには 2 つのステップがあります。
- HTTPS での Keycloak への受信接続の設定 - 手順はサーバーインストールガイドに記載されています。
- AD FS 証明書を Java トラストストアにエクスポートして、HTTPS 送信接続を有効にします。
- AD FS 管理コンソールで、ツリーのサービス → 証明書ノードに移動し、サービス通信証明書をエクスポートします。
- Java keytool ユーティリティを使用して、証明書を Java トラストストア (JKS 形式) にインポートします。
- サーバーインストールガイドの説明に従って、Keycloak でトラストストアを設定します。
Keycloak でのアイデンティティプロバイダーの設定
仲介アイデンティティプロバイダーの基本プロパティの設定
アイデンティティプロバイダーで、新しい SAML v2.0 アイデンティティプロバイダーを作成します。この記事では、アイデンティティプロバイダーはエイリアス adfs-idp-alias で知られるようになります。
次に、一番下までスクロールし、「URL からインポート」フィールドに AD FS 記述子 URL を入力します。AD FS 3.0 の場合、この URL は https://fs.domain.name/FederationMetadata/2007-06/FederationMetadata.xml です。「インポート」をクリックしたら、設定を確認してください。通常は、少なくとも 署名の検証 オプションを有効にすることをお勧めします。
AD FS インスタンスに送信される認証リクエストが署名されることが想定される場合 (通常もそうですが)、AuthnRequests の署名を要求 オプションを有効にする必要があります。重要なことは、AuthnRequests の署名を要求 オプションを有効にした後に表示される SAML 署名キー名 フィールドを CERT_SUBJECT に設定する必要があることです。AD FS は署名キー名ヒントが署名証明書のサブジェクトであることを想定しているためです。
AD FS は次のステップで Windows ドメイン修飾名形式で名前 ID を応答するように設定されるため、それに応じて NameID ポリシー形式 フィールドを設定します。
マッパーの設定
以下の AD FS の設定ステップでは、AD FS は SAML アサーションでメールとグループ情報を送信するように設定されます。AD FS によって発行された SAML ドキュメントからこれらの詳細を Keycloak ユーザー ストアに変換するには、アイデンティティプロバイダーの [マッパー] タブで対応する 2 つのマッパーを設定する必要があります。
- グループ: managers という名前のマッパーは、タイプが SAML 属性からロールへ であり、http://schemas.xmlsoap.org/claims/Group という名前の属性を、属性値が managers の場合、ロール manager にマッピングします。
- 属性: email という名前のマッパーは、タイプが 属性インポーター であり、http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress という名前の属性を、email という名前のユーザー属性にマッピングします。
AD FS 設定に必要な情報の取得
次に、アイデンティティプロバイダーの詳細の リダイレクト URI フィールドから AD FS 設定で使用される SAML サービスプロバイダー記述子 URI を決定します。このフィールドの URI に「/descriptor」を追加します。URI は https://kc.domain.name:8443/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor のようになります。URI をブラウザーに入力して、URI が正しいかどうかを確認できます。SAML サービスプロバイダー XML 記述子が表示されるはずです。
AD FS での証明書利用者信頼の設定
証明書利用者の設定
AD FS 管理コンソールで、[信頼関係] を右クリックし、証明書利用者信頼 → メニューから 証明書利用者信頼の追加 を選択します。
ウィザードの開始時に、前のステップで取得した SAML 記述子 URL を フェデレーションメタデータアドレス フィールドに入力し、AD FS に設定をインポートさせます。ウィザードを続行し、必要に応じて設定を調整します。ここでは、デフォルト設定のみを使用します。ウィザードの最後のページで要求されたら、チェックボックスをオンのままにして、クレームルールを編集する必要があることに注意してください。
クレームマッピングの設定
SAML プロトコルは正しく続行され、AD FS は Keycloak からのリクエストに従ってユーザーを正しく認証できますが、リクエストされた名前 ID 形式はまだ認識されておらず、SAML レスポンスにはメールなどの追加情報は含まれません。したがって、AD ユーザーの詳細から SAML ドキュメントにクレームをマッピングする必要があります。
3 つのルールを設定します。1 つはユーザー ID のマッピング、2 つ目は標準ユーザー属性のマッピング、3 つ目はユーザーグループのマッピングです。すべて、[kc.domain.name のクレームルールの編集] ウィンドウの [ルールの追加] ボタンをクリックして開始します。
最初のルールは、Windows 修飾ドメイン名のユーザー ID を SAML レスポンスにマッピングします。[変換要求規則の追加] ウィンドウで、受信クレームの変換規則タイプを選択します。
上記の例は、Windows アカウント名 ID 形式を対象としています。他の名前 ID 形式もサポートされていますが、この記事の範囲外です。永続形式および一時形式の名前 ID の設定方法については、たとえばこのブログを参照してください。
2 番目のルールは、ユーザーのメールを SAML レスポンスにマッピングします。[変換要求規則の追加] ウィンドウで、LDAP 属性をクレームとして送信規則タイプを選択します。必要に応じて他の属性を追加できます。
3 番目のルールは、ユーザーが名前付きグループのメンバーである場合にグループ名を送信します。[変換要求規則の追加] ウィンドウで再度開始し、グループメンバーシップをクレームとして送信規則タイプを選択します。次に、フィールドにリクエストされた値を入力します。
この設定では、認証されたユーザーが DOMAIN\Managers グループのメンバーである場合、値が managers の Group という名前の属性を SAML アサーションで送信します。
トラブルシューティング
最初の手法として、ブラウザーで Keycloak と AD FS 間で送受信される SAML メッセージを確認する必要があります。SAML デコーダーは、ブラウザー拡張機能として利用できます (例: Firefox 用 SAML Tracer、Chrome 用 SAML Chrome Panel)。キャプチャされた通信から、エラー ステータス コードと、マッパーの設定に必要な SAML アサーションの実際の属性名と値を確認できます。たとえば、名前 ID 形式が認識されない場合、AD FS は urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy ステータス コードを含む SAML レスポンスを返します。
2 番目の手段として、ログを確認します。AD FS の場合、ログは イベントビューアー の アプリケーションとサービス ログ → AD FS → 管理 にあります。Keycloak では、jboss-cli.sh 経由で実行中の Keycloak インスタンスに接続し、次のコマンドを入力することで、SAML 処理のトレースを有効にできます。
これにより、Keycloak サーバーログで SAML メッセージとブローカー関連の SAML 処理メッセージを見つけることができるようになります。
一般的な問題
Q: Windows 2016 で AD FS を使用しているときに、URL から記述子をインポートした後、Keycloak ログに次のエラーが表示されました: RESTEASY002010: Failed to execute: javax.ws.rs.NotFoundException: RESTEASY003210: Could not find resource for full path: https://kc.domain.name/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor/FederationMetadata/2007-06/FederationMetadata.xml。これは害を及ぼしますか?
A: 害はありません。Windows 2016 バージョンでは、最初に入力された URL に FederationMetadata/2007-06/FederationMetadata.xml を追加して、AD FS のような記述子 URL をチェックしているようです。このようなリソースは Keycloak に存在しないため、エラーが報告されます。ただし、AD FS は、これが発生した場合に入力された URL を使用してインポートしているようです。この問題に関する元のメールディスカッションも参照してください。
結論
行き詰まった場合は、遠慮なくKeycloak ユーザーフォーラムメーリングリストに質問を書き込んでください。
常に改善の余地があるため、このテキストに関する問題や提案があれば、自由にコメントを残してください。