> 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/maiagent-user-guide-ja/org/sso/sso-saml.md).

# SAML 連携

SAML（Security Assertion Markup Language）は、企業向けアプリケーションで広く採用されている標準認証プロトコルです。

**対象ユーザー**：SAML ID プロバイダーをすでに構築している企業（Microsoft Entra ID / Azure AD、Okta、Google Workspace など）

**主なメリット**：

* 業界標準プロトコルで、互換性が高い
* 完全なユーザー属性の受け渡しに対応
* 多要素認証（MFA）と統合可能
* シングルログアウト（Single Logout, SLO）に対応

## 設定手順 <a href="#setup-steps" id="setup-steps"></a>

### 1. MaiAgent 管理画面で IdP 情報を入力する <a href="#step-1-fill-idp-info" id="step-1-fill-idp-info"></a>

<figure><img src="/files/oJZGi1EXZE0ZGNVVmtbv" alt="SAML 設定"><figcaption><p>SAML 認証設定：IdP 情報を入力すると、システムが自動的に SP 情報を生成します</p></figcaption></figure>

<mark style="color:blue;">SAML</mark> 認証タイプを選択した後、以下の項目を入力する必要があります：

| 項目               | 必須  | 説明                                       |
| ---------------- | --- | ---------------------------------------- |
| 認証ソース名           | はい  | SP エンドポイント URL の生成に使用されます。例：`my-company` |
| IdP Metadata URL | はい  | ID プロバイダーのメタデータ URL                      |
| IdP Entity ID    | はい  | ID プロバイダーのエンティティ識別子                      |
| IdP SSO URL      | はい  | ID プロバイダーのシングルサインオン用エンドポイント URL          |
| Email Domain     | いいえ | 企業の Email ドメインを任意で入力できます                 |

### 2. SP（MaiAgent 側）情報を取得する <a href="#step-2-get-sp-info" id="step-2-get-sp-info"></a>

認証ソース名を入力すると、システムが以下の SP 情報を自動的に生成し、設定ページに表示します：

| SP 項目                            | フォーマット                                        | 説明             |
| -------------------------------- | --------------------------------------------- | -------------- |
| Entity ID（エンティティ識別子）             | `https://{ドメイン}/accounts/saml/{名前}/metadata/` | IdP 設定用に提供されます |
| ACS URL（アサーション コンシューマー サービス URL） | `https://{ドメイン}/accounts/saml/{名前}/acs/`      | IdP 設定用に提供されます |
| Login URL（ログイン URL）              | `https://{API ドメイン}/auth/saml/{名前}/login/`    | SAML ログインの入口   |

{% hint style="info" %}
SP 情報エリアには <mark style="color:blue;">コピー</mark> ボタンが用意されており、URL を IdP の設定画面へ直接コピーするのに便利です。
{% endhint %}

### 3. ID プロバイダー（IdP）で MaiAgent アプリケーションを設定する <a href="#step-3-configure-idp" id="step-3-configure-idp"></a>

**Microsoft Entra ID（Azure AD）** を例に説明します：

