# SSO

SSO lets team members sign in with an identity provider instead of a Lettermint password. Lettermint detects the user's email domain on the login screen and sends managed users to the configured provider.

:::info
Enterprise SSO is currently in preview and only available to a select group of users. Contact Lettermint if you want access for your team.
:::

:::info
SSO is available on paid plans. If your team is on the free Developer plan, managed SSO will not be shown on the login screen.
:::

{/* Screenshot placeholder: /docs/images/sso/login-managed-domain.png */}

## Supported providers

Lettermint supports generic SAML 2.0 and OpenID Connect providers. That covers common enterprise identity providers such as:

- [Google Workspace](/platform/teams/sso/providers/google-workspace)
- [Microsoft Entra ID](/platform/teams/sso/providers/microsoft-entra)
- [Okta](/platform/teams/sso/providers/okta)
- [ZITADEL](/platform/teams/sso/providers/zitadel)
- [authentik](/platform/teams/sso/providers/authentik)
- [Keycloak](/platform/teams/sso/providers/keycloak)
- [cidaas](/platform/teams/sso/providers/cidaas)
- [Ory](/platform/teams/sso/providers/ory)
- [Signicat](/platform/teams/sso/providers/signicat)
- [Custom OIDC](/platform/teams/sso/providers/custom-oidc)
- [Custom SAML](/platform/teams/sso/providers/custom-saml)

For provider-specific setup, use the generic SAML or OIDC app configuration in your identity provider and map the required values into Lettermint.

## How sign-in works

1. A user opens the Lettermint login page.
2. The user enters their work email address.
3. Lettermint checks whether the email domain belongs to an active SSO provider on a paid team.
4. If the domain is managed, the password field is hidden.
5. The user clicks **Continue with SSO** and authenticates with the identity provider.
6. Lettermint signs the user in and adds them to the team if they are not already a member.

{/* Screenshot placeholder: /docs/images/sso/login-sso-button.png */}

## Configure a SAML provider

Create a SAML 2.0 application in your identity provider and configure the service provider values from Lettermint.

Lettermint provides these service provider values for each SAML provider:

| Field | Description |
|-------|-------------|
| SP metadata URL | Public metadata URL for the Lettermint service provider configuration. |
| SP entity ID | Lettermint service provider entity ID. |
| ACS URL | Assertion Consumer Service URL where the identity provider sends SAML responses. |

You will need the following values from your identity provider:

| Field | Description |
|-------|-------------|
| Provider name | A label shown in Lettermint, for example `Okta` or `Google Workspace`. |
| Managed domains | Email domains that should use this provider, for example `example.com`. |
| Metadata URL | The identity provider metadata URL, when available. |
| Entity ID | The identity provider entity ID. |
| SSO URL | The identity provider single sign-on URL. |
| SLO URL | Optional identity provider logout URL for ending the upstream SAML session during logout. |
| Certificate | The identity provider signing certificate. |
| Attribute mapping | Optional custom SAML attribute names for email, name, first name, and last name. |

:::tip
Use the provider metadata URL when your identity provider supports it. Metadata makes certificate rollover easier because Lettermint can read the current IdP settings from one URL.
:::

{/* Screenshot placeholder: /docs/images/sso/admin-saml-provider.png */}

## Configure an OIDC provider

Create an OpenID Connect application in your identity provider and configure the Lettermint callback URL as an allowed redirect URI.

The OIDC callback URL is:

```text
https://app.lettermint.co/sso/callback
```

For local development, use the frontend URL from your environment, for example `http://localhost:3000/sso/callback`. SAML providers still use the ACS URL shown by Lettermint because SAML posts directly to the service provider endpoint.

You will need the following values:

| Field | Description |
|-------|-------------|
| Provider name | A label shown in Lettermint, for example `Microsoft Entra ID`. |
| Managed domains | Email domains that should use this provider. |
| Client ID | The OIDC client ID. |
| Client secret | The OIDC client secret. |
| Discovery URL | The provider `.well-known/openid-configuration` URL, when available. |
| Authorization URL | Required when no discovery URL is used. |
| Token URL | Required when no discovery URL is used. |
| Userinfo URL | Required when no discovery URL is used. |
| Logout URL | Optional OIDC end-session endpoint. When a discovery URL exposes `end_session_endpoint`, Lettermint can use that automatically. |
| Scopes | Optional scopes. Lettermint uses `openid email profile` by default. |

The OIDC response must include an email address in one of these claims:

- `email`
- `preferred_username`
- `upn`

{/* Screenshot placeholder: /docs/images/sso/admin-oidc-provider.png */}

## User provisioning

SSO users do not need to accept an invitation before they can access the team. After a successful SSO callback, Lettermint:

- creates the user if the email address does not already exist,
- verifies the email address,
- adds the user to the matching team as a member,
- removes a pending invite for the same email address, and
- switches the user's current team to the managed team.

:::note
SSO provisioning adds users with the Member role. Team owners can change roles after the user has joined.
:::

## Security behavior

SSO is only active when all of the following are true:

- the team is on a paid plan,
- the identity provider is active,
- the user's email domain matches one of the provider's managed domains, and
- the identity provider returns an email address for the same managed domain.

If any of these checks fail, Lettermint will not continue the SSO login.

Team owners can disable a provider to stop SSO sign-ins without deleting its configuration, or delete the provider when the connection should be removed entirely.

## Logout behavior

When a user signs in through OIDC, Lettermint keeps the OIDC logout context for the session. On logout, Lettermint returns the provider end-session URL when the provider exposes one through discovery or when a logout URL is configured manually.

When a user signs in through SAML and the provider has an SLO URL configured, Lettermint returns that SLO URL on logout so the browser can end the upstream identity provider session as well.

## Audit history

Lettermint records durable team security events for SSO setup changes, domain verification, provider updates, provider enablement, and SSO-managed user provisioning. Team members can review recent SSO events in the dashboard.

## Related docs

- [SCIM](/platform/teams/scim)
- [Team members](/platform/teams/team-members)
- [Team API tokens](/platform/teams/api-tokens)