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

# Okta

> Configure Okta as an identity provider for Modelcode using SAML 2.0 or OpenID Connect

This guide walks through configuring **Okta** as an identity provider for Modelcode SSO. Okta supports both SAML 2.0 and OpenID Connect — choose the protocol that best fits your setup.

<Tip>
  **We recommend SAML 2.0 for Okta.** It's typically quicker to configure and doesn't require managing authorization server access policies.
</Tip>

## Prerequisites

* Admin access to your Modelcode organization, **signed in with email and password** — the SSO settings page is not available to users who signed in with a social provider (GitHub, GitLab, Microsoft)
* An Okta admin account with privileges to create and edit applications and policies

***

## SAML 2.0

### Step 1: Get Modelcode's Service Provider Details

Before creating the Okta application, get the SP details from Modelcode:

1. In Modelcode, navigate to **Single Sign-On** in the sidebar
2. Click **Setup SSO** and select **SAML 2.0**
3. Copy the **ACS URL** and **SP Entity ID** displayed on the form

### Step 2: Create a SAML Application in Okta

1. In the Okta Admin Console, go to **Applications → Applications**
2. Click **Create App Integration**
3. Select **SAML 2.0** and click **Next**

#### General Settings

| Field        | Value                                 |
| ------------ | ------------------------------------- |
| **App name** | `Modelcode` (or any descriptive name) |
| **App logo** | Optional                              |

Click **Next**.

#### SAML Settings

| Field                                              | Value                                     |
| -------------------------------------------------- | ----------------------------------------- |
| **Single sign-on URL**                             | Paste the **ACS URL** from Modelcode      |
| **Use this for Recipient URL and Destination URL** | Yes (checked)                             |
| **Audience URI (SP Entity ID)**                    | Paste the **SP Entity ID** from Modelcode |
| **Name ID format**                                 | `EmailAddress`                            |
| **Application username**                           | `Email`                                   |

Leave other fields at their defaults and click **Next**.

#### Feedback

Select **I'm an Okta customer adding an internal app** and click **Finish**.

#### Attribute Statements

After the application is created, go to the **Sign On** tab and add the following attribute statements so Modelcode receives the user's profile information in the SAML assertion:

| Name        | Value                    |
| ----------- | ------------------------ |
| `email`     | `user.profile.email`     |
| `firstName` | `user.profile.firstName` |
| `lastName`  | `user.profile.lastName`  |

### Step 3: Get Okta's Identity Provider Details

After creating the application:

1. Go to the **Sign On** tab of your new Okta application
2. Find the **Metadata URL** — this is typically labeled "Metadata URL" or available via a link like "Identity Provider metadata"
3. Copy the **Metadata URL**

Alternatively, if you prefer manual configuration, find these values on the Sign On tab:

| Okta Field                               | Modelcode Field                                          |
| ---------------------------------------- | -------------------------------------------------------- |
| **Sign on URL** or **SAML 2.0 Endpoint** | SSO URL                                                  |
| **Issuer**                               | Entity ID                                                |
| **Signing Certificate**                  | Signing Certificate (download and paste the PEM content) |

### Step 4: Configure SAML in Modelcode

1. In Modelcode, navigate to **Single Sign-On** in the sidebar
2. Click **Setup SSO** (or **Edit** if updating)
3. Select **SAML 2.0** as the protocol
4. Choose your configuration method:

<Tabs>
  <Tab title="Metadata URL (Recommended)">
    Paste the **Metadata URL** from Okta. Modelcode automatically extracts all required IdP details.
  </Tab>

  <Tab title="Manual Configuration">
    Click **Configure manually** and enter:

    | Field                   | Value                                       |
    | ----------------------- | ------------------------------------------- |
    | **SSO URL**             | The Sign on URL from Okta                   |
    | **Entity ID**           | The Issuer from Okta                        |
    | **Signing Certificate** | The X.509 certificate content in PEM format |
  </Tab>
</Tabs>

5. Click **Verify & Save**

### Step 5: Assign Users and Share the Portal Link

