OIDC SSO setup

Overview

MailSlurp organization admins can use OpenID Connect (OIDC) for enterprise single sign-on with identity providers such as Microsoft Entra ID, Okta, Auth0, Google Workspace, OneLogin, Ping Identity, Keycloak, or any OIDC provider that supports the authorization code flow.

MailSlurp uses the OIDC broker at https://oidc.mailslurp.com. The broker redirects users to your identity provider, validates the authorization-code response, provisions or finds the matching organization user, applies role mappings, and returns the browser to the MailSlurp dashboard.

Before You Start

You need:

• A MailSlurp enterprise organization with OIDC SSO enabled.
• Admin access to an OIDC identity provider.
• The MailSlurp organization slug.
• An OIDC application client ID and client secret.
• Any MailSlurp organization roles you want to assign from provider claims.
• Any MailSlurp environments you want users to access after OIDC sign-in.

MailSlurp Organization Setup

OIDC is configured on a MailSlurp organization. The first administrator signs in to MailSlurp with a normal MailSlurp login, creates or opens the organization, configures OIDC, and then shares the organization OIDC login URL with users.

Recommended MailSlurp setup:

1. Sign in to the MailSlurp dashboard as the account owner or an organization admin.
2. Open Settings > Organizations.
3. Create a new organization, or open the organization that will use OIDC.
4. Open the organization access settings and confirm which email domains or exact email addresses are allowed to join.
5. Create any MailSlurp roles that should be assigned from OIDC claims.
6. Open OIDC SSO for the organization and copy the redirect URI and login URL.

Keep at least one owner or admin account that can sign in outside OIDC for setup and recovery. Organization OIDC users should use the organization OIDC login URL, for example https://oidc.mailslurp.com/login?slug={organization-slug}. Normal MailSlurp email login does not read OIDC claims or apply OIDC role mappings.

When a user signs in through OIDC for the first time, MailSlurp reads the configured email claim. If that email already exists in the organization, MailSlurp links the OIDC identity to the existing organization user. If the email is allowed and does not exist yet, MailSlurp provisions a new organization user. After that first link is created, MailSlurp uses the provider issuer and stable subject claim to recognize the same identity on future sign-ins.

MailSlurp OIDC Features

MailSlurp OIDC SSO supports:

• Organization-specific login URLs for enterprise SSO.
• Authorization code flow through the MailSlurp OIDC broker.
• Provider discovery from the issuer URL when the provider exposes OIDC metadata.
• Client secret authentication with configurable token endpoint auth method.
• Configurable scopes, email claim, subject claim, and groups claim.
• Optional endpoint overrides for providers that do not expose standard discovery metadata.
• Just-in-time user provisioning for users who authenticate successfully.
• Existing organization user matching when the authenticated email already belongs to a MailSlurp user.
• Default MailSlurp role assignment for newly provisioned users.
• Claim-to-role mappings for groups, app roles, or custom provider claims.
• Optional verified-email enforcement when the provider reliably emits an email_verified claim.

OIDC SSO does not replace MailSlurp API keys, dashboard cookies, temporary access tokens, email-link login, or SAML. It is an enterprise organization sign-in option that starts from a dedicated organization login URL and then resumes the normal MailSlurp dashboard session.

OIDC Provider Requirements

Use an OIDC provider that can issue ID tokens through the authorization code flow and can register a web redirect URI. The provider should expose:

Provider capability	MailSlurp use
Issuer URL	Lets MailSlurp discover authorization, token, and key endpoints
Client ID	Identifies the OIDC application
Client secret	Authenticates MailSlurp to the provider token endpoint
Redirect URI	Sends the user back to MailSlurp after authentication
openid scope	Required for OIDC ID token issuance
Email-style user claim	Lets MailSlurp find or provision the organization user
Stable subject claim	Lets MailSlurp track the provider identity
Group, role, or custom claims	Lets MailSlurp map provider authorization data to MailSlurp roles

For most providers, start with openid profile email scopes. If the provider does not place the user’s usable login email in email, set the MailSlurp email claim to the claim your provider emits, such as preferred_username, upn, or a custom claim.

MailSlurp Values For Any Provider

Open Settings > Organizations > your organization > OIDC SSO in MailSlurp.

Use these values in your identity provider:

