> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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](https://admin.okta.com/).
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:

| 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

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.