> 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/tech/maiagent-tech-ja/advanced-genai-tech/saml-sso.md).

# SAML SSO シングルサインオン連携

> 本書では、MaiAgent プラットフォームが SAML 2.0 プロトコルを連携し、企業レベルのシングルサインオン（Single Sign-On, SSO）機能を実現する方法、ならびにユーザー認証の安全性と正確性を確保する仕組みについて説明します。

## 1. SAML SSO とは？

SAML（Security Assertion Markup Language）は XML をベースとしたオープンスタンダードであり、IDプロバイダー（Identity Provider, IdP）とサービスプロバイダー（Service Provider, SP）の間で認証情報や認可情報を交換するために利用されます。

### 1.1 SAML SSO の主なメリット

| 検討の観点        | 従来の複数ログイン方式                    | SAML SSO 方式                               |
| ------------ | ------------------------------ | ----------------------------------------- |
| **ユーザー体験**   | システムごとに個別ログインが必要で、パスワードの管理が煩雑  | 一度のログインで複数のシステムにアクセスでき、業務効率が向上            |
| **安全性**      | パスワードが複数システムに分散して保存され、漏洩リスクが増大 | パスワードは企業の IdP のみに保存され、一元管理でより安全           |
| **アカウント管理**  | 退職時に各システムのアカウントを個別に無効化する必要がある  | IdP でアカウントを無効化すれば、すべてのシステムのアクセス権を一括で取り消せる |
| **コンプライアンス** | アクセス記録の統一的な監査・管理が難しい           | 一元化された ID 管理により、企業のセキュリティコンプライアンス要件を満たす   |

### 1.2 主な利用シーン

* **企業内システム連携**: 従業員が自社の Active Directory または Okta を使って MaiAgent にログイン
* **教育機関**: 学生や教職員が学校の IdP を使って AI 学習アシスタントにアクセス
* **マルチテナント SaaS**: 各企業顧客がそれぞれの IdP を使って MaiAgent プラットフォームにログイン
* **パートナー協業**: 外部パートナーが自社の企業アカウントを使って特定のリソースにアクセスすることを許可

***

## 2. MaiAgent SAML SSO アーキテクチャ

```mermaid
sequenceDiagram
    participant User as ユーザー
    participant Browser as ブラウザ
    participant MaiAgent as MaiAgent (SP)
    participant IdP as 企業 IdP
    
    User->>Browser: MaiAgent にアクセス
    Browser->>MaiAgent: アクセスを要求
    MaiAgent->>Browser: IdP へリダイレクト<br/>(SAML AuthnRequest)
    Browser->>IdP: 認証リクエストを転送
    
    IdP->>User: ログインページを表示
    User->>IdP: 企業アカウントとパスワードを入力
    IdP->>IdP: ユーザー身元を検証
    
    IdP->>Browser: SAML Response を返却<br/>(ユーザー属性を含む)
    Browser->>MaiAgent: POST SAML Response
    
    MaiAgent->>MaiAgent: SAML 署名を検証
    MaiAgent->>MaiAgent: ユーザー属性を解析<br/>(Email、氏名など)
    MaiAgent->>MaiAgent: Email を正規化<br/>(小文字に変換)
    
    alt ユーザーが既に存在
        MaiAgent->>MaiAgent: ログインセッションを作成
    else ユーザーが存在しない
        MaiAgent->>MaiAgent: アカウントを自動作成
    end
    
    MaiAgent->>Browser: アプリのトップページへリダイレクト
    Browser->>User: MaiAgent の画面を表示
```

### 2.1 主要コンポーネントの説明

* **Service Provider (SP)**: MaiAgent プラットフォームがサービスプロバイダーとして機能し、SAML 応答を受信・検証します
* **Identity Provider (IdP)**: Azure AD、Okta、Google Workspace などの企業の認証システム
* **SAML Assertion**: IdP が署名した XML 文書で、ユーザーの身元情報と属性情報を含みます
* **Metadata Exchange**: SP と IdP が XML metadata を通じて構成情報を交換します

### 2.2 ユーザー属性のマッピング

MaiAgent は SAML Assertion から以下のユーザー属性を抽出します。