Field	Value
Redirect URI	https://oidc.mailslurp.com/callback/{organization-slug}
Login URL	https://oidc.mailslurp.com/login?slug={organization-slug}
Environment landing login URL	https://oidc.mailslurp.com/login?slug={organization-slug}&returnTo=%2Fenvironment-landing
Response type	code
Grant type	authorization_code
Scopes	openid profile email

Save Generic OIDC Settings

In MailSlurp, enter the provider values:

MailSlurp field	Provider value
Issuer URL	Provider issuer URL, for example https://login.example.com/{tenant}
Client ID	OIDC application client ID
Client secret	OIDC application client secret
Scopes	Usually openid profile email
Email claim	Claim containing the MailSlurp user’s email address
Subject claim	Stable subject identifier, usually sub
Groups claim	Claim containing group or role values, often groups or roles
Token endpoint auth method	Provider requirement, often client_secret_post or client_secret_basic
Require verified email	Enable only when the provider reliably sends email_verified: true
Default role ID	Optional MailSlurp role for newly provisioned users

Select Save OIDC settings and copy the generated login URL for testing.

User Identity Matching

OIDC providers send both a user email claim and a stable subject claim. MailSlurp uses both, but for different parts of the sign-in flow.

On first OIDC sign-in, MailSlurp uses the configured email claim to find or create the organization user. If the user was already invited or provisioned by SCIM with the same email address, MailSlurp links the OIDC identity to that existing user. If no matching organization user exists and the email is allowed by the organization, MailSlurp provisions a new user.

After the first successful OIDC sign-in, MailSlurp recognizes the user by the provider issuer and subject claim. This protects the account if the email claim later changes. The existing OIDC subject link wins, so the user continues to sign in as the same MailSlurp organization user.

MailSlurp also protects existing users from accidental reassignment. If the same email address is later presented with a different OIDC subject for the same issuer, MailSlurp rejects the sign-in instead of silently attaching the new identity to the existing user. This usually means the identity provider app was recreated, the subject claim changed, or the wrong user was assigned to the application.

If this happens, verify that the user is assigned to the intended identity provider application and that the MailSlurp OIDC subject claim is still the stable provider subject, usually sub. If the identity provider application was intentionally replaced, ask your MailSlurp organization admin or MailSlurp support to reset the affected user’s OIDC link before retrying sign-in.

For SCIM-managed organizations, use the same email value for SCIM userName and the OIDC email claim whenever possible. SCIM can create, update, disable, or re-enable the MailSlurp user, while OIDC signs that same user in. When SCIM disables a user, OIDC sign-in for that linked user is blocked until the identity administrator re-enables or reassigns the user in the identity provider.

Provisioning And Role Mapping

When a user signs in through OIDC, MailSlurp checks the configured identity link, email claim, and organization settings. If the user already exists in the organization, MailSlurp signs that user in. If the user is allowed and does not exist yet, MailSlurp provisions the user and can apply the configured default role.

Use OIDC role mappings when the provider should control MailSlurp role assignment from token claims.

Common mapping patterns:

Provider model	Claim name	Claim value
Group claims	groups	Exact group ID, group slug, or group name emitted by the provider
App roles	roles	Exact app role value emitted by the provider
Custom claims	Provider-specific claim	Exact claim value emitted by the provider

Role mapping is exact-match. Check the provider’s issued ID token when a mapping does not apply, then copy the emitted claim name and claim value into the MailSlurp role mapping.

How Roles And Environments Work

OIDC decides how a user signs in to a MailSlurp organization. MailSlurp roles and environment grants decide what that signed-in user can do after sign-in.

The access model has three parts:

Part	What it controls
OIDC application assignment	Whether the identity provider lets the user start SSO
MailSlurp role mapping	Which MailSlurp organization roles are assigned from OIDC claims
Environment organization grant	Which linked MailSlurp environments the user can switch into

The sign-in sequence is:

1. A user opens the organization OIDC login URL.
2. The identity provider authenticates the user and returns OIDC claims such as email, preferred_username, groups, or roles.
3. MailSlurp finds or provisions the organization user by the configured email claim.
4. MailSlurp checks OIDC role mappings and assigns any matching MailSlurp organization roles.
5. MailSlurp starts a normal dashboard session for that organization user.
6. The environment switcher shows only the linked environments allowed by the user’s MailSlurp role or user-specific environment grant.

Roles are organization-level permissions. They can control MailSlurp capabilities such as organization administration, team access, and environment access. A provider group or app role does not directly grant a MailSlurp environment. It must first map to a MailSlurp role, and that MailSlurp role must be allowed on the environment grant.

