> 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/ja/identity-and-access/sso-overview/saml-sso.md). # SAML SSO シングルサインオン連携 SAML SSO によるシングルサインオン連携：IdP と SP のアーキテクチャ、メールアドレスの正規化、アカウントの自動作成と競合処理、設定手順、制限、トラブルシューティングを説明します。 > 本ドキュメントでは、SAML 2.0 サービスプロバイダー（SP）としての MaiAgent プラットフォームの技術仕様を説明します。ログインフロー、読み取るユーザー属性、アカウントの作成・照合ルール、設定時に準備する情報を扱います。管理画面での操作や Microsoft Entra ID の詳細な設定手順は、ユーザーマニュアルの「[SAML 連携](https://docs.maiagent.ai/org/sso/sso-saml)」を参照してください。 ## 1. SAML SSO とは SAML（Security Assertion Markup Language）は、ID プロバイダー（Identity Provider、IdP）とサービスプロバイダー（Service Provider、SP）の間で認証・認可データを交換するための、XML ベースのオープン標準です。 {% hint style="info" %} SAML SSO の導入効果と利用シーンは、ユーザーマニュアルの「[外部サービスによるログイン（SSO）](https://docs.maiagent.ai/org/sso)」を参照してください。 {% endhint %} *** ## 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 へリダイレクト
(SAML AuthnRequest) Browser->>IdP: 認証リクエストを転送 IdP->>User: ログインページを表示 User->>IdP: 企業アカウントとパスワードを入力 IdP->>IdP: ユーザーの本人確認 IdP->>Browser: SAML Response を返却
(ユーザー属性を含む) Browser->>MaiAgent: SAML Response を POST MaiAgent->>MaiAgent: SAML 署名を検証 MaiAgent->>MaiAgent: ユーザー属性を解析
(メールアドレス、氏名など) MaiAgent->>MaiAgent: メールアドレスを正規化
(小文字に変換) 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 ドキュメントで、ユーザーの ID と属性情報を含みます * **IdP 設定の取得元**：MaiAgent は IdP Metadata URL から IdP 設定を自動取得できます。または、管理者が Entity ID、SSO URL、X.509 証明書を手動で入力できます（5.2 節を参照してください） ### 2.2 ユーザー属性のマッピング MaiAgent が読み取る属性は、**メールアドレス**と**表示名**の 2 つだけです。マッピングルールは固定されており、**管理画面ではカスタマイズできません**。部署、役職、グループ、ロールなどの他の属性は読み取りません。 | 用途 | MaiAgent が読み取る属性（優先順） | 説明 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | メールアドレス（必須） |

1. （Microsoft Entra ID、ADFS のデフォルト出力）
2. urn:oid:0.9.2342.19200300.100.1.3 または
3. 形式が urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress の NameID

