# Set up Okta SSO

> Connect Okta to Model Monster, configure access and role behavior safely, and verify that single sign-on works.

Canonical URL: http://modelmonster.ai/docs/organization-and-administration/set-up-okta-sso/

## Article Metadata

- Reading time: 9 min

Connect your organization's Okta tenant to Model Monster and confirm that an assigned user can sign in successfully with single sign-on (SSO).

## Before you begin

Prepare these items before changing either product:

- Access to **Settings → General → Single sign-on → Configure SSO** in your Model Monster organization. If this option is unavailable, contact Model Monster support.
- Permission to create and assign applications in your Okta organization.
- A dedicated Okta test user. Its email address should use the domain you intend to allow in Model Monster.
- A separate browser session where a Model Monster Organization Administrator remains signed in.

For the first setup, use the Okta organization issuer, **Model Monster** role assignment, and the **Member** default role. Start sign-in from Model Monster. Add sign-in from the Okta dashboard or roles from an **Okta ID token claim** after the basic flow works.

> **Warning:** Keep the separate administrator session open, leave SSO disabled, and leave email-domain enforcement off until a real test user has signed in with the expected role.

## Create the Okta application

Create an interactive OIDC application for Model Monster:

1. In the Okta Admin Console, open **Applications and Resources → Applications**.
2. Select **Create App Integration**.
3. Under **Sign-in method**, select **OIDC - OpenID Connect**.
4. Under **Application type**, select **Web Application**, then select **Next**.

5. Enter **Model Monster** for **App integration name**.
6. Leave **Require Demonstrating Proof of Possession (DPoP) header in token requests** off.
7. Under **Grant type**, keep **Authorization Code** selected.
8. Leave **Client Credentials**, under **Client acting on behalf of itself**, unchecked.
9. Retain Okta's temporary localhost **Sign-in redirect URI** for this pass. You will replace this later. Leave **Refresh Token**, the advanced grants, **Sign-out redirect URIs**, and **Trusted Origins** unchanged.
10. Under **Assignments**, select **Skip group assignment for now**. You will assign the test user after completing the connection addresses.
11. Select **Save**.

> **Tip:** Do not use **Create your first Okta app** on the Integrator home page. That starts an Okta Integration Network publishing workflow.

## Copy the Okta credentials

After Okta creates the application:

1. Find **Client Credentials**.
2. Copy the **Client ID** and one active **Client secret** to an approved secure temporary location. You will enter both in Model Monster.

> **Note:** Model Monster masks the secret after saving. On later edits, leave **Client secret** blank to preserve it; enter a value to replace it.

## Save Model Monster SSO while it is disabled

The first disabled save creates stable connection addresses without changing sign-in.

1. In Model Monster, open **Settings → General → Single sign-on → Configure SSO**.
2. Keep the Okta sign-in control **DISABLED**.
3. Keep **Role assignment at sign-in** set to **Model Monster**. **Default role** then applies only to new memberships; later Okta sign-ins preserve existing roles.
4. Enter **Okta** for **Provider name** and keep **Default role** set to **Member** for the first test.

5. For **Issuer URL**, enter the exact HTTPS **Issuer** for your Okta organization authorization server, normally `https://{yourOktaDomain}`. Find your Okta domain in the Admin Console address, administrator menu, or welcome email. Do not use an Admin Console `-admin` host, **Metadata URI**, or a `.well-known/openid-configuration` URL.
6. Enter the **Client ID** and **Client secret** copied from Okta.
7. Under **Allowed email domains**, replace any prefilled value with the portion after `@` in the test user's address.
8. Keep **Require matching email domains to sign in with Okta only** off.
9. Select **Save** while the Okta sign-in control remains **DISABLED**.

> **Warning:** A fresh form may seed **Allowed email domains** with the organization slug. If `example-org` appears, replace it with the real email suffix—for `person@example.com`, enter `example.com`. A non-domain slug prevents saving.

After the disabled save, find **Connection** and copy both generated values:

- **Initiate Login URI** ends in `/login/` and starts sign-in, including from an Okta dashboard tile.
- **Sign-in redirect URI** ends in `/login/callback/` and receives Okta's authentication response.

![Model Monster Connection section showing the distinct Initiate Login URI and Sign-in redirect URI with identifiers redacted](/media/original_images/04-model-monster-generated-connection-uris.png)

Model Monster may warn that Okta does not have the sign-in redirect URI configured. Finish the next section, then compare the exact value in both products.

## Finish the Okta configuration

Return to Okta to replace the temporary address and assign your test identity.

1. Open **Applications and Resources → Applications → Model Monster → General Settings → Edit**.
2. Under **Sign-in redirect URIs**, remove the temporary localhost value and paste Model Monster's exact **Sign-in redirect URI**, including its `/login/callback/` ending.
3. Set **Login initiated by** to **App Only** for the recommended Model Monster-initiated path. You do not need to configure **Initiate login URI** for this path.
4. Save the General Settings.

5. Open the application's **Assignments** tab.
6. Select **Assign → Assign to People** and assign the dedicated test user. For a managed rollout, you can instead select **Assign to Groups** and choose a group that contains the test user.
7. Confirm that the user is assigned directly or through the selected group.

## Check a custom authorization server only if you use one

If you entered the organization issuer, `https://{yourOktaDomain}`, skip this section and continue to the smoke test. The organization issuer is the recommended path for basic sign-in and does not use authorization-server Access Policies.

![A two-path issuer decision diagram showing the organization issuer continuing directly to testing and custom issuers continuing through Access Policies](/media/original_images/05-okta-issuer-decision.png)

An issuer ending in `/oauth2/default` or `/oauth2/{authorizationServerId}` selects a custom authorization server. Custom servers can use different claims and access policies from the organization server.