Environments are separate MailSlurp account inventories linked to the same environment group. Each environment has its own inboxes, phone numbers, webhooks, usage, and organization context. Granting a user access to PTEST does not grant access to VTEST unless VTEST has its own matching grant.

Use role-restricted grants for repeatable access rules:

User should access	Recommended setup
Only PTEST	Map the provider’s PTEST claim to a PTEST access MailSlurp role, then restrict the PTEST environment grant to that role
Only VTEST	Map the provider’s VTEST claim to a VTEST access MailSlurp role, then restrict the VTEST environment grant to that role
All environments	Map the provider’s all-environments claim to an All environments MailSlurp role, then allow that role on each environment grant
One named exception	Add a user-specific restriction to the target environment grant

If a user has more than one matching role, MailSlurp combines the access from those roles. To remove access immediately, remove the MailSlurp role assignment, remove the user-specific environment grant, or remove the role from the environment grant. Removing the user from the identity provider application blocks future OIDC sign-ins.

OIDC With MailSlurp Environments

MailSlurp environments are linked environment accounts with separate data inventories. OIDC controls how users enter the organization. Environment access is controlled after sign-in by MailSlurp environment organization grants.

Use this model when one organization should use one OIDC configuration but different users should access different environments, such as PTEST, VTEST, or all environments. Configure OIDC on the identity or managing organization, then let that organization’s role mappings and environment grants control which environments each user can enter.

1. Create or link the MailSlurp environment accounts.
2. Create MailSlurp organization roles such as PTEST access, VTEST access, and All environments.
3. Configure OIDC role mappings from provider claims to those MailSlurp roles.
4. In Settings > Organizations > Environments, grant the organization access to each environment.
5. Restrict each environment grant to the matching role or specific users.

Example:

Provider claim	MailSlurp role	Environment grant
roles: ["MailSlurp.PTEST"]	PTEST access	PTEST environment restricted to PTEST access
roles: ["MailSlurp.VTEST"]	VTEST access	VTEST environment restricted to VTEST access
roles: ["MailSlurp.AllEnvironments"]	All environments	Each environment grant also allows All environments

After sign-in, users see only the environments permitted by their MailSlurp role or user-specific grant. A user with only PTEST access can switch into PTEST but not VTEST. A user with the all-environments role can be allowed on every environment grant.

Automatic Environment Landing From An IdP Tile

When users start MailSlurp from an IdP app tile such as Okta My Apps, use the environment landing login URL:

https://oidc.mailslurp.com/login?slug={organization-slug}&returnTo=%2Fenvironment-landing

The slug should be the identity or managing organization where OIDC settings and role mappings are configured. Do not create a separate OIDC configuration in every environment unless each environment needs its own separate login tile, app assignment policy, or administrator boundary.

The environment landing flow runs after MailSlurp has processed the OIDC claims and applied role mappings:

1. MailSlurp signs the user into the identity organization.
2. MailSlurp loads the environments allowed by that user’s MailSlurp roles and user-specific grants.
3. If exactly one non-default environment is available, MailSlurp switches the session into that environment automatically.
4. If more than one non-default environment is available, MailSlurp shows the environment chooser.
5. If no additional environment is available, MailSlurp keeps the user in the default organization context.

For Okta, configure the OIDC application tile or initiate-login URL to open the environment landing login URL above. The redirect URI in Okta remains the MailSlurp callback URL, https://oidc.mailslurp.com/callback/{organization-slug}. Okta groups or app-role style claims should still map to MailSlurp roles in the identity organization.

For strongest separation, create a separate MailSlurp organization and a separate OIDC application per environment. Use that pattern when each environment needs its own SSO login tile, administrator set, allowed domains, or identity-provider assignment policy.

For revocation, remove the user from the identity provider application to block future OIDC sign-ins, and remove any MailSlurp role assignment or environment grant that should stop immediately. OIDC role mappings are applied when users sign in, so review existing MailSlurp role assignments when identity-provider group or app-role membership changes.

Generic OIDC Setup Checklist