* **Email (必須)**: ユーザーの一意な識別子として使用され、一貫性を確保するために自動的に小文字へ変換されます
* **名称**: ユーザーの表示名
* **組織情報**: 部署、役職など（IdP の構成に依存）
* **グループ/ロール**: 権限管理とアクセス制御に使用

***

## 3. Email 正規化処理

### 3.1 なぜ Email の正規化が必要なのか？

Email アドレスは技術的には大文字・小文字を区別しません（RFC 5321）が、システムによって異なる大文字・小文字の形式で出現する場合があります。

* IdP からの返却: `John.Doe@Company.com`
* ユーザーの手動入力: `john.doe@company.com`
* API 呼び出し: `JOHN.DOE@COMPANY.COM`

正規化処理を行わない場合、以下のような問題が生じる可能性があります。

* 同一ユーザーに対して複数のアカウントが作成される
* 権限判定の誤り
* データの不整合

### 3.2 MaiAgent の正規化方針

MaiAgent は SAML SSO 連携において、以下の Email 正規化措置を実装しています。

システムは Email の前後の空白を自動的に除去し、一律で小文字形式に変換することで、アカウント照合の一貫性を確保します。

**正規化を行うタイミング**:

1. **SAML 応答の解析時**: IdP からユーザーの Email を受信した直後に小文字へ変換
2. **アカウント作成時**: 新規ユーザーアカウントを作成する前に Email が小文字であることを確認
3. **アカウント検索時**: 既存ユーザーを検索する際にも小文字の Email を使用
4. **データベース保存時**: 保存されるすべての Email を小文字形式で保持

### 3.3 後方互換性への対応

正規化機構の実装前に作成されたアカウントについて、MaiAgent は以下の方針を採用しています。

* **自動移行**: システムが既存アカウントの Email を自動的に小文字へ変換します
* **重複検出**: 変換の過程で重複アカウントが存在しないかを検出します
* **競合解決**: 競合が見つかった場合は、最も早く作成されたアカウントを保持し、データを統合します

***

## 4. アカウントの自動作成とアカウント競合の処理

### 4.1 アカウント自動作成フロー

ユーザーが初めて SAML SSO でログインすると、MaiAgent は自動的にアカウントを作成します。

```mermaid
flowchart TD
    A["SAML Response を受信"] --> B["ユーザー Email を解析"]
    B --> C["Email を小文字に変換"]
    C --> D{"アカウントは存在するか？"}
    D -- "はい" --> E["既存アカウントを読み込み"]
    D -- "いいえ" --> F["新規アカウントを自動作成"]
    F --> G["デフォルト権限を設定"]
    G --> H["ログインセッションを作成"]
    E --> H
    H --> I["トップページへリダイレクト"]
```

**自動作成時のデフォルト設定**:

* **表示名**: SAML Assertion 内の name 属性から抽出
* **デフォルト権限**: 組織の設定に基づいて基本権限を割り当て
* **組織の所属**: Email domain または IdP の構成に基づいて決定

### 4.2 アカウントが既に存在する場合の処理

MaiAgent はインテリジェントなアカウント競合の検出・処理機構を実装しています。

* **Email が登録済み**: ユーザーが以前に同一の Email（小文字）で登録している場合は、既存アカウントへ直接ログインします
* **通知メールの送信**: 既存アカウントを検出した際に、ユーザーへメールで通知します
* **重複作成の防止**: データベースの一意制約（Unique Constraint）により、同一 Email で複数のアカウントが作成されないようにします

### 4.3 安全性に関する考慮事項

* **Email 検証**: IdP が提供する Email は企業の身元認証を通過済みのため、これを信頼します
* **SAML 署名の検証**: SAML Response のデジタル署名を厳格に検証し、偽造を防止します
* **タイムスタンプの確認**: SAML Assertion が有効期限切れでないことを確認します
* **リプレイ攻撃の防止**: 使用済みの SAML Response ID を記録し、再利用を防止します

***

## 5. SAML SSO の構成手順

### 5.1 IdP 側での構成

企業の IT 管理者は IdP（Okta、Azure AD など）で以下を行う必要があります。

