Use this guide to connect Okta to MailSlurp with OIDC single sign-on, SCIM provisioning, and role-based access to separate MailSlurp environments such as `staging`, `qa`, and `test`.

The recommended Okta setup uses two Okta applications:

1. A user-facing OIDC web application. This is the app tile users click from the Okta dashboard.
2. A hidden SCIM provisioning application. This app creates, updates, disables, and groups MailSlurp organization users.

Use the same Okta groups for both applications. The OIDC app controls who can sign in and which group claims MailSlurp receives during login. The SCIM app provisions users and groups into MailSlurp so MailSlurp can keep users, group memberships, and role assignments in sync.

If MailSlurp provides a published Okta Integration Network app for your tenant in the future, use that app's combined SSO and provisioning instructions when it explicitly supports both. Until then, the two-app setup is the reliable custom-app pattern.

## How the environment model works

Configure OIDC and SCIM on one MailSlurp managing organization. That organization can grant access to multiple linked MailSlurp environment accounts.

![MailSlurp environments for default, staging, QA, and test](/assets/guides/okta-environments-setup/mailslurp-environments-overview.png)

The access flow is:

1. Okta groups represent environment access, for example `MailSlurp staging`, `MailSlurp qa`, `MailSlurp test`, and `MailSlurp all environments`.
2. Okta SCIM pushes those groups and users into the MailSlurp organization.
3. MailSlurp maps each SCIM group to a MailSlurp organization role.
4. MailSlurp environment grants map each role to the matching environment.
5. The Okta OIDC tile sends users to the MailSlurp OIDC login URL with `returnTo=/environment-landing`.
6. MailSlurp signs the user in and routes them to the assigned environment. If the user can access more than one environment, MailSlurp shows the environment chooser.

Do not create a separate OIDC configuration in every MailSlurp environment unless each environment needs its own Okta app tile, assignment policy, administrator boundary, or issuer/client configuration. For most teams, one managing organization with role-restricted environment grants is easier to operate.

## Requirements

Before starting, prepare:

- A MailSlurp Enterprise organization.
- MailSlurp owner or admin access for the organization.
- Okta administrator access.
- The MailSlurp environments users should access.
- Okta groups for each environment access set.
- Stable Okta user email addresses.

For SCIM-managed users, keep the Okta user email, SCIM `userName`, and MailSlurp OIDC email claim aligned. MailSlurp links the first OIDC login to the SCIM-provisioned user by email, then uses the OIDC issuer and stable `sub` subject for future logins.

## Create MailSlurp environments and roles

In MailSlurp, open **Settings** > **Environments**.

Create one environment account for each isolated workspace:

- `staging`
- `qa`
- `test`

Then create MailSlurp organization roles for the access sets you want Okta to control:

- `Okta staging access`
- `Okta QA access`
- `Okta test access`
- `Okta all environments access`

Create environment access grants from the managing organization to each environment account. Restrict each grant to the matching MailSlurp role. Add the all-environments role to every grant when you want one administrator group that can enter all environments.

![MailSlurp environment grants restricted to Okta-managed roles](/assets/guides/okta-environments-setup/mailslurp-environment-grants.png)

## Enable SCIM in MailSlurp

Open **Settings** > **Organizations** > your organization > **SCIM provisioning**.

Enable:

- **Provisioning status**
- **Group role sync**

Copy the SCIM **Tenant URL** and create a bearer token. Store the token securely because Okta needs it when configuring provisioning.

After Okta pushes groups for the first time, return to MailSlurp and map each SCIM group to the matching MailSlurp role.

![MailSlurp SCIM group role sync settings with Okta groups mapped to MailSlurp roles](/assets/guides/okta-environments-setup/mailslurp-scim-groups-role-sync.png)

Example mappings:

| Okta group | MailSlurp role |
| --- | --- |
| `MailSlurp staging` | `Okta staging access` |
| `MailSlurp qa` | `Okta QA access` |
| `MailSlurp test` | `Okta test access` |
| `MailSlurp all environments` | `Okta all environments access` |