1. Sign in to MailSlurp as the account owner or organization admin.
2. Create or open the MailSlurp organization and copy the organization slug.
3. Create any MailSlurp roles needed for authorization or environment access.
4. Create a web OIDC application in the identity provider.
5. Add the MailSlurp redirect URI.
6. Copy the provider issuer URL, client ID, and client secret.
7. Configure scopes and token claims so the ID token includes a usable email claim.
8. Add group, role, or custom claims if MailSlurp roles should come from the provider.
9. Save the provider values in MailSlurp OIDC settings.
10. Add MailSlurp OIDC role mappings if provider claims should map to MailSlurp roles.
11. Configure environment grants if users should be limited to specific environments.
12. If users launch MailSlurp from an IdP tile, set the tile or initiate-login URL to https://oidc.mailslurp.com/login?slug={organization-slug}&returnTo=%2Fenvironment-landing.
13. Test sign-in with an existing user, a new allowed user, a mapped-role user, an environment-restricted user, and a user who should be blocked by the provider.

Microsoft Entra Setup

Use the Entra steps below when your Enterprise Application has Assignment required? enabled, and when authorization is based on Entra app roles, group claims, or both.

For Microsoft Entra deployments that also need SCIM provisioning, My Apps tile launch, or separate PTEST/VTEST/production MailSlurp environments, use the full Microsoft Entra OIDC and SCIM environment setup guide. The tested pattern is one visible OIDC Enterprise Application for sign-in and one hidden SCIM Enterprise Application for provisioning. In that pattern, SCIM group role sync normally supplies the MailSlurp roles used by environment grants, and Entra app roles are optional.

For Okta deployments that need an Okta dashboard tile, SCIM provisioning, or separate MailSlurp environments, use the full Okta OIDC and SCIM environment setup guide. The recommended custom setup is one visible OIDC web application for sign-in and one hidden SCIM provisioning application for user and group lifecycle.

Entra Prerequisites

You need:

• Microsoft Entra admin access for app registrations and Enterprise Applications.
• The MailSlurp organization slug.
• Any MailSlurp organization roles you want to assign from Entra claims.
• Any MailSlurp environments and environment access roles you want Entra to control.

Create The Entra App Registration

1. In Microsoft Entra admin center, open App registrations.
2. Select New registration.
3. Enter a clear name, such as MailSlurp OIDC.
4. Choose the supported account type for your tenant. Most organizations use single tenant.
5. Set Redirect URI to Web and paste the MailSlurp redirect URI.
6. Select Register.

After registration, copy the Application (client) ID and Directory (tenant) ID. The issuer URL for Microsoft Entra is:

https://login.microsoftonline.com/{tenant-id}/v2.0

Create A Client Secret

1. Open Certificates & secrets.
2. Select New client secret.
3. Add a description and choose an expiry that matches your credential rotation policy.
4. Select Add.
5. Copy the secret Value immediately. Entra only shows it once.

Grant API Consent

Open API permissions and grant admin consent for the app if your tenant does not allow end users to consent. In restricted tenants, users may otherwise see “Need admin approval” before Entra returns to MailSlurp.

Configure Claims

Open Token configuration.

Recommended Entra settings:

Use case	Entra setting	MailSlurp claim name
User email	Use preferred_username, or add optional email/upn claims if required	preferred_username
Stable subject	Default ID token subject	sub
App roles	Create Entra app roles	roles
Groups	Add group claims to the ID token	groups

For Entra tenants, preferred_username is usually the most reliable MailSlurp email claim because the optional email claim can be blank for users without a populated mail attribute.

Keep the subject claim set to Entra’s stable sub claim after users start signing in. If you replace the Entra application registration or change the subject claim later, existing users may need their MailSlurp OIDC link reset before they can sign in through the new identity.

Configure App Roles

If Assignment required? is enabled, create at least one access role that lets assigned users sign in. Create additional app roles for MailSlurp roles you want to map.

If you are using SCIM group role sync, you can assign Entra groups to the OIDC Enterprise Application without creating environment app roles. MailSlurp can receive users and groups from SCIM, map SCIM groups to MailSlurp roles, and use those roles for environment grants. Use Entra app roles when you want the OIDC token itself to carry role values or when you are not using SCIM group role sync.

Example Entra app roles:

Display name	Value	MailSlurp use
MailSlurp access	MailSlurp.Access	Allows assigned users to sign in
MailSlurp admin	MailSlurp.Admin	Maps to a MailSlurp organization role
MailSlurp user	MailSlurp.User	Maps to a MailSlurp organization role
MailSlurp PTEST access	MailSlurp.PTEST	Maps to a role allowed on the PTEST environment grant
MailSlurp VTEST access	MailSlurp.VTEST	Maps to a role allowed on the VTEST environment grant

