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

# Okta

> Configure an Okta SAML application for your Auth application.

This guide walks you through connecting an Okta SAML application to Prelude Auth. Okta is the Identity Provider (IdP); Prelude Auth is the Service Provider (SP).

## Prerequisites

* An [Okta](https://www.okta.com/) account with admin access
* A verified [custom domain](/session/documentation/domain-names) on your Auth application

Because the SP endpoints embed the generated connection ID, the flow is: create the Okta app, create the Prelude connection from Okta's metadata, then paste the generated SP values back into Okta.

## Configure Okta SAML

<Steps>
  <Step title="Create a SAML app integration in Okta">
    1. Log in to the [Okta Admin Console](https://login.okta.com/)
    2. Navigate to **Applications** > **Applications**
    3. Click **Create App Integration**
    4. Select **SAML 2.0** as the sign-in method, then click **Next**
    5. Enter a name (e.g. "Prelude Auth") and click **Next**
    6. On the **Configure SAML** screen, enter temporary placeholders for now — you will replace them in a later step:
       * **Single sign-on URL**: `https://example.com/acs`
       * **Audience URI (SP Entity ID)**: `https://example.com`
    7. Set **Name ID format** to `EmailAddress` and **Application username** to `Email`
    8. Click **Next**, then **Finish**
  </Step>

  <Step title="Copy Okta's metadata URL">
    On the application's **Sign On** tab, find the **Metadata URL** (under *SAML Signing Certificates* / *More details*). It looks like:

    ```
    https://${YOUR_OKTA_DOMAIN}/app/${APP_ID}/sso/saml/metadata
    ```

    You will pass this URL to Prelude in the next step so the IdP Entity ID, SSO URL, and signing certificate are imported automatically.
  </Step>

  <Step title="Create the SAML connection in Prelude">
    Create the connection from Okta's metadata. Start it **disabled** — you will enable it once the SP URLs are wired back into Okta.

    ```bash theme={null}
    curl -X POST https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/okta \
      -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Acme Okta",
        "enabled": false,
        "idp_metadata_url": "https://${YOUR_OKTA_DOMAIN}/app/${APP_ID}/sso/saml/metadata",
        "behavior": {
          "jit_provisioning": true,
          "allow_email_account_merge": true,
          "email_domain_allowlist": ["acme.com"],
          "enforce_login": false,
          "default_redirect_uri": "https://app.acme.com/callback"
        }
      }'
    ```

    | Field                                | Description                                                                                                                    |
    | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
    | `name`                               | A human-readable label for the connection.                                                                                     |
    | `enabled`                            | Set to `false` while you finish IdP setup; flip to `true` at the end.                                                          |
    | `idp_metadata_url`                   | Okta's SAML metadata URL. Provide exactly one IdP source (`idp_metadata_url`, `idp_metadata_xml`, or an explicit `idp` block). |
    | `behavior.jit_provisioning`          | When `true`, creates a user on first SSO login.                                                                                |
    | `behavior.allow_email_account_merge` | When `true`, links to an existing user with the same verified email.                                                           |
    | `behavior.email_domain_allowlist`    | Domains this connection covers; required for email-resolved login and `enforce_login`.                                         |
    | `behavior.default_redirect_uri`      | Redirect URI for IdP-initiated logins and when `redirect_uri` is omitted.                                                      |

    The response contains an `sp` block with the values you need next:

    ```json theme={null}
    {
      "connection": {
        "id": "samlc_01jqebhswje1ka1z7ahr9rfsgt",
        "provider_id": "okta",
        "sp": {
          "entity_id": "https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt",
          "acs_url": "https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt/acs",
          "metadata_url": "https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt/metadata"
        }
      }
    }
    ```
  </Step>

  <Step title="Paste the SP URLs back into Okta">
    Return to the Okta application's **General** tab and **Edit** the SAML settings:

    1. Set **Single sign-on URL** to the `sp.acs_url` from the response
    2. Set **Audience URI (SP Entity ID)** to the `sp.entity_id` from the response
    3. Click **Save**

    <Note>
      The values must match exactly — no trailing slash, and `https` only.
    </Note>
  </Step>

  <Step title="Assign users and enable the connection">
    1. On the Okta **Assignments** tab, assign the people or groups who should have access.
    2. Enable the Prelude connection:

    ```bash theme={null}
    curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt \
      -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{ "enabled": true }'
    ```
  </Step>
</Steps>

## Rotating the IdP certificate

When Okta rotates its signing certificate, update the connection's IdP block (the Entity ID is immutable — to change it, delete and recreate the connection):

```bash theme={null}
curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/okta/${CONNECTION_ID} \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "idp": {
      "sso_url": "https://acme.okta.com/app/abc/exk.../sso/saml",
      "certificates": ["-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"]
    }
  }'
```

## Delete the connection

```bash theme={null}
curl -X DELETE https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/okta/${CONNECTION_ID} \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}"
```

Existing `saml:<connection_id>` user identifiers are retained so historical sessions stay auditable.

## What's next?

Now that the Okta connection is configured, integrate the frontend using the [Web Integration](/session/documentation/frontend-sdks/web/saml) guide, or require this domain to use SSO with [Enforce SSO login](/session/documentation/integration-guide/saml/enforce).