When group role sync is enabled, MailSlurp applies the mapped role to existing SCIM group members when you save the group-role mapping. Future Okta group membership changes add or remove the SCIM-owned role automatically.

## Create Okta groups and users

In Okta, create one group per environment access set:

- `MailSlurp staging`
- `MailSlurp qa`
- `MailSlurp test`
- `MailSlurp all environments`

![Okta groups for MailSlurp environment access](/assets/guides/okta-environments-setup/okta-groups.png)

Create or identify the users that should be provisioned into MailSlurp.

![Okta users for MailSlurp environment testing](/assets/guides/okta-environments-setup/okta-users.png)

Add users to the narrowest group that matches their access:

| User type | Okta group membership |
| --- | --- |
| Staging-only user | `MailSlurp staging` |
| QA-only user | `MailSlurp qa` |
| Test-only user | `MailSlurp test` |
| Administrator or release owner | `MailSlurp all environments` |

![Okta group membership for a MailSlurp environment group](/assets/guides/okta-environments-setup/okta-group-membership.png)

Users can belong to more than one group. MailSlurp combines the matching roles and environment grants. A user in only the staging group should be switched into staging after login. A user in the all-environments group should see the environment chooser when more than one linked environment is available.

## Create the Okta OIDC app

In Okta Admin Console, open **Applications** > **Applications** and create an app integration.

Use:

| Okta setting | Value |
| --- | --- |
| Sign-in method | `OIDC - OpenID Connect` |
| Application type | `Web Application` |
| Grant type | Authorization Code |
| Sign-in redirect URI | MailSlurp OIDC redirect URI |
| Login initiated by | Either Okta or App |
| Initiate login URI | MailSlurp OIDC login URL with `returnTo=/environment-landing` |
| Controlled access | Assign the MailSlurp Okta groups |

In MailSlurp, the redirect URI and login URL are shown on the organization **OIDC SSO** page.

![MailSlurp OIDC settings for Okta](/assets/guides/okta-environments-setup/mailslurp-oidc-settings.png)

Copy the Okta client ID and client secret into MailSlurp OIDC settings.

For the Okta issuer URL, use the authorization server that issues the ID token. A common Okta default authorization server issuer is:

```text
https://{yourOktaDomain}/oauth2/default
```

Set the Okta initiate-login URI to the MailSlurp environment landing login URL:

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

Use the MailSlurp organization slug for the managing organization where OIDC and SCIM are configured.

![Okta OIDC app general settings for MailSlurp](/assets/guides/okta-environments-setup/okta-oidc-general.png)

Assign the Okta groups to the OIDC app. These assignments control who can see and launch the MailSlurp tile.

![Okta OIDC app group assignments](/assets/guides/okta-environments-setup/okta-oidc-group-assignments.png)

Confirm the app assignment list shows users inherited through the MailSlurp groups. Each user who should launch the tile must be assigned to the OIDC app, not just the SCIM app.

![Okta OIDC app assignments showing users assigned through MailSlurp groups](/assets/guides/okta-environments-setup/okta-oidc-assignments-verified.png)

## Add an Okta authorization server access policy

If your Okta issuer URL uses a custom authorization server such as `https://{yourOktaDomain}/oauth2/default`, the authorization server also needs an access policy and rule. Okta app assignment controls who can launch the app, but the authorization server policy controls whether Okta will issue OIDC tokens for that app.

In Okta Admin Console, open **Security** > **API** > **Authorization Servers** and select the authorization server used in the MailSlurp issuer URL. For the default issuer, select **default**.

Open **Access Policies** and add a policy for MailSlurp:

| Okta setting | Recommended value |
| --- | --- |
| Name | `MailSlurp OIDC` |
| Assign to | The MailSlurp OIDC client |
| Grant type | Authorization Code |
| User is | Any user assigned the app, or assigned the app and in the MailSlurp groups |
| Scopes requested | Any scopes, or `openid`, `email`, and `profile` |
| Inline hook | None |

For a dedicated test tenant you can assign the policy to **All Clients** while validating the setup. In production, scope the policy to the MailSlurp OIDC client when possible.