1. [Azure Portal](https://portal.azure.com/) にログインし、<mark style="color:blue;">Microsoft Entra ID</mark> > <mark style="color:blue;">エンタープライズ アプリケーション</mark> を選択します
2. <mark style="color:blue;">新しいアプリケーション</mark> > <mark style="color:blue;">独自のアプリケーションの作成</mark> をクリックします
3. 「**ギャラリーに見つからないその他のアプリケーションを統合します（ギャラリー以外）**」を選択します

<figure><img src="/files/8wccm1o5BkGumSRjBfUS" alt="エンタープライズ アプリケーションの作成"><figcaption><p>Azure AD でカスタムのエンタープライズ アプリケーションを作成します</p></figcaption></figure>

4. 先ほど作成したエンタープライズ アプリケーションを選択します

<figure><img src="/files/bPcf0NsoYB0PzJik4bQk" alt="エンタープライズ アプリケーションの選択"><figcaption><p>指定したエンタープライズ アプリケーションを選択します</p></figcaption></figure>

5. エンタープライズ アプリケーションに入り、左側の <mark style="color:blue;">シングル サインオン</mark> > <mark style="color:blue;">SAML</mark> をクリックします

<figure><img src="/files/1Un6dIS3UTKT9R5oVgrP" alt="SAML の選択"><figcaption><p>シングルサインオンの方式として SAML を選択します</p></figcaption></figure>

6. <mark style="color:blue;">基本的な SAML 構成</mark> セクションに MaiAgent の SP 情報を入力します：
   * **識別子（エンティティ ID）**：MaiAgent が生成した Entity ID を入力します
   * **応答 URL（アサーション コンシューマー サービス URL）**：MaiAgent が生成した ACS URL を入力します

<figure><img src="/files/SmZW326OoUrIQjq3shmA" alt="基本的な SAML 構成"><figcaption><p>基本的な SAML 構成に MaiAgent の Entity ID と ACS URL を入力します</p></figcaption></figure>

7. 設定を保存します

### 4. IdP から設定値を取得して MaiAgent に入力し直す <a href="#step-4-fill-idp-values-back" id="step-4-fill-idp-values-back"></a>

Azure AD の <mark style="color:blue;">SAML でのシングル サインオンのセットアップ</mark> ページの下部で、以下の情報を確認します：

| Azure AD の項目           | 対応する MaiAgent の項目 |
| ---------------------- | ----------------- |
| アプリ フェデレーション メタデータ URL | IdP Metadata URL  |
| Microsoft Entra 識別子    | IdP Entity ID     |
| ログイン URL               | IdP SSO URL       |

これらの値を MaiAgent 管理画面の SAML 設定フォームに入力します。

<figure><img src="/files/V5SNf6vYYY9UicSbLfdk" alt="IdP 情報"><figcaption><p>Azure AD から Microsoft Entra 識別子、ログイン URL、メタデータ URL を取得します</p></figcaption></figure>

### 5. ユーザーとグループを割り当てる <a href="#step-5-assign-users-groups" id="step-5-assign-users-groups"></a>

Azure AD のエンタープライズ アプリケーションで <mark style="color:blue;">ユーザーとグループ</mark> > <mark style="color:blue;">ユーザーまたはグループの追加</mark> をクリックし、MaiAgent へのアクセスが必要な従業員またはグループを追加します。

<figure><img src="/files/8MenDcISCFkZplP4oBf7" alt="ユーザーとグループの追加"><figcaption><p>MaiAgent へのアクセスが必要な従業員またはグループをエンタープライズ アプリケーションに追加します</p></figcaption></figure>

### 6. 保存して確認する <a href="#step-6-save-and-confirm" id="step-6-save-and-confirm"></a>

MaiAgent 管理画面で <mark style="color:blue;">保存</mark> ボタンをクリックすると、システムが確認ウィンドウを表示し、次の点をお知らせします：

* 認証タイプを切り替えると、従業員のログイン方法が変わります
* 既存のユーザーは新しい SSO 方式でログインする必要があります
* IdP 側の設定が完了していることを必ず確認してください

確認すると設定が完了します。

## SAML 属性マッピング <a href="#saml-attribute-mapping" id="saml-attribute-mapping"></a>

MaiAgent は SAML レスポンス（SAML Response）から以下の属性を取得します：

| SAML 属性（Claim）                                               | MaiAgent の項目 | 説明                 |
| ------------------------------------------------------------ | ------------ | ------------------ |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | ユーザーの電子メール   | 必須項目。ユーザー識別に使用されます |
| `http://schemas.microsoft.com/identity/claims/displayname`   | 表示名          | 画面に表示されるユーザー名      |

{% hint style="info" %}
SAML レスポンスに displayname 属性が含まれていない場合、システムは自動的に Email の接頭辞（@ の前のテキスト）を表示名として取得します。
{% endhint %}

## その他の SAML IdP の設定 <a href="#other-saml-idp-settings" id="other-saml-idp-settings"></a>

MaiAgent の SAML 統合は Microsoft Entra ID に限定されません。ご利用の ID プロバイダーが SAML 2.0 標準プロトコルに対応していれば、いずれも統合が可能です。一般的な IdP には以下のものがあります：

* **Okta**：Applications で SAML 2.0 App を追加します
* **Google Workspace**：Admin Console > Security > SSO で設定します
* **ADFS**：Relying Party Trusts で追加します

設定のロジックは同じです。MaiAgent の SP 情報（Entity ID、ACS URL）を IdP に入力し、続いて IdP の情報（Metadata URL、Entity ID、SSO URL）を MaiAgent に入力し直します。

## SAML のセキュリティ特性 <a href="#saml-security-features" id="saml-security-features"></a>

* SAML 2.0 HTTP Redirect Binding に対応
* Session Index による追跡で、ログアウト操作の正確性を確保
* NameID フォーマットに emailAddress を使用し、ユーザー識別の一貫性を確保
* ログイン Cookie の設定：`Secure=True`、`SameSite=None`、`HttpOnly=True`、有効期間 5 分

## 設定項目早見表 <a href="#settings-quick-reference" id="settings-quick-reference"></a>

| 項目               | 必須  | フォーマット                 | 例                                                                                         |
| ---------------- | --- | ---------------------- | ----------------------------------------------------------------------------------------- |
| 認証ソース名           | はい  | 小文字英数字 + ハイフン、最大 31 文字 | `my-company`                                                                              |
| IdP Metadata URL | はい  | HTTPS URL              | `https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml` |
| IdP Entity ID    | はい  | URI                    | `https://sts.windows.net/{tenant-id}/`                                                    |
| IdP SSO URL      | はい  | HTTPS URL              | `https://login.microsoftonline.com/{tenant-id}/saml2`                                     |
| Email Domain     | いいえ | ドメイン形式                 | `company.com`                                                                             |


---

# 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/maiagent-user-guide-ja/org/sso/sso-saml.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.