> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/ja/org/sso/sso-saml/sso-saml-adfs.md).

# 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` 属性に値が設定されている必要があります**）

{% hint style="info" %}
統合の基本的な考え方は「双方向の情報交換」です。ADFS の情報（Metadata URL）を MaiAgent に入力し、MaiAgent の情報（SP Metadata URL）を ADFS にインポートします。SAML の一般的な設定手順については、先に [SAML 連携](/maiagent-user-guide/ja/org/sso/sso-saml.md) を参照してください。
{% endhint %}

## 一、MaiAgent 管理画面で認証ソースを作成する <a href="#create-auth-source" id="create-auth-source"></a>

<mark style="color:blue;">組織管理</mark> > <mark style="color:blue;">認証ソース</mark> に進み、<mark style="color:blue;">SAML</mark> 認証タイプを選択します：

| 項目               | 入力値                                                                     |
| ---------------- | ----------------------------------------------------------------------- |
| 認証ソース名           | 例：`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、署名証明書を自動的に入力します。

{% hint style="warning" %}
保存時に MaiAgent サーバーがこの Metadata URL に接続できる必要があります。ADFS が内部ネットワークのみで公開されており MaiAgent が接続できない場合は、手動モードを使用してください。IdP Entity ID（通常は `http://{ADFS ドメイン}/adfs/services/trust`）、IdP SSO URL（通常は `https://{ADFS ドメイン}/adfs/ls/`）、および ADFS 管理コンソールからエクスポートした **Token-Signing 証明書**（Base64 形式）をそれぞれ入力します。
{% endhint %}

## 二、MaiAgent の SP 情報を取得する <a href="#get-sp-info" id="get-sp-info"></a>

保存後、設定ページに SP（Service Provider、すなわち MaiAgent 側）の情報が表示されます：

| SP 項目                       | フォーマット                                                |
| --------------------------- | ----------------------------------------------------- |
| Entity ID / SP Metadata URL | `https://{プラットフォームドメイン}/accounts/saml/{名前}/metadata/` |
| ACS URL                     | `https://{プラットフォームドメイン}/accounts/saml/{名前}/acs/`      |

ブラウザで SP Metadata URL を開き、XML ドキュメント（`<EntityDescriptor>` で始まるもの）が表示されることを確認してください。表示されれば、認証ソースが有効であることを意味します。この URL が次のステップで ADFS 管理者に渡す情報です。

{% hint style="warning" %}
プライベートデプロイで非標準ポートを使用している場合（例：`https://プラットフォームドメイン:8000`）、XML 内の `AssertionConsumerService` の `Location` に**ポートが含まれているか**確認してください。entityID にはポートがあるのに ACS URL にはない場合、リバースプロキシ（Nginx）が Host ヘッダーからポートを除去しています。Nginx 設定の `proxy_set_header Host $host;` を `proxy_set_header Host $http_host;` に変更し、Nginx をリロードしてください（すべての location ブロックで変更が必要です）。その後、リロードして確認してください。
{% endhint %}

## 三、ADFS で証明書利用者信頼を作成する <a href="#create-relying-party-trust" id="create-relying-party-trust"></a>

以下は ADFS 管理者が ADFS サーバー上で行う操作です：

1. <mark style="color:blue;">Server Manager</mark> > <mark style="color:blue;">Tools</mark> > <mark style="color:blue;">AD FS Management</mark> を開きます
2. 左側で <mark style="color:blue;">Relying Party Trusts</mark> を選択し、右側の <mark style="color:blue;">Add Relying Party Trust...</mark> をクリックします
3. <mark style="color:blue;">Claims aware</mark> > Start を選択します
4. **Select Data Source** ページでインポート方法を選択します（以下を参照）
5. **Display name** に `MaiAgent` と入力します
6. **Access Control Policy** はまず <mark style="color:blue;">Permit everyone</mark> を選択します（テスト完了後に指定の AD グループに変更してください）
7. 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 をファイルとして保存してから、そのファイルを選択してインポートします |

{% hint style="info" %}
オンラインインポートで「Could not create SSL/TLS secure channel」エラーが表示された場合は、ADFS サーバーが MaiAgent の証明書を信頼していないことを意味します。ファイルインポートを使用してください。メタデータのインポートは 1 回限りの操作です。実際のログインフローでは ADFS は MaiAgent に接続する必要がありません（すべてのリダイレクトはユーザーのブラウザが処理します）。そのため、ファイルインポートによる副作用はありません。
{% endhint %}

インポートが成功すると、ウィザードが Identifier（SP Metadata URL）と ACS Endpoint を自動的に入力します。手動で入力する必要はありません。

## 四、クレーム規則（Claim Rules）を設定する <a href="#configure-claim-rules" id="configure-claim-rules"></a>

