Skip to main content
This guide walks you through configuring Okta as a social login provider for your application.

​
Prerequisites

  • An Okta account with admin access
  • Your Okta Client ID, Client Secret, and Issuer URL

​
Configure Okta OAuth

1

Create an application on Okta

  1. Log in to the Okta Admin Console
  2. Navigate to Applications > Applications
  3. Click Create App Integration
  4. Select OIDC - OpenID Connect as the sign-in method
  5. Select Web Application as the application type
  6. Click Next
  7. Enter a name (e.g. “Prelude Session”)
  8. Under Sign-in redirect URIs, replace the default value with:
https://${YOUR_CUSTOM_DOMAIN}/v1/session/login/oauth/okta/callback
Replace ${YOUR_CUSTOM_DOMAIN} with your custom domain (e.g. session.yourapp.com).
  1. Click Save
  2. Copy the Client ID and Client Secret from the application settings page
The redirect URI must match exactly. Make sure there is no trailing slash and that you are using https.
2

Note your Issuer URL

Your Issuer URL is found in Security > API > Authorization Servers in the Okta Admin Console (e.g. https://dev-123456.okta.com/oauth2/default). You will need it in the next step.
3

Create the Okta OAuth configuration

curl -X POST https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/oauth/okta \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-okta-client-id",
    "client_secret": "your-okta-client-secret",
    "enabled": true,
    "options": {
      "use_email_as_identifier": true,
      "allow_email_account_merge": true
    },
    "okta": {
      "issuer_url": "https://dev-123456.okta.com/oauth2/default"
    }
  }'
FieldDescription
client_idYour Okta OAuth client ID.
client_secretYour Okta OAuth client secret.
enabledSet to true to enable Okta login.
okta.issuer_urlYour Okta authorization server Issuer URL (e.g. https://dev-123456.okta.com/oauth2/default).
options.use_email_as_identifierWhen true, the user’s Okta email is stored as an email identifier.
options.allow_email_account_mergeWhen true, if a user with the same email already exists, the Okta account is linked to the existing user.

​
Update the configuration

To update an existing Okta OAuth configuration: 
curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/oauth/okta \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-new-okta-client-id",
    "client_secret": "your-new-okta-client-secret",
    "enabled": true,
    "options": {
      "use_email_as_identifier": true,
      "allow_email_account_merge": true
    },
    "okta": {
      "issuer_url": "https://dev-123456.okta.com/oauth2/default"
    }
  }'

​
Delete the configuration

To remove Okta OAuth from your application: 
curl -X DELETE https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/oauth/okta \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}"

​
What’s next?

Now that Okta OAuth is configured on your backend, integrate the frontend using the Web Integration guide.