> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Single sign-on (SSO)

> Sign in to ManaLens with a work email code, with Google, or with SAML single sign-on through your identity provider, and set up SAML for your email domain.

## Sign-in methods

| Method | How |
| - | - |
| **Email code** | Enter your email. Enter the six-digit code from the email. |
| **Google** | Click **Continue with Google**. |
| **SAML SSO** | Enter your work email and click **Sign in with SSO**. |

An email code and Google give the same account for the same email address. A SAML sign-in gives a separate account, even for the same email address: see [Accounts and access](#accounts-and-access). [MFA](https://docs.manalens.dev/security/mfa.md) applies on top of every method.

> [!NOTE]
>
> Google and SAML sign-in are available only when they are turned on for your deployment. If Google sign-in is not available, the sign-in page says so: continue with your work email. Contact support to ask about SAML SSO for your organization.

## How SAML SSO works

When SSO is set up for your email domain:

1. You open the sign-in page and enter your work email.
2. You click **Sign in with SSO**.
3. ManaLens finds the identity provider for your email domain and sends you to it.
4. You sign in with your identity provider.
5. The identity provider sends you back to ManaLens, signed in.

Start each sign-in from the ManaLens sign-in page.

## Supported providers

SSO works with SAML 2.0 identity providers, such as Okta, Google Workspace and Microsoft Entra ID (Azure AD). Any identity provider that follows SAML 2.0 should work.

## Set up SAML SSO

The ManaLens team registers your identity provider. You create the SAML application in your identity provider.

**1. Contact support**

Ask support to set up SAML SSO. Give your email domains, for example `example.com` and `example.co.uk`. Each domain can have one identity provider.

Support sends you two values for your identity provider:

| Value | Also called |
| - | - |
| **ACS URL** (ends in `/sso/saml/acs`) | Single sign-on URL, Reply URL |
| **SP entity ID** (ends in `/sso/saml/metadata`) | Audience URI, Identifier |

**2. Create a SAML application**

In your identity provider, create a SAML 2.0 application with these settings:

| Setting | Value |
| - | - |
| ACS URL | The ACS URL from support |
| SP entity ID | The SP entity ID from support |
| Name ID format | `EmailAddress` |
| Name ID value | The user's email address |
| Signing | Sign the SAML response or the assertion |

**3. Map the email attribute**

Add an attribute statement named `email` with the user's email address. The email must use one of the domains you gave support.

**4. Assign users**

Assign the application to the users or groups who need ManaLens.

**5. Send the metadata**

Copy your identity provider's SAML metadata URL (or download the metadata XML file) and send it to support. Support registers it for your domains and tells you when it is ready.

**6. Test the sign-in**

1. Sign out of ManaLens, or open a private window.
2. Open the sign-in page and enter an email with your domain.
3. Click **Sign in with SSO**. You go to your identity provider.
4. Sign in. You come back to ManaLens, signed in.

### Okta

1. In the Okta Admin Console, go to **Applications** > **Applications** and click **Create App Integration**.
2. Select **SAML 2.0** and click **Next**.
3. Enter an app name, for example `ManaLens`, and click **Next**.
4. Enter the **Single sign-on URL** (the ACS URL) and the **Audience URI (SP Entity ID)**.
5. Set **Name ID format** to `EmailAddress` and **Application username** to `Email`.
6. Under **Attribute Statements**, add `email` with the value `user.email`.
7. Finish the wizard. On the **Sign On** tab, copy the **Metadata URL** and send it to support.
8. On the **Assignments** tab, assign the users or groups.

### Google Workspace

1. In the Google Admin console, go to **Apps** > **Web and mobile apps**, then **Add app** > **Add custom SAML app**.
2. Enter an app name and click **Continue**.
3. Click **Download metadata** and keep the XML file for support. Click **Continue**.
4. Enter the **ACS URL** and the **Entity ID** (the SP entity ID). Set **Name ID format** to `EMAIL` and **Name ID** to **Basic Information > Primary email**.
5. Under **Attribute mapping**, map **Primary email** to `email`.
6. Turn the app on for the organizational units or groups who need it.

### Microsoft Entra ID

1. In the Microsoft Entra admin center, go to **Enterprise applications** > **New application** > **Create your own application**. Choose **Integrate any other application you don't find in the gallery**.
2. Open **Single sign-on** and choose **SAML**.
3. Under **Basic SAML Configuration**, enter the **Identifier (Entity ID)** (the SP entity ID) and the **Reply URL** (the ACS URL).
4. Under **Attributes & Claims**, set the **Unique User Identifier** to `user.mail` with the format `Email address`, and add a claim named `email` with the value `user.mail`.
5. Copy the **App Federation Metadata Url** and send it to support.
6. Under **Users and groups**, assign the users or groups.

## Accounts and access

SSO proves who you are. It does not give access to a workspace.

* An owner or admin must still [invite](https://docs.manalens.dev/security/roles.md#invitations) you, and your role decides what you can do. Accept the invite while you are signed in with SSO.
* A new identity does not get a membership only because its email matches a member.
* A SAML account is separate from an email code or Google account with the same email address. It has its own workspace memberships and its own [MFA](https://docs.manalens.dev/security/mfa.md) authenticator.

To move a member who signed in with an email code to SSO, an owner or admin removes the member on the **Members** page and invites the same email again. The member then accepts the invite with SSO.

## Remove access

1. Remove the user from the SAML application in your identity provider. They can no longer sign in with SSO.
2. Remove the user on the **Members** page of each workspace. This ends their access to the workspace at once, even in a session that is already open.

SSO does not stop users of your domain from signing in with an email code. Workspace access always comes from membership, so remove members who should no longer have access.

## Troubleshooting

| Problem | Check |
| - | - |
| **Sign in with SSO** shows an error | SSO is not set up for the domain of the email you entered. Check the spelling, or contact support. |
| The identity provider refuses the user | The user is assigned to the SAML application. |
| You come back to the sign-in page with an error | The ACS URL and the SP entity ID match the values from support exactly, with no extra slash or space. The Name ID format is `EmailAddress`, and the response or assertion is signed. |
| You are signed in, but your workspace is missing | The SAML account has no membership yet. Ask an owner or admin to invite your email, then accept the invite with SSO. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.