Okta

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 account with admin access
A verified custom domain 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

Create a SAML app integration in Okta

Log in to the Okta Admin Console
Navigate to Applications > Applications
Click Create App Integration
Select SAML 2.0 as the sign-in method, then click Next
Enter a name (e.g. “Prelude Auth”) and click Next
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
Set Name ID format to EmailAddress and Application username to Email
Click Next, then Finish

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.

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.

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:

{
  "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"
    }
  }
}

Paste the SP URLs back into Okta

Return to the Okta application’s General tab and Edit the SAML settings:

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

The values must match exactly — no trailing slash, and https only.

Assign users and enable the connection

On the Okta Assignments tab, assign the people or groups who should have access.
Enable the Prelude connection:

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 }'

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):

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

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 guide, or require this domain to use SSO with Enforce SSO login.

Documentation

API Reference

Prerequisites

Configure Okta SAML

Rotating the IdP certificate

Delete the connection

What’s next?

​Prerequisites

​Configure Okta SAML

​Rotating the IdP certificate

​Delete the connection

​What’s next?

Prerequisites

Configure Okta SAML

Rotating the IdP certificate

Delete the connection

What’s next?