Single sign-on (SSO)
Okta OIDC SSO Integration Guide
Single sign-on (SSO)
Okta OIDC SSO Integration Guide
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:
- An Okta Admin Account with the ability to create and manage applications.
- 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
- Log in to the Okta Admin Console.
- Navigate to Applications > Applications in the left-hand menu.
- Click Create App Integration.
- Select OIDC - OpenID Connect as the Sign-in method and choose Web Application.
- Click Next.
Step 2: Configure the Application
- 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”).
- App Integration Name: Enter a name for your app (e.g.,
- Click Save.
Step 3: Retrieve Client Credentials
- After saving, you’ll be redirected to the application’s General settings page.
- 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
- Go to Security > API in the left-hand menu.
- Under Authorization Servers, select the default authorization server.
- Navigate to the Scopes tab and ensure the following scopes are enabled:
openidprofileemailoffline_access(if your platform supports refreshing tokens).
Step 5: Collect Endpoint URLs
- From the default authorization server, navigate to the Metadata URI link (e.g.,
https://<your-okta-domain>/oauth2/default/.well-known/openid-configuration). - 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
- Authorization Endpoint:
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:
| Field | Value |
|---|---|
| OIDC Client ID | The Client ID retrieved from the Okta Admin Console. |
| OIDC Client Secret | The Client Secret retrieved from the Okta Admin Console. |
| OIDC Authorization Endpoint | The Authorization Endpoint URL retrieved from the metadata. |
| OIDC Token Endpoint | The Token Endpoint URL retrieved from the metadata. |
| OIDC User Info Endpoint | The User Info Endpoint URL retrieved from the metadata. |
| OIDC User Identifier Key | sub |
| OIDC User First Name Key | given_name |
| OIDC User Last Name Key | family_name |
Testing the Integration
- Log out of your account on the platform.
- Go to the login page and select Sign in with SSO.
- Authenticate via Okta.
- 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.
- Use a tool like Postman to test the User Info Endpoint (
For further assistance, contact our support team.