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

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