This guide explains how to integrate Okta with your platform using OpenID Connect (OIDC) for Single Sign-On (SSO). It includes detailed instructions for obtaining the required configuration data from Okta.

​
Prerequisites

Before starting, ensure you have:
  1. An Okta Admin Account with the ability to create and manage applications.
  2. Access to your Okta Organization Domain (e.g., dev-123456.okta.com).

​
Steps for Customers to Obtain Configuration Data

Follow these steps to retrieve the necessary information from Okta.

​
Step 1: Create an Application in Okta

  1. Log in to the Okta Admin Console.
  2. Navigate to Applications > Applications in the left-hand menu.
  3. Click Create App Integration.
  4. Select OIDC - OpenID Connect as the Sign-in method and choose Web Application.
  5. Click Next.

​
Step 2: Configure the Application

  1. Fill out the following details:
    • App Integration Name: Enter a name for your app (e.g., Roe-AI SSO Integration App).
    • Sign-in Redirect URIs: Add Roe-AI platform’s SSO callback URL https://app.roe-ai.com/sso/callback.
    • Assignments: Choose who can access this application (e.g., “Everyone”).
  2. Click Save.

​
Step 3: Retrieve Client Credentials

  1. After saving, you’ll be redirected to the application’s General settings page.
  2. Note the following:
    • Client ID: This will be used as the OIDC Client ID.
    • Client Secret: Click Edit under Client Credentials to reveal and copy the Client Secret. This will be used as the OIDC Client Secret.
      Important: Store the Client Secret securely, as it will not be visible again.

​
Step 4: Enable OIDC Scopes

  1. Go to Security > API in the left-hand menu.
  2. Under Authorization Servers, select the default authorization server.
  3. Navigate to the Scopes tab and ensure the following scopes are enabled:
    • openid
    • profile
    • email
    • offline_access (if your platform supports refreshing tokens).

​
Step 5: Collect Endpoint URLs

  1. From the default authorization server, navigate to the Metadata URI link (e.g., https://<your-okta-domain>/oauth2/default/.well-known/openid-configuration).
  2. Use this metadata to retrieve the following endpoints:
    • Authorization Endpoint: <your-okta-domain>/oauth2/default/v1/authorize
    • Token Endpoint: <your-okta-domain>/oauth2/default/v1/token
    • User Info Endpoint: <your-okta-domain>/oauth2/default/v1/userinfo
Replace <your-okta-domain> with your Okta organization domain (e.g., dev-123456.okta.com).

​
Configuration on Your Platform

Once you’ve collected the necessary information, configure your platform as follows:
FieldValue
OIDC Client IDThe Client ID retrieved from the Okta Admin Console.
OIDC Client SecretThe Client Secret retrieved from the Okta Admin Console.
OIDC Authorization EndpointThe Authorization Endpoint URL retrieved from the metadata.
OIDC Token EndpointThe Token Endpoint URL retrieved from the metadata.
OIDC User Info EndpointThe User Info Endpoint URL retrieved from the metadata.
OIDC User Identifier Keysub
OIDC User First Name Keygiven_name
OIDC User Last Name Keyfamily_name

​
Testing the Integration

  1. Log out of your account on the platform.
  2. Go to the login page and select Sign in with SSO.
  3. Authenticate via Okta.
  4. Verify that:
    • You are redirected back to the platform.
    • Your user details (e.g., name, email) are displayed correctly.

​
Troubleshooting

  • Invalid Client ID/Secret:
    • Ensure the Client ID and Client Secret are entered correctly in your platform.
  • Authorization Errors:
    • Verify the redirect URI matches the one configured in Okta.
  • User Info Mapping Issues:
    • Use a tool like Postman to test the User Info Endpoint (https://<your-okta-domain>/oauth2/default/v1/userinfo) and validate the keys.
For further assistance, contact our support team.