> 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/en/identity-and-access/sso-overview.md).
# SSO and Identity Integration Overview
An overview of MaiAgent sign-in and identity integration options: built-in accounts, SAML, EIP, Keycloak, Cloudflare Access, LDAP password sign-in, and Google sign-in, including use cases, configurati
This page helps customer IT teams and SI partners choose the right identity integration: which sign-in methods MaiAgent supports, which environments each suits, what information to prepare, and how sign-in (SSO) works with member provisioning (SCIM and LDAP synchronization). Once you have chosen a method, see its dedicated page for configuration details.
{% hint style="info" %}
**How this page complements the user manual**: For administration configuration steps, see [Third-party Sign-in (SSO)](https://docs.maiagent.ai/org/sso) and its subpages in the user manual. This page covers technical specifications, selection, and combinations of methods only.
{% endhint %}
## Sign-in and Provisioning Are Separate
| Question | Handled By | Related Pages |
| ---------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------- |
| How people prove their identity and sign in to the MaiAgent website, MaiGPT, or the App | Sign-in methods (this page) | This page, [SAML SSO Integration](/tech/en/identity-and-access/sso-overview/saml-sso.md) |
| When people become organization members, who disables them when they leave, and how roles are synchronized | Member provisioning | [Member Provisioning: SCIM / Invitations / SSO](/tech/en/identity-and-access/member-provisioning.md) |
SSO creates accounts or checks identity only **at sign-in**. When an employee is disabled in the IdP, MaiAgent does not automatically disable their membership. Use SCIM, identity synchronization, or the administration interface for offboarding.
Enabling SSO also does not disable password sign-in for existing accounts: accounts that already have a MaiAgent password can still sign in with Email and password. The platform has no setting to allow only SSO sign-in. For disabling members in the administration interface, see [Offboarding and Disabling Members](https://docs.maiagent.ai/org/sso#offboarding) in the user manual.
## Sign-in Methods an Organization Can Configure
Configuration location: Organization Settings → Organization Overview → Third-party Sign-in Settings. This is an Enterprise feature, and only the organization owner can modify it.
| Method | Mechanism | Information to Enter in MaiAgent | First Sign-in | Role Synchronization | Suitable For |
| ------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| MaiAgent (default) | Email and password | No configuration required | Through an invitation or self-registration | — | Small teams without an IdP |
| SAML | SAML 2.0; MaiAgent is the SP | Either an IdP Metadata URL or an IdP Entity ID + IdP SSO URL + X.509 certificate; email domain (optional) | Automatically creates an account and joins the organization | No synchronization; reads only Email and display name | IdPs such as Entra ID, Okta, Google Workspace, and ADFS |
| EIP | MaiAgent calls your company's EIP API to retrieve user information | Server URL | Automatically creates an account and joins the organization | When EIP returns `groupIds`, replaces roles previously assigned by EIP | Custom portals without a standard IdP |
| Keycloak | A dedicated Keycloak (OIDC) flow | Server URL, Realm name, Client ID, and virtual email domain | Automatically creates an account and joins the organization; the account Email is `@` | No synchronization | Environments already using Keycloak for identity management |
| Cloudflare Access | Validates JWTs issued by Cloudflare Zero Trust | Server URL, Team Name, AUD Tag; email domain (optional); automatic member creation | Depends on Automatically Create Members: when enabled, automatically creates and adds members; when disabled, allows only existing members | No synchronization | Environments already using Cloudflare Zero Trust to protect internal services |
Rules common to all methods:
* Each organization can use only **one** sign-in method at a time. Choosing another method overwrites the original settings and cannot be undone.
* All third-party methods require an Authentication Source Name. It must be unique across the platform and becomes part of the sign-in link and SAML endpoint URLs.
* After saving, the Sign-in Link card shows a Sign-in URL you can share with members. For EIP, it instead shows the callback URL to configure in the EIP administration interface.
* After switching back to MaiAgent built-in accounts, members must use their MaiAgent passwords at their next sign-in. Accounts created through SSO that have never had a password must set one first.
* There is currently no generic OIDC configuration. For OIDC IdPs other than Keycloak, use that IdP's SAML integration instead.
For configuration steps, see [SAML Integration](https://docs.maiagent.ai/org/sso/sso-saml) (including [ADFS Integration](https://docs.maiagent.ai/org/sso/sso-saml/sso-saml-adfs)), [EIP Integration](https://docs.maiagent.ai/org/sso/sso-eip), [Keycloak Integration](https://docs.maiagent.ai/org/sso/sso-keycloak), and [Cloudflare Access Integration](https://docs.maiagent.ai/org/sso/sso-cloudflare-access). For SAML SP specifications, attributes, and account matching rules, see [SAML SSO Integration](/tech/en/identity-and-access/sso-overview/saml-sso.md) in the technical manual. For Cloudflare Access JWT validation, see [below](#cloudflare-access).
## What the Email Domain Means for Each Method
The same field serves different purposes depending on the method. A domain can be used by only one authentication source across the platform. Saving a duplicate fails with `This email domain is already in use.`.
| Method | Required? | Purpose |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAML | Optional | When a member enters an email address with this domain on the sign-in page, they are automatically redirected to this SAML sign-in (enabled on the SaaS sign-in page; depends on deployment settings for on-premises). The domain must match exactly: `user@mail.acme.com` does not match `acme.com` |
| Keycloak | Required | Forms the member account's Email (virtual email address) |
| Cloudflare Access | Optional | Allows only email addresses in this domain to sign in through Cloudflare Access |
## Cloudflare Access
This suits organizations already using Cloudflare Zero Trust to manage employee access: employees authenticate through Cloudflare Access first, and MaiAgent then trusts the identity issued by Cloudflare. For the fields to enter (Server URL, Team Name, AUD Tag, email domain, and automatic member creation) and account matching rules, see [Cloudflare Access Integration](https://docs.maiagent.ai/org/sso/sso-cloudflare-access#configure-in-maiagent) in the user manual.
At sign-in, MaiAgent redirects the member to `/api/auth/cloudflare//callback/`. This path must pass through Cloudflare Access and be forwarded to MaiAgent so that Cloudflare adds the `Cf-Access-Jwt-Assertion` header to the request. MaiAgent uses the team's public key to validate the JWT signature (RS256), checks the AUD and issuer, and then matches the account using the Email in the JWT. If validation fails or sign-in is not allowed, the member is redirected back to MaiAgent with an error message.
## Sign-in Methods Outside Third-party Sign-in Settings
| Method | Description | Configuration Location |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| LDAP password sign-in | Import people from the LDAP directory through identity synchronization first, then enable LDAP password sign-in. Members enter their Email and enterprise password on the MaiAgent sign-in page, and MaiAgent validates them against LDAP. Once enabled, synchronized members' original MaiAgent passwords are no longer valid | Organization Settings → Organization Overview → Identity Synchronization (Enterprise; only the organization owner can enable or change it, while members with the Identity Synchronization permission can view it). See [Identity Synchronization (LDAP)](https://docs.maiagent.ai/org/sso/identity-sync#ldap-login) in the user manual |
| Google sign-in | Sign in with Google on the SaaS sign-in page. Matches an existing account by the Email verified by Google, or creates a new account if none exists | Provided by the platform; organizations cannot configure it. Membership still depends on invitations, SCIM, or the organization's SSO |
## Combining Sign-in with Member Provisioning
| Your Environment | Recommended Combination |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| An IdP that supports SCIM (Entra ID, Okta, JumpCloud) | Use SCIM for the member roster, roles, and offboarding, and SAML for sign-in. See [Member Provisioning: SCIM](/tech/en/identity-and-access/member-provisioning.md#scim) |
| AD or another LDAP directory | Use LDAP identity synchronization for the roster and roles, then choose LDAP password sign-in or SAML through ADFS |
| A custom portal | Use EIP for sign-in and synchronize roles at sign-in. Manage the roster and deactivation separately through the [Member Roster Synchronization Tool](/tech/en/identity-and-access/member-provisioning/member-roster-sync.md) or the administration interface |
| Employees use MaiGPT only within your own system | SSO is not required: provision members through SCIM or [Real-time Synchronization](/tech/en/identity-and-access/member-provisioning/member-event-sync.md), then embed it using member identities |
{% hint style="warning" %}
Members who use only SSO and have no MaiAgent password can also use the organization account sign-in entry point on the OAuth authorization page. After signing in through the administration interface, they return to the authorization page and allow MCP clients such as Claude to connect as them. See [MaiAgent as an OAuth 2.1 Authorization Server](/tech/en/identity-and-access/maiagent-oauth-server.md#login-and-consent).
{% endhint %}
## Frequently Asked Questions
Can SAML and Keycloak be enabled at the same time?
No. An organization can have only one sign-in method at a time. Choosing another overwrites the original settings. If different departments need different IdPs, consolidate them into a single entry point on the IdP side.
Why is LDAP missing from Third-party Sign-in Settings?
LDAP password sign-in is tied to identity synchronization: you must complete LDAP synchronization before enabling it under Identity Synchronization. Third-party Sign-in Settings manages only SAML, EIP, Keycloak, and Cloudflare Access.
Third-party Sign-in Settings is missing or cannot be saved?
Third-party sign-in is an Enterprise feature, and only the organization owner can modify it. Non-Enterprise organizations receive `Only enterprise plan can modify third-party authentication.` when saving.
---
# 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/en/identity-and-access/sso-overview.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.