ADFS 連携
SAML 2.0 プロトコルを通じて企業内の ADFS（Active Directory Federation Services）と統合します
ADFS（Active Directory Federation Services）は、Microsoft が提供する企業向け ID フェデレーションサービスです。Windows Active Directory と ADFS をすでに構築している企業では、従業員が AD アカウントのパスワードで直接 MaiAgent にログインでき、別途アカウントを作成する必要がありません。
対象ユーザー：ADFS（Windows Server 2016 / 2019 / 2022）を構築済みの企業
事前にご準備ください：
MaiAgent 組織管理者権限（認証ソースの設定に使用）
ADFS サーバーの管理者権限（証明書利用者信頼とクレーム規則の作成に使用）
テスト用の AD アカウント（そのアカウントの
mail属性に値が設定されている必要があります）
一、MaiAgent 管理画面で認証ソースを作成する
組織管理 > 認証ソース に進み、SAML 認証タイプを選択します：
認証ソース名
例：my-company（小文字英数字とハイフン、SP エンドポイント URL の生成に使用されます）
IdP Metadata URL
https://{ADFS ドメイン}/FederationMetadata/2007-06/FederationMetadata.xml
Email Domain
（任意）企業の Email ドメイン、例：company.com
ADFS の Federation Metadata URL は固定パスです。{ADFS ドメイン} を企業の ADFS サーバーのドメインに置き換えるだけで使用できます。保存時に MaiAgent がこのメタデータをリアルタイムで取得・解析し、Entity ID、SSO URL、署名証明書を自動的に入力します。
保存時に MaiAgent サーバーがこの Metadata URL に接続できる必要があります。ADFS が内部ネットワークのみで公開されており MaiAgent が接続できない場合は、手動モードを使用してください。IdP Entity ID（通常は http://{ADFS ドメイン}/adfs/services/trust）、IdP SSO URL（通常は https://{ADFS ドメイン}/adfs/ls/）、および ADFS 管理コンソールからエクスポートした Token-Signing 証明書（Base64 形式）をそれぞれ入力します。
二、MaiAgent の SP 情報を取得する
保存後、設定ページに SP（Service Provider、すなわち MaiAgent 側）の情報が表示されます：
Entity ID / SP Metadata URL
https://{プラットフォームドメイン}/accounts/saml/{名前}/metadata/
ACS URL
https://{プラットフォームドメイン}/accounts/saml/{名前}/acs/
ブラウザで SP Metadata URL を開き、XML ドキュメント（<EntityDescriptor> で始まるもの）が表示されることを確認してください。表示されれば、認証ソースが有効であることを意味します。この URL が次のステップで ADFS 管理者に渡す情報です。
プライベートデプロイで非標準ポートを使用している場合（例：https://プラットフォームドメイン:8000）、XML 内の AssertionConsumerService の Location にポートが含まれているか確認してください。entityID にはポートがあるのに ACS URL にはない場合、リバースプロキシ（Nginx）が Host ヘッダーからポートを除去しています。Nginx 設定の proxy_set_header Host $host; を proxy_set_header Host $http_host; に変更し、Nginx をリロードしてください（すべての location ブロックで変更が必要です）。その後、リロードして確認してください。
三、ADFS で証明書利用者信頼を作成する
以下は ADFS 管理者が ADFS サーバー上で行う操作です：
Server Manager > Tools > AD FS Management を開きます
左側で Relying Party Trusts を選択し、右側の Add Relying Party Trust... をクリックします
Claims aware > Start を選択します
Select Data Source ページでインポート方法を選択します（以下を参照）
Display name に
MaiAgentと入力しますAccess Control Policy はまず Permit everyone を選択します（テスト完了後に指定の AD グループに変更してください）
Next をクリックしてウィザードを完了します
Select Data Source の 2 つのインポート方法：
Import data about the relying party published online
ADFS サーバーが MaiAgent の TLS 証明書を信頼している
SP Metadata URL を貼り付けます
Import data from a file
MaiAgent が自己署名証明書または内部証明書を使用している（プライベートデプロイでよくあります）
まずブラウザで SP Metadata URL を開き、XML をファイルとして保存してから、そのファイルを選択してインポートします
インポートが成功すると、ウィザードが Identifier（SP Metadata URL）と ACS Endpoint を自動的に入力します。手動で入力する必要はありません。
四、クレーム規則（Claim Rules）を設定する
これは統合において最も見落とされやすいステップです。ウィザード完了後、クレーム規則は空の状態です。設定しないと、ADFS が返す SAML レスポンスにはユーザー属性が含まれず、ログインが直接失敗します。
先ほど作成した Relying Party を右クリック > Edit Claim Issuance Policy...（Edit Access Control Policy ではありません）> Add Rule を選択し、テンプレートとして Send Claims Using a Custom Rule を選択して、以下の 2 つの規則を順番に作成します。
規則一：ユーザー属性の送信（名前：MaiAgent attributes）
この規則は AD からユーザーの mail および displayName 属性を読み取ります。特に注意が必要なのは、MaiAgent は電子メールの読み取りに Name クレーム（.../claims/name）を使用しており、一般的に使用される emailaddress クレームではないという点です。そのため、この規則では Email を両方のクレームに同時に送信しています（属性マッピングの詳細は SAML 連携の属性マッピング説明 を参照してください）。
規則二：Email を NameID に変換（名前：Email to NameID）
この規則は Email を Email 形式の NameID に変換し、ログイン識別およびシングルログアウトに使用します。
設定時の 3 つの注意事項：
規則の順序：規則一が上、規則二が下になるようにしてください（規則二は規則一が発行する emailaddress クレームに依存しています）
規則テキストは全文をコピー＆ペーストしてください。手動入力はしないでください。クレーム URI が 1 文字でも異なると規則全体が無効になります
保存後にサービスの再起動は不要です。すぐにログインをテストできます
五、証明書利用者のプロパティを確認する
Relying Party を右クリック > Properties：
Advanced
Secure hash algorithm で SHA-256 を選択します
Encryption
暗号化証明書を設定しないでください。MaiAgent は暗号化された SAML アサーションに対応していません。証明書を設定すると ADFS がレスポンスを暗号化し、ログインが失敗します
Signature
空白のままにします
六、ログインをテストする
AD の
mail属性に値が設定されているテストアカウントを使用しますMaiAgent のログインページで SSO ログインをクリックすると、ブラウザが
https://{ADFS ドメイン}/adfs/ls/にリダイレクトされますAD のアカウントとパスワードを入力し、認証に成功すると自動的に MaiAgent にリダイレクトされます
トラブルシューティング
ADFS でメタデータのインポート時に「Could not create SSL/TLS secure channel」と表示される
ADFS サーバーが MaiAgent の TLS 証明書を信頼していない（自己署名証明書または内部証明書）
「Import data from a file」でファイルインポートを使用してください
ログイン後「Third-Party Login Failure」で停止する
最も一般的な原因はクレーム規則の問題です。サーバーログを確認してください
プライベートデプロイでは docker logs maiagent-django --since 5m 2>&1 | grep -i saml を実行してエラーメッセージを確認できます
ログに There is no AttributeStatement on the Response と表示される
クレーム規則が未設定、またはテストアカウントの AD mail 属性が空
第四節に従って 2 つの規則を追加してください。Get-ADUser <アカウント> -Properties mail で mail に値があることを確認してください
ログに User email not found と表示される
クレームは発行されているが、Email が Name クレームに含まれていない
規則一のクレーム URI がドキュメントと完全に一致しているか確認してください
ログにアサーションの期限切れまたは未到来（NotBefore / NotOnOrAfter）と表示される
MaiAgent サーバーと ADFS サーバーの時刻がずれている
両方のサーバーで NTP を設定してください
ログイン成功後「No Access Permission」と表示される
新しいメンバーにまだ権限が割り当てられていない（正常な動作）
管理者がメンバー管理でロール権限を割り当ててください
ADFS 認証成功後のリダイレクト URL にポートが含まれておらず、ページが開けない
SP メタデータの ACS URL にポートが含まれていない（リバースプロキシの設定問題）
第二節の説明に従い Nginx の proxy_set_header Host 設定を修正し、メタデータを再生成して ADFS に再インポートしてください
SAML-tracer を使用してデバッグ：ブラウザに SAML-tracer 拡張機能をインストールしてから再度ログインすると、ADFS が返す SAML レスポンスの内容を直接確認できます。AttributeStatement が空であるか、Email が誤ったクレームに含まれている場合、ADFS 側のクレーム規則の問題であることがすぐに確認できます。
運用上の注意事項
Token-Signing 証明書のローテーション：ADFS はデフォルトで毎年 Token-Signing 証明書を自動的にローテーションします（AutoCertificateRollover）。MaiAgent 側で IdP Metadata URL モードを使用している場合は、証明書の更新後に認証ソースを再保存するだけで更新されます。手動証明書モードを使用している場合は、ローテーション前に新しい証明書を取得して設定を更新する必要があります。更新しないと、すべてのユーザーがログインできなくなります
ログイン対象の制限：テスト完了後、ADFS の Access Control Policy を Permit everyone から指定の AD グループに変更することで、どの従業員が MaiAgent にログインできるかを制御できます。MaiAgent 側の設定変更は不要です
SSO の一時停止：MaiAgent 管理画面で該当の認証ソースのログインスイッチをオフにするだけで済みます。ADFS 側の変更は不要です
最終更新
役に立ちましたか？