For a custom authorization server:

1. In Okta, open **Security → API → Authorization Servers** and select **default** or the custom server you chose.
2. On **Settings**, confirm that **Issuer** exactly matches the value entered in Model Monster. Copy **Issuer**, not **Metadata URI**.
3. Open **Access Policies**.
4. Confirm that an active policy and rule apply to the Model Monster client and its Authorization Code request. A newly created default custom server may not include a policy.

The sign-in request uses the reserved `openid`, `profile`, and `email` scopes. Do not create duplicate custom scopes with those names.

## Enable SSO and test a real sign-in

Complete a real round trip before expanding access or requiring Okta.

1. Return to the Model Monster Okta SSO page.
2. Enable Okta sign-in and save. Keep **Require matching email domains to sign in with Okta only** off.
3. For an isolated test, open a private or incognito browser window and start at Model Monster sign-in.
4. Enter the assigned test user's email address. Select **Continue with Okta** when it appears.
5. Complete Okta authentication and confirm that the browser returns to Model Monster.
6. Verify that the expected organization is active, the test user appears under **Settings → Members**, and their access matches the expected **Member** role for the basic path.

> **Note:** Model Monster's configuration validation checks selected connection details. A real end-to-end sign-in verifies the user's assignment, applicable policies, client secret, email claims, organization access, and role together.

Keep the separate administrator session open until each sign-in path you plan to use produces the correct organization and role.

## Add optional sign-in behavior after the basic path works

Add each option after the basic test succeeds. Retest after each change to isolate failures.

### Start sign-in from an Okta dashboard tile

Use this option only when users should launch Model Monster from the Okta dashboard.

1. Copy the generated Model Monster **Initiate Login URI** ending in `/login/`.
2. In the Okta application's General Settings, change **Login initiated by** to **Either Okta or App**.
3. Paste the generated value into **Initiate login URI**. Choose the option that redirects to the application to begin sign-in, not **Send ID Token directly to app (Okta Simplified)**.
4. Save, launch the Model Monster tile with the assigned test user, and verify the same organization and role.

Never put the **Sign-in redirect URI** in the initiation field. The two addresses have different jobs.

### Assign roles from an Okta token claim

Choose **Okta ID token claim** only when your identity team intends Okta to control roles at every successful sign-in. This mode can change an existing member's role.

Configure your chosen custom authorization server with these requirements:

- **Location:** Add one top-level ID-token claim named `mm_role`.
- **Accepted values:** Return the lowercase string `admin` or `member`.
- **Rejected shapes:** Differently cased or whitespace-padded text, group lists, nested values, and claims delivered only as user information block sign-in without changing the stored role.

Okta expressions depend on how your organization models users and groups, so there is no universal expression to copy. Design the mapping with your identity team, then test both supported outcomes with users who are not administrators. In Model Monster, change **Role assignment at sign-in** to **Okta ID token claim** only after those tests are ready.

> **Warning:** A valid `member` claim can demote an existing administrator—including the last administrator—the next time that person signs in. Switching authority does not bulk-update users or restore earlier roles. Verify the claim with a test user who is not an administrator before any administrator uses it.

### Require matching domains to use Okta

Turn on **Require matching email domains to sign in with Okta only** only after every required path works. Turning this on removes email-code fallback for matching users.

Test again with an ordinary member before expanding assignment to larger groups. Keep the separate administrator session until you have confirmed the enforced flow.

## Troubleshooting

Use this table to diagnose common setup and sign-in problems.

| Symptom | What to check |
|---|---|
| **Allowed email domains** reports a value such as `example-org` | Remove the organization slug and add the real suffix after `@`, such as `example.com`. The error does not require the email domain to match the slug. |
| **Client Credentials** was selected under **Grant type** | Edit the Okta application, leave that grant unchecked, and use **Authorization Code**. Then confirm **Client authentication → Client secret** under the saved application's **Client Credentials** section. |
| You cannot find the Client ID or secret | Save the Okta application first, then open **General → Client Credentials**. Generate an active secret there if needed. |
| The issuer is rejected or discovery fails | Enter **Issuer**, not **Metadata URI** or a `.well-known` address. Check the HTTPS tenant domain and exact custom-server path. Do not switch issuer types as a formatting workaround. |
| The Okta tile says sign-in started at the wrong address | Put Model Monster's **Initiate Login URI** ending in `/login/` in Okta's initiation field. Keep the `/login/callback/` address only under **Sign-in redirect URIs**. |
| Okta says the user is not assigned | Open **Assignments** and assign the person or a group containing them. Application activation alone does not grant access. |
| Okta policy blocks sign-in | Review **Security → Authentication Policies → App sign-in**. If you selected a custom issuer, separately confirm an active matching **Access Policy** and rule. Organization-issuer users do not add an Access Policy. |
| A generic redirect warning appears | Compare the exact post-save callback in both products, then run the private-window test. The warning by itself does not prove success or failure. |
| Configuration looks correct, but callback sign-in fails | Confirm that Model Monster has the current active client secret. Replace it from Okta, save, and test again; configuration validation does not complete a real user token exchange. |
| Okta role authority rejects sign-in | Confirm that `mm_role` is a top-level ID-token claim with exactly `admin` or `member`. It cannot be a group list or a user-information-only field. |
| You lose access after enforcement or a role change | If another organization administrator still has access, ask them to disable or correct the configuration. Otherwise, contact Model Monster support. |

## Continue administering access

Use [Invite and manage organization members](/docs/organization-and-administration/inviting-and-managing-organization-members/) to manage people beyond SSO provisioning. Review Roles & permissions before changing default or claim-managed roles, and use Organization audit log to review later SSO configuration and access events.