1. In Okta, go to your Modelcode application's **Assignments** tab
2. Assign individual users or groups
3. In Modelcode, go to the [Members](https://morph.modelcode.ai/user-roles?tab=users) page and invite each user who needs SSO access — users cannot sign in via SSO until they have been invited
4. Copy the **Portal Link** from the SSO settings page and share it with your team:

```
https://morph.modelcode.ai/sso-portal/<your-organization-id>
```

***

## OpenID Connect

### Step 1: Create a Web Application in Okta

1. In the Okta Admin Console, go to **Applications → Applications**
2. Click **Create App Integration**
3. Select **OIDC - OpenID Connect** as the sign-in method
4. Select **Web Application** as the application type
5. Click **Next**

#### General Settings

| Field                      | Value                                                     |
| -------------------------- | --------------------------------------------------------- |
| **App integration name**   | `Modelcode` (or any descriptive name)                     |
| **Grant type**             | Authorization Code (default)                              |
| **Sign-in redirect URIs**  | The **Callback URL** from the Modelcode SSO settings page |
| **Sign-out redirect URIs** | Optional                                                  |

6. Click **Save**

After saving, Okta displays the **Client ID** and **Client Secret** on the application's **General** tab. Copy both values — you'll need them in the next step.

<Warning>
  Copy the Client Secret immediately. Depending on your Okta configuration, the secret may only be visible once.
</Warning>

### Step 2: Find Your Issuer URL

The Issuer URL tells Modelcode where to find Okta's OIDC discovery document.

1. In the Okta Admin Console, navigate to **Security → API** in the left sidebar
2. Click on the **Authorization Servers** tab
3. Click on your authorization server (usually named **default**)
4. Under the **Settings** tab, find the **Issuer** field
5. Copy the Issuer URL

Your Issuer URL will look like:

```
https://<your-domain>.okta.com/oauth2/default
```

### Step 3: Add an Access Policy

Your Okta authorization server must have an access policy that allows your Modelcode application to request tokens. Without a policy (or a matching rule), Okta rejects the login attempt.

1. In the Okta Admin Console, navigate to **Security → API**
2. Click on your authorization server (e.g., **default**)
3. Select the **Access Policies** tab
4. If no policy exists, click **Add Policy**:
   * **Name**: `Modelcode SSO` (or any descriptive name)
   * **Assign to**: **All clients**, or select **The following clients** and enter your Modelcode application name
   * Click **Create Policy**
5. Inside the policy, click **Add Rule**:
   * **Name**: `Allow login` (or any descriptive name)
   * **Grant type**: Ensure **Authorization Code** is selected
   * Leave other fields at their defaults
   * Click **Create Rule**

<Note>
  If your authorization server already has a policy that covers all clients or includes your Modelcode application, you can skip this step.
</Note>

### Step 4: Configure OIDC in Modelcode

1. In Modelcode, navigate to **Single Sign-On** in the sidebar
2. Click **Setup SSO** (or **Edit** if updating)
3. Select **OpenID Connect** as the protocol
4. Enter the following:

| Field             | Value                                                                            |
| ----------------- | -------------------------------------------------------------------------------- |
| **Issuer URL**    | The Issuer URL from Okta (e.g., `https://<your-domain>.okta.com/oauth2/default`) |
| **Client ID**     | The Client ID from your Okta application                                         |
| **Client Secret** | The Client Secret from your Okta application                                     |
| **Scopes**        | `openid email profile` (default)                                                 |

5. Click **Verify & Save**

Modelcode validates the connection by fetching the OIDC discovery document and optionally verifying the client credentials.

### Step 5: Assign Users and Share the Portal Link

1. In Okta, go to your Modelcode application's **Assignments** tab
2. Assign individual users or groups
3. In Modelcode, go to the [Members](https://morph.modelcode.ai/user-roles?tab=users) page and invite each user who needs SSO access — users cannot sign in via SSO until they have been invited
4. Copy the **Portal Link** from the SSO settings page and share it with your team:

```
https://morph.modelcode.ai/sso-portal/<your-organization-id>
```

***

## Troubleshooting

### SAML: "Verification failed" when saving the Metadata URL

* Confirm the Metadata URL uses HTTPS and is publicly reachable
* Try accessing the Metadata URL in your browser to verify it returns XML
* If the URL is behind a firewall, use manual configuration instead

### SAML: Users see a SAML error after authenticating

* Verify the **Single sign-on URL** in Okta matches the ACS URL from Modelcode exactly
* Confirm the **Audience URI** in Okta matches the SP Entity ID from Modelcode exactly
* Check that **Name ID format** is set to `EmailAddress`
* Ensure the user is assigned to the application in Okta

### SAML: Certificate rotation

When Okta rotates signing certificates:

* If using **Metadata URL**: Modelcode fetches the latest metadata on each authentication attempt, so certificate rotation is handled automatically
* If using **manual configuration**: Update the signing certificate in the Modelcode SSO settings after Okta rotates

### OIDC: "Verification failed" when saving

* Confirm the **Issuer URL** matches the Issuer field from your Okta authorization server
* Verify the URL uses HTTPS and is publicly reachable
* Check that the authorization server is active in Okta

### OIDC: Users see an error after authenticating

* Verify the **Sign-in redirect URI** in Okta matches the Callback URL from Modelcode exactly
* Confirm the application type is **Web Application** (not SPA or Native)
* Check that the **Grant type** includes Authorization Code
* Ensure the authorization server has an access policy that covers your application
* Ensure the user is assigned to the application in Okta

### Users authenticate but are not recognized in Modelcode

* The user's email in Okta must match their Modelcode account email
* Ensure users are accessing Modelcode through the **Portal Link**, not the standard login page
* If the user hasn't been invited to the organization yet, the admin must send an invitation first