{% hint style="danger" %}
これは統合において**最も見落とされやすいステップ**です。ウィザード完了後、クレーム規則は空の状態です。設定しないと、ADFS が返す SAML レスポンスにはユーザー属性が含まれず、ログインが直接失敗します。
{% endhint %}

先ほど作成した Relying Party を右クリック > <mark style="color:blue;">Edit Claim Issuance Policy...</mark>（Edit Access Control Policy ではありません）> <mark style="color:blue;">Add Rule</mark> を選択し、テンプレートとして <mark style="color:blue;">Send Claims Using a Custom Rule</mark> を選択して、以下の 2 つの規則を順番に作成します。

**規則一：ユーザー属性の送信**（名前：`MaiAgent attributes`）

```
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.microsoft.com/identity/claims/displayname"), query = ";mail,mail,displayName;{0}", param = c.Value);
```

この規則は AD からユーザーの `mail` および `displayName` 属性を読み取ります。特に注意が必要なのは、MaiAgent は電子メールの読み取りに **Name クレーム**（`.../claims/name`）を使用しており、一般的に使用される emailaddress クレームではないという点です。そのため、この規則では Email を両方のクレームに同時に送信しています（属性マッピングの詳細は [SAML 連携の属性マッピング説明](/maiagent-user-guide/ja/org/sso/sso-saml.md#saml-attribute-mapping) を参照してください）。

**規則二：Email を NameID に変換**（名前：`Email to NameID`）

```
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
```

この規則は Email を Email 形式の NameID に変換し、ログイン識別およびシングルログアウトに使用します。

設定時の 3 つの注意事項：

* 規則の順序：規則一が上、規則二が下になるようにしてください（規則二は規則一が発行する emailaddress クレームに依存しています）
* 規則テキストは全文をコピー＆ペーストしてください。手動入力はしないでください。クレーム URI が 1 文字でも異なると規則全体が無効になります
* 保存後にサービスの再起動は不要です。すぐにログインをテストできます

## 五、証明書利用者のプロパティを確認する <a href="#check-relying-party-properties" id="check-relying-party-properties"></a>

Relying Party を右クリック > <mark style="color:blue;">Properties</mark>：

| タブ         | 確認項目                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------- |
| Advanced   | Secure hash algorithm で **SHA-256** を選択します                                                        |
| Encryption | 暗号化証明書を**設定しないでください**。MaiAgent は暗号化された SAML アサーションに対応していません。証明書を設定すると ADFS がレスポンスを暗号化し、ログインが失敗します |
| Signature  | 空白のままにします                                                                                         |

## 六、ログインをテストする <a href="#test-login" id="test-login"></a>

1. AD の `mail` 属性に値が設定されているテストアカウントを使用します
2. MaiAgent のログインページで SSO ログインをクリックすると、ブラウザが `https://{ADFS ドメイン}/adfs/ls/` にリダイレクトされます
3. AD のアカウントとパスワードを入力し、認証に成功すると自動的に MaiAgent にリダイレクトされます

{% hint style="info" %}
SSO で初めてログインしたユーザーは自動的にアカウントが作成され、組織に追加されますが、**デフォルトでは権限がない**ため、「No Access Permission」ページが表示されます。これは正常なセキュリティ設計です。組織管理者が <mark style="color:blue;">組織管理</mark> > <mark style="color:blue;">メンバー</mark> で該当メンバーを見つけてロール権限を割り当ててください。ユーザーが <mark style="color:blue;">Check Permission</mark> をクリックするか、再度ログインすると利用できるようになります。
{% endhint %}

## トラブルシューティング <a href="#troubleshooting" id="troubleshooting"></a>

| 症状                                                                 | 原因                                                     | 解決策                                                                                             |
| ------------------------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| 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 側のクレーム規則の問題であることがすぐに確認できます。

## 運用上の注意事項 <a href="#maintenance-notes" id="maintenance-notes"></a>

* **Token-Signing 証明書のローテーション**：ADFS はデフォルトで毎年 Token-Signing 証明書を自動的にローテーションします（AutoCertificateRollover）。MaiAgent 側で IdP Metadata URL モードを使用している場合は、証明書の更新後に認証ソースを再保存するだけで更新されます。手動証明書モードを使用している場合は、ローテーション前に新しい証明書を取得して設定を更新する必要があります。更新しないと、すべてのユーザーがログインできなくなります
* **ログイン対象の制限**：テスト完了後、ADFS の Access Control Policy を Permit everyone から指定の AD グループに変更することで、どの従業員が MaiAgent にログインできるかを制御できます。MaiAgent 側の設定変更は不要です
* **SSO の一時停止**：MaiAgent 管理画面で該当の認証ソースのログインスイッチをオフにするだけで済みます。ADFS 側の変更は不要です


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/org/sso/sso-saml/sso-saml-adfs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.