Skip to main content
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

1

Create a SAML app integration in Okta

  1. Log in to the Okta Admin Console
  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
2

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.
3

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"
    }
  }'
FieldDescription
nameA human-readable label for the connection.
enabledSet to false while you finish IdP setup; flip to true at the end.
idp_metadata_urlOkta’s SAML metadata URL. Provide exactly one IdP source (idp_metadata_url, idp_metadata_xml, or an explicit idp block).
behavior.jit_provisioningWhen true, creates a user on first SSO login.
behavior.allow_email_account_mergeWhen true, links to an existing user with the same verified email.
behavior.email_domain_allowlistDomains this connection covers; required for email-resolved login and enforce_login.
behavior.default_redirect_uriRedirect 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"
    }
  }
}
4

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
The values must match exactly — no trailing slash, and https only.
5

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