When a user or group is assigned to an app role, Entra emits the role value in the OIDC roles claim.

Require Assignment

Open the Enterprise Application created for the app registration.

1. Go to Properties.
2. Set Enabled for users to sign-in? to Yes.
3. Set Assignment required? to Yes.
4. Save.

With assignment required, Entra blocks users who are not directly assigned or assigned through a group.

Assign Users And Groups

Open Users and groups in the Enterprise Application.

Use direct user assignment for simple access. Use group assignment when you want Entra group membership to control access or roles.

Common assignment patterns:

Entra assignment	Token claim	MailSlurp result
User assigned to access role	roles: ["MailSlurp.Access"]	User can sign in and receives the MailSlurp default role
User assigned to mapped app role	roles: ["MailSlurp.Admin"]	User receives the mapped MailSlurp role
User assigned to environment app role	roles: ["MailSlurp.PTEST"]	User receives the mapped role and can access matching MailSlurp environment grants
Group assigned to mapped app role	roles and groups	Group members can sign in and can receive mapped MailSlurp roles
User not assigned	Entra blocks sign-in	MailSlurp does not provision the user

Save MailSlurp OIDC Settings

In MailSlurp, enter:

MailSlurp field	Entra value
Issuer URL	https://login.microsoftonline.com/{tenant-id}/v2.0
Client ID	Entra Application (client) ID
Client secret	Entra client secret Value
Scopes	openid profile email
Email claim	preferred_username
Subject claim	sub
Groups claim	groups
Token endpoint auth method	client_secret_post
Require verified email	Off, unless your token reliably includes email_verified
Default role ID	Optional MailSlurp role for newly provisioned users

Select Save OIDC settings.

Map Entra Claims To MailSlurp Roles

Use MailSlurp OIDC role mappings when Entra app roles or groups should grant MailSlurp organization roles.

For app roles:

MailSlurp field	Value
Provider claim	Microsoft Entra app role
Claim name	roles
Claim value	The Entra app role Value, such as MailSlurp.Admin
MailSlurp role	The organization role to assign

For groups:

MailSlurp field	Value
Provider claim	Microsoft Entra group
Claim name	groups
Claim value	The Entra group object ID
MailSlurp role	The organization role to assign

For environment access, map each Entra app role or group to the MailSlurp role used by the matching environment grant. For example, map roles = MailSlurp.PTEST to the PTEST access MailSlurp role, then restrict the PTEST environment grant to that role.

Test Sign-In

1. Copy the MailSlurp login URL.
2. Open it in a private browser session.
3. Sign in as an assigned Entra user.
4. Confirm the user lands in the MailSlurp dashboard.
5. Check the organization user list and role assignments.
6. If using environments, open Settings > Organizations > Environments and confirm the user only sees the expected environments.
7. Switch into an allowed environment and confirm the dashboard loads in that environment.
8. Try a user assigned to a different environment role and confirm the environment list changes.
9. Repeat with an unassigned Entra user. Entra should block sign-in before MailSlurp provisions the user.

Troubleshooting

• If users see “Need admin approval”, grant admin consent on the Entra app’s API permissions page.
• If Entra returns AADSTS50105, the user is not assigned directly or through an assigned group while Assignment required? is enabled.
• If MailSlurp reports a missing email claim, set the MailSlurp email claim to preferred_username or add the optional Entra claim your tenant emits.
• If role mappings do not apply, compare the exact Entra app role Value or group object ID with the MailSlurp mapping claim value.
• If an environment appears for the wrong user, check that the environment grant is restricted to the intended MailSlurp role or user and that the user does not still have a broader MailSlurp role assignment.
• If MailSlurp reports that the email is already linked to a different OIDC subject, confirm the user is assigned to the intended Entra application and that the MailSlurp subject claim is still sub. If the Entra application was intentionally recreated, ask your MailSlurp organization admin or MailSlurp support to reset the affected user’s OIDC link.
• If the token request fails, confirm the client secret is the secret Value, not the secret ID, and that the token endpoint auth method is client_secret_post.

Related guides: Microsoft Entra OIDC and SCIM environments and Okta OIDC and SCIM environments.

Microsoft references: OpenID Connect on Microsoft identity platform, optional claims, app roles, and Enterprise Application assignment.