Save the policy and add an active rule before testing login. Without this rule, assigned users can pass the password step and still receive an Okta 403 before MailSlurp receives the OIDC callback.

![Okta authorization server access policy with an active MailSlurp OIDC rule](/assets/guides/okta-environments-setup/okta-auth-server-policy-rule-verified.png)

## Add an Okta groups claim

MailSlurp needs a group, role, or custom claim to assign MailSlurp roles from Okta. For the group-based environment model, add a `groups` claim to the Okta authorization server used by the OIDC app.

Use a filter that emits only the MailSlurp groups, for example:

```text
^MailSlurp .*
```

Use a more specific prefix in production, such as `^MailSlurp production tenant .*`, if the Okta tenant has many groups.

![Okta authorization server groups claim for MailSlurp groups](/assets/guides/okta-environments-setup/okta-groups-claim.png)

## Save OIDC settings in MailSlurp

Back in MailSlurp, open **OIDC SSO** for the managing organization and enter:

| MailSlurp field | Okta value |
| --- | --- |
| Issuer URL | `https://{yourOktaDomain}/oauth2/default` |
| Client ID | Okta OIDC app client ID |
| Client secret | Okta OIDC app client secret |
| Scopes | `openid email profile` |
| Email claim | `email` |
| Subject claim | `sub` |
| Groups claim | `groups` |
| Token endpoint auth method | `client_secret_post` or the method required by your Okta app |
| Require verified email | Usually off unless Okta reliably emits `email_verified: true` |

Add MailSlurp OIDC role mappings for each Okta group claim value if you want OIDC login to update roles from ID token claims.

![MailSlurp role mappings for Okta groups](/assets/guides/okta-environments-setup/mailslurp-oidc-role-mappings.png)

If you use SCIM group role sync, the same roles are also maintained by SCIM. Keeping OIDC role mappings in place is useful for sign-in-time role refresh, while SCIM remains the source for user lifecycle and group membership.

## Create the Okta SCIM provisioning app

Create a second Okta application for SCIM provisioning. Use an Okta app integration that supports SCIM 2.0 provisioning with bearer token authentication, such as **SCIM 2.0 Test App (OAuth Bearer Token)** for a custom setup.

Because this application is only for provisioning, hide it from users. The visible user tile should be the OIDC app.

Configure provisioning with the values from MailSlurp:

| Okta SCIM setting | MailSlurp value |
| --- | --- |
| Base URL or Tenant URL | MailSlurp SCIM Tenant URL |
| API token or bearer token | MailSlurp SCIM bearer token |
| Unique user field | `userName` |
| Supported actions | Create users, update user attributes, deactivate users, push groups |

Test the SCIM credentials in Okta before saving.

![Okta SCIM credential test succeeds against MailSlurp](/assets/guides/okta-environments-setup/okta-scim-connection-success.png)

After the API connection is saved, enable **Create Users**, **Update User Attributes**, and **Deactivate Users** under **Provisioning** > **To App**. Leave password sync disabled when users authenticate through OIDC.

![Okta SCIM To App provisioning actions enabled](/assets/guides/okta-environments-setup/okta-scim-to-app-settings.png)

Assign the same Okta groups to the SCIM app that you assigned to the OIDC app.

![Okta SCIM app group assignments](/assets/guides/okta-environments-setup/okta-scim-group-assignments.png)

## Push Okta groups to MailSlurp

Open the SCIM app **Push Groups** tab. Use **Push Groups** > **Find groups by name**, select each MailSlurp access group, and keep **Push group memberships immediately** enabled.

When Okta cannot find an existing app-side group, choose **Create Group**. Okta creates the SCIM group in MailSlurp and pushes membership.

![Okta pushed groups for MailSlurp SCIM](/assets/guides/okta-environments-setup/okta-scim-push-groups.png)

After pushing groups, confirm in MailSlurp that:

- The users exist in the organization.
- The SCIM groups exist.
- Group member counts match Okta.
- Each group maps to the intended MailSlurp role.
- Each user has the role that matches their Okta group.

## Test the Okta tile

Open the Okta dashboard as an assigned user and click the MailSlurp OIDC tile.

