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

# Single sign-on

> Let people sign in through OIDC, SAML 2.0, or LDAP, map their groups to roles, and limit the email domains that may join a workspace.

Single sign-on lets people use the accounts of the company directory instead of a MoleSignal
password. Open **Identity & Access → SSO providers** and **Email domains**. Reading the providers and
domains requires `org.settings.read`, and changing them requires `org.settings.manage`.

## Before adding a provider

Set `[http].external_url` to the public address of MoleSignal. The **Redirect URI** of OIDC and the
**Assertion consumer URL (ACS)** of SAML are derived from it, and the identity provider must call
them back. Provider settings are stored in the database and apply without a restart.

## Add a provider

1. Open **SSO providers** and select **New provider**.
2. Enter a **Name** and choose the **Kind**: **OIDC**, **SAML**, or **LDAP**.
3. Fill in the settings of the kind.
4. Map the identity fields and the roles. See [Identity field mapping](#identity-field-mapping) and
   [Role binding](#role-binding).
5. Select **Create provider**.

| Kind | Settings |
| - | - |
| OIDC | **Issuer URL**, **Authorization URL**, **Token URL**, **UserInfo URL**, **JWKS URL**, **Client ID**, **Client secret**, and the **Scopes**, separated by spaces. Register the **Redirect URI** that the form shows, with **Copy redirect URI**, as an allowed callback at the identity provider. |
| SAML | **SP entity ID**, **IdP entity ID**, **IdP SSO URL**, and the **IdP signing certificate (PEM)**. Register the **Assertion consumer URL (ACS)** that the form shows, with **Copy ACS URL**, at the identity provider. |
| LDAP | **LDAP server URL**: `ldaps://`, or `ldap://` with **StartTLS** on. **User base DN**, for example `ou=people,dc=example,dc=com`. A **User search filter** that contains `{username}`, which is escaped before the search. A **Search bind DN** and its **Search bind password**: leave both empty only when the directory allows anonymous search. |

When editing a provider, leave **Client secret** or **Search bind password** empty to keep the saved
value.

## Identity field mapping

**Identity field mapping** tells MoleSignal where to read four fields of a person:

| MoleSignal field | OIDC | SAML | LDAP |
| - | - | - | - |
| **Stable subject** | A claim. Dotted paths such as `realm_access.roles` work. | An attribute name, or `NameID` for the subject of the assertion. | An attribute, or `dn` for the DN of the entry. |
| **Email** | A claim. | An attribute name. | An attribute. |
| **Display name** | A claim. | An attribute name. | An attribute. |
| **Groups** | A claim. | An attribute name. | An attribute. |

A sign-in without a valid email is refused.

## Role binding

**External group → role** lists mappings from a value of **Groups** to a MoleSignal role. Select
**Add mapping**, enter the **External group value**, for example `platform-admins`, and choose the
role. A person receives the role of every mapping that matches, and the roles are synchronized at
each sign-in.

**Default role** applies when no mapping matches. Without it, the role of self-service joining
applies.

## What happens at sign-in

The sign-in page shows a button for each enabled provider. For an LDAP provider, enter the directory
user name and password in the form first, then select the button of the provider.

1. The provider confirms the person, and MoleSignal reads the mapped fields.
2. A person without a MoleSignal account gets one, when the email passes the
   [email domains](#email-domains) of the workspace.
3. A person who is not yet a member joins the workspace of the provider with the mapped roles, or
   the default role.
4. For an existing member, the roles of matching mappings replace the earlier ones. A disabled
   account cannot sign in.

## Manage providers

The list shows each provider with its kind, whether it is enabled, and when it changed.

| Action | Effect |
| - | - |
| **Edit** | Changes the settings and the mappings. |
| **Disable** / **Enable** | A disabled provider leaves the sign-in page and refuses sign-ins. |
| **Delete** | Removes the provider. People who depend on it can no longer sign in through it. |

## Email domains

**Email domains** limits which email addresses may join the workspace through an
[invitation](https://docs.molesignal.com/en-US/identity/members.md#invitations) or single sign-on. Select **Add domain** and enter a
domain such as `example.com`. While the list is empty, any address may join. **Remove** deletes a
domain from the list.


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