1. **新しい SAML アプリケーションを作成**
2. **MaiAgent の ACS URL を設定**（Assertion Consumer Service URL）
3. **ユーザー属性のマッピングを構成**し、Email が含まれていることを確認
4. **IdP Metadata XML をダウンロード**し、MaiAgent に提供

### 5.2 MaiAgent 側での構成

MaiAgent の管理者は以下を行う必要があります。

1. **IdP Metadata XML を MaiAgent の管理画面にアップロード**
2. **Entity ID を設定**し、この SAML 連携を識別
3. **属性マッピングルールを構成**し、Email や氏名などのフィールドを対応付け
4. **SAML SSO を有効化**し、ログインフローをテスト

### 5.3 テストと検証

構成が完了したら、以下のテストを実施することを推奨します。

* **初回ログインテスト**: アカウント自動作成機能が正常に動作することを確認
* **再ログインテスト**: 既存アカウントでのログインを確認
* **Email 大文字・小文字テスト**: 異なる大文字・小文字形式の Email がすべて正しく識別されることを検証
* **ログアウトテスト**: シングルログアウト（SLO）機能が正常に動作することを確認

***

## 6. MaiAgent SAML SSO の技術的メリット

### 6.1 安全性のメリット

* **企業レベルの認証**: 企業の既存の ID 管理システムを活用し、認証基準の一貫性を確保
* **パスワードは MaiAgent を経由しない**: ユーザーのパスワードは企業の IdP でのみ検証され、漏洩リスクを低減
* **一元化されたアクセス制御**: IT 管理者が IdP ですべてのアプリケーションのアクセス権限を一元管理可能
* **多要素認証の強制**: IdP で MFA が有効化されている場合、ユーザーが MaiAgent にログインする際にも MFA が要求されます

### 6.2 管理効率のメリット

* **アカウントの自動作成**: 手動でアカウントを作成する作業負担を軽減
* **アカウントの自動無効化**: 従業員の退職時に IdP でアカウントを無効化すれば、MaiAgent のアクセス権も即座に失効
* **属性の同期**: ユーザーの氏名や部署などの情報が変更された際に自動で同期
* **監査記録**: すべてのログイン活動が完全に記録され、セキュリティ監査が容易

### 6.3 ユーザー体験のメリット

* **シームレスなログイン**: ユーザーが既に企業システムにログインしている場合、MaiAgent にアクセスする際にパスワードの再入力が不要になることがあります
* **統一されたログイン画面**: 使い慣れた企業のログインページを利用でき、追加のパスワードを記憶する必要がありません
* **モバイルデバイスに優しい**: モバイルデバイス上での SSO 体験をサポート

***

## 7. トラブルシューティング

### 7.1 よくある問題

| 問題             | 考えられる原因            | 解決方法                                     |
| -------------- | ------------------ | ---------------------------------------- |
| **ログインできない**   | SAML 署名の検証に失敗      | IdP の証明書が有効期限切れでなく、Metadata が最新版であることを確認 |
| **重複アカウントの作成** | Email の大文字・小文字が不一致 | システムに Email 正規化の修正が適用済みであることを確認          |
| **属性の欠落**      | IdP が必須属性を送信していない  | IdP の属性マッピング構成を確認し、Email が含まれていることを確認    |
| **タイムスタンプエラー** | サーバー時刻が同期していない     | SP と IdP のシステム時刻が一致していることを確認（NTP の使用を推奨） |

### 7.2 デバッグツール

* **SAML-tracer**: ブラウザ拡張機能で、SAML メッセージを捕捉・解析できます
* **MaiAgent ログ**: 詳細な SAML 処理ログを確認できます
* **IdP 管理画面**: IdP 側のエラーログとユーザー属性を確認できます

***

## 8. 関連ドキュメント

* [組織とメンバーの管理](https://docs.maiagent.ai/org/role-permission) - SAML ユーザーの権限管理について理解する
* [サードパーティログイン（SSO）](https://docs.maiagent.ai/org/sso) - ユーザーガイド内の SSO 構成説明

### 参考リンク

* [SAML 2.0 Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)
* [SAML Security Best Practices](https://www.oasis-open.org/committees/download.php/56776/sstc-saml-sec-consider-2.0-os.pdf)


---

# 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/tech/maiagent-tech-ja/advanced-genai-tech/saml-sso.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.