![Okta My Apps dashboard showing the MailSlurp OIDC tile](/assets/guides/okta-environments-setup/okta-user-dashboard-tile-verified.png)

Expected results:

| Test user | Expected MailSlurp result |
| --- | --- |
| Staging-only user | Signs in and switches into `staging` |
| QA-only user | Signs in and switches into `qa` |
| Test-only user | Signs in and switches into `test` |
| All-environments user | Signs in and sees the environment chooser |

If the user has exactly one non-default linked environment, MailSlurp switches to that environment automatically. If the user can access multiple environments, MailSlurp shows the chooser so the user can pick the correct environment.

After a successful single-environment login, MailSlurp shows a success message and the target environment name in the dashboard.

![MailSlurp dashboard after an Okta staging-only user is switched to staging](/assets/guides/okta-environments-setup/mailslurp-staging-user-result.png)

Confirm the same single-environment user cannot switch into other environments. Open **Settings** > **Environments** or the environment switcher as that user. Only the allowed environment and the default account context should be available.

![MailSlurp environment switcher for a staging-only Okta user](/assets/guides/okta-environments-setup/mailslurp-staging-user-qa-rejected.png)

After a successful all-environments login from the Okta tile, MailSlurp shows the environment chooser with each environment the user's roles can access.

![MailSlurp environment chooser after launching the Okta tile](/assets/guides/okta-environments-setup/mailslurp-okta-dashboard-tile-click-result.png)

Selecting another environment switches the MailSlurp account context and returns the user to the dashboard.

![MailSlurp dashboard after an Okta tile user switches to staging](/assets/guides/okta-environments-setup/mailslurp-okta-dashboard-tile-switch-staging.png)

Okta may ask a new test user to enroll required security methods before showing the dashboard. Complete the Okta enrollment or adjust the Okta authenticator enrollment policy for the test group, then retry the tile launch. This prompt happens before OIDC reaches MailSlurp.

## Troubleshooting

**The Okta tile is not visible**

Confirm the user or one of their groups is assigned to the OIDC application. The SCIM app does not need to be visible to users.

**Okta shows 403 after the password step**

Confirm the OIDC app assignment first. If the assignment is correct and your issuer is an Okta custom authorization server such as `/oauth2/default`, check **Security** > **API** > **Authorization Servers** > your authorization server > **Access Policies**. Add an active policy rule that allows the MailSlurp OIDC client to use the Authorization Code grant.

![Okta 403 shown when the authorization server has no access policy rule for the OIDC app](/assets/guides/okta-environments-setup/okta-missing-auth-server-policy-403.png)

**Okta asks the user to set up security methods**

Complete the Okta Verify or authenticator enrollment required by your Okta policy, or adjust the test policy for the assigned Okta group. MailSlurp does not receive an OIDC callback until Okta completes this step.

**Okta says the user is not assigned**

Assign the user or their group to the OIDC app. Assigning only the SCIM app is not enough for tile launch or OIDC sign-in.

**MailSlurp signs the user in but shows no environment**

Check the user's MailSlurp roles and the environment access grants. The user must have a role allowed by the target environment grant.

**SCIM users appear but roles do not update**

Confirm group push is enabled for the Okta groups and that MailSlurp SCIM group role sync is enabled. Each pushed SCIM group must be mapped to a MailSlurp role.

**OIDC role mappings do not apply**

Check the Okta ID token and confirm it contains the configured groups claim. The MailSlurp role mapping must match the emitted claim name and value exactly.

**The wrong MailSlurp user is linked**

Make sure the MailSlurp OIDC email claim matches the same email value that SCIM provisions for the user. Keep the subject claim set to Okta `sub`. If the Okta app was recreated or the subject claim changed intentionally, ask a MailSlurp organization admin or MailSlurp support to reset the affected user's OIDC link before retrying.

## Related docs

- [MailSlurp OIDC setup](/docs/oidc/)
- [MailSlurp organizations](/guides/organizations/)
- [MailSlurp environments](/docs/environments/)
- [SCIM provisioning](/docs/scim/)
- [Okta SAML SSO setup](/guides/sso/saml-okta-setup/)