| 小文字に変換してアカウント識別子として使用します。3 つともない場合はログインに失敗します | | 表示名 | `http://schemas.microsoft.com/identity/claims/displayname` | 初回ログインでアカウントを作成する際にのみ書き込みます。提供されない場合は、メールアドレスの @ より前の文字列、または IdP が送信した氏名属性を使用します | IdP 側で、上表にあるメールアドレス属性を少なくとも 1 つ送信していることを確認してください。 *** ## 3. メールアドレスの正規化 ### 3.1 メールアドレスの正規化が必要な理由 メールアドレスは技術上、大文字と小文字を区別しません（RFC 5321）が、システムによって異なる表記で現れることがあります。 * IdP が返す値：`John.Doe@Company.com` * ユーザーが手動入力する値：`john.doe@company.com` * API 呼び出しで使用する値：`JOHN.DOE@COMPANY.COM` 正規化しない場合、以下の問題が発生する可能性があります。 * 同じユーザーに複数のアカウントが作成されます * 権限判定が誤ります * データに不整合が生じます ### 3.2 MaiAgent の正規化方針 システムはメールアドレスをすべて小文字に変換し、アカウント照合の一貫性を確保します。 **正規化のタイミング**： 1. **SAML レスポンスの解析時**：IdP からユーザーのメールアドレスを受信した直後に小文字に変換します 2. **アカウントの検索時**：小文字のメールアドレスで既存ユーザーを検索します 3. **データベースへの保存時**：ユーザーアカウントを保存する際、メールアドレスを必ず小文字で保存します *** ## 4. アカウントの自動作成とアカウント競合の処理 ### 4.1 アカウントの自動作成フロー ユーザーが初めて SAML SSO でログインすると、MaiAgent はアカウントを自動作成します。 ```mermaid flowchart TD A["SAML Response を受信"] --> B["ユーザーのメールアドレスを解析"] B --> C["メールアドレスを小文字に変換"] C --> D{"アカウントは存在しますか?"} D -- "はい" --> E["既存アカウントを読み込み"] D -- "いいえ" --> F["新規アカウントを自動作成"] F --> H["ログインセッションを作成"] E --> H H --> I["ホームページへリダイレクト"] ``` **自動作成時の設定**： * **表示名**：2.2 節のルールに従って取得します * **ログイン元**：この SAML 認証ソースに設定します * **所属組織**：この認証ソースにデフォルト組織が設定されている場合、アカウントは自動的にその組織のメンバーになります * **ロール**：SAML はロールを送信・同期しません。組織管理者が MaiAgent 管理画面でメンバーのロールを割り当てます ### 4.2 既存アカウントの処理 * **メールアドレスが登録済みの場合**：ユーザーが同じメールアドレス（小文字）で登録済みの場合は、既存アカウントに直接ログインします。そのアカウントのログイン元はこの SAML 認証ソースに変更され、この認証ソースのデフォルト組織に参加します * **通知メールを送信しません**：既存アカウントが見つかった場合は、ユーザーに通知メールを送らずに直接関連付けます * **重複作成の防止**：データベースの一意制約（Unique Constraint）により、同じメールアドレスで複数のアカウントが作成されないようにします ### 4.3 セキュリティ上の考慮事項 * **メールアドレスの検証**：企業の認証を通過しているため、IdP が提供するメールアドレスを信頼します * **SAML 署名の検証**：SAML Response のデジタル署名を厳密に検証し、偽造を防ぎます * **タイムスタンプの確認**：SAML Assertion が期限切れでないことを確認します * **MaiAgent からログインを開始してください**：MaiAgent のログインページから SSO ログインを開始することを推奨します。IdP ポータルから直接開始するログイン（IdP-initiated）は完了できない場合があります。必要な場合は MaiAgent の担当窓口にお問い合わせください *** ## 5. SAML SSO の設定手順 ### 5.1 IdP 側の設定 企業の IT 管理者は、Okta、Azure AD などの IdP で以下を実施します。 1. **新しい SAML アプリケーションを作成します** 2. **MaiAgent の SP 情報を入力します**： * Entity ID（Audience URI）：`{MaiAgent 後端網址}/accounts/saml/{認證來源名稱}/metadata/` * ACS URL（Reply URL）：`{MaiAgent 後端網址}/accounts/saml/{認證來源名稱}/acs/` MaiAgent 側で SAML 設定を保存すると、両方の URL が設定ページの「Service Provider 情報」に表示され、そのままコピーできます。 2 つの値の役割は異なります。**Entity ID** は SP としての MaiAgent の識別名で、IdP はこれを使って Assertion の送信先（Audience）を判断します。**ACS URL**（Assertion Consumer Service）は、ユーザーが IdP でログインに成功した後、IdP が署名済み SAML Response をブラウザーの POST で送信する MaiAgent のエンドポイントです。MaiAgent はここで署名を検証し、メールアドレス属性を読み取ってログインを完了します。IdP は事前登録された ACS URL にのみレスポンスを送るため、末尾の `/` を含め、MaiAgent に表示される値と完全に一致させる必要があります。誤っている場合は IdP が拒否するか、MaiAgent がレスポンスを受信できません。これは MaiAgent のログイン入口（`/auth/saml/{認證來源名稱}/login/`、ユーザーが「SSO ログイン」をクリックした際にリダイレクトされる URL）とは別のエンドポイントです。 3. **メールアドレス属性の送信を確認します**：2.2 節にあるメールアドレス属性のいずれかを送信します。氏名を表示する場合は、さらに `displayname` を送信します 4. **IdP 設定を取得します**：IdP Metadata URL、または IdP Entity ID、SSO URL、X.509 証明書を取得します ### 5.2 MaiAgent 側の設定 MaiAgent 管理者は、組織設定の 外部サービスによるログイン設定 で SAML を選択し、認証ソース名（SP の URL の一部になります）を入力します。その後、以下の **どちらか 1 つ**のモードで IdP 設定を入力してください。両方を同時には入力できません。 | モード | 入力する項目 | 説明 | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | A：Metadata URL | IdP Metadata URL | 保存時にシステムが metadata をダウンロード・解析し、Entity ID、SSO URL、証明書を自動取得します。MaiAgent サーバーからこの URL にアクセスできる必要があり、接続できない場合や形式が誤っている場合は保存できません | | B：手動設定 | IdP Entity ID、IdP SSO URL、IdP X.509 証明書 | 3 項目すべての入力が必要です。証明書には、PEM の `BEGIN CERTIFICATE` と `END CERTIFICATE` の間にある base64 内容を入力します。Google Workspace など、Metadata URL を提供できず、metadata ファイルのダウンロードのみが可能な IdP に適しています | 任意項目の メールドメイン：設定すると、このドメインのメールアドレスを持つメンバーがログインページでメールアドレスを入力した際、自動的にこの SAML ログインへリダイレクトされます。 MaiAgent には「IdP Metadata XML ファイルのアップロード」項目はありません。metadata ファイルしかない場合は、ファイルから Entity ID、SSO URL、証明書を取り出し、モード B を使用してください。属性マッピングの設定項目もありません。ルールは 2.2 節を参照してください。 保存後、ページには SP 情報とメンバー向けのログインリンクが表示されます。 ### 5.3 テストと検証 設定完了後は、以下のテストを行うことを推奨します。 * **初回ログインテスト**：アカウントの自動作成が正常に機能することを確認してください * **再ログインテスト**：既存アカウントでログインすることを確認してください * **メールアドレスの大文字・小文字テスト**：異なる大文字・小文字の表記でもメールアドレスを正しく識別できることを確認してください * **ログアウトテスト**：Single Logout（SLO）が正常に機能することを確認してください *** ## 6. 制限と注意事項 * **属性マッピングは固定です**：メールアドレスと表示名のみを読み取ります。マッピングはカスタマイズできず、グループや部署も読み取りません * **氏名は同期されません**：表示名は初回ログイン時にのみ書き込みます。その後 IdP 側で変更しても MaiAgent には同期されません * **ロールは同期されません**：SAML はロールを渡しません。IdP のグループに基づいてメンバーとロールを自動設定する必要がある場合は、[SCIM などのメンバープロビジョニング方式](/tech/ja/identity-and-access/member-provisioning.md)を使用してください * **退職時の無効化**：SSO はログイン時にのみアカウントを作成します。IdP でユーザーを無効化しても MaiAgent のメンバーは無効化されません。退職者は SCIM または管理画面で無効化してください * **IdP 証明書の更新**：Metadata URL モードは保存時にのみ metadata を読み取ります。IdP が署名証明書を変更した場合は、設定ページで再保存するか（モード A）、X.509 証明書の項目を更新してください（モード B）。対応しないと署名検証に失敗します *** ## 7. トラブルシューティング ### 7.1 よくある問題 | 問題 | 考えられる原因 | 解決方法 | | -------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- | | **ログインできません** | SAML 署名の検証に失敗しています | IdP の証明書が期限切れでないことを確認してください。IdP が証明書を変更した場合は、[第 6 節](#limitations)に従って再保存するか証明書を更新してください | | **重複アカウントが作成されます** | メールアドレスの大文字・小文字が一致していません | メールアドレス正規化の修正がシステムに適用されていることを確認してください | | **属性がありません** | IdP がメールアドレス属性を送信していません | ログインは `error=email_not_found` を伴って元の画面に戻されます。IdP から 2.2 節にあるメールアドレス属性のいずれかを送信してください | | **IdP ポータルでアプリケーションをクリックしてもログインできません** | MaiAgent ではなく IdP がログインを開始しています | IdP でアプリケーションのログイン URL（Sign-on URL）を MaiAgent のログインリンクに設定し、MaiAgent からログインを開始するようにしてください | | **タイムスタンプエラーが発生します** | サーバーの時刻が同期されていません | SP と IdP のシステム時刻を一致させてください（NTP の使用を推奨します） | ### 7.2 デバッグツール * **SAML-tracer**：SAML メッセージをキャプチャ・解析できるブラウザー拡張機能です * **MaiAgent ログ**：SAML 処理の詳細ログを確認できます * **IdP 管理画面**：IdP 側のエラーログとユーザー属性を確認できます *** ## 8. 関連ドキュメント * [組織とメンバーの管理](https://docs.maiagent.ai/org/roles/role-permission) - SAML ユーザーの権限管理を説明します * [外部サービスによるログイン（SSO）](https://docs.maiagent.ai/org/sso) - ユーザーガイドの SSO 設定説明です * [SAML 連携](https://docs.maiagent.ai/org/sso/sso-saml) - ユーザーガイドの SAML 管理画面の操作と Microsoft Entra ID の設定手順です * [メンバープロビジョニング：SCIM／招待／SSO](/tech/ja/identity-and-access/member-provisioning.md) - メンバーの自動プロビジョニングと無効化を説明します ### 参考リンク * [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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/tech/ja/identity-and-access/sso-overview/saml-sso.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.