---
title: "Setting Up Okta for SSO in Express (OIDC)"
slug: "setting-up-okta-for-sso-in-express-oidc-unqork-platform"
tags: ["authentication", "single-sign-on"]
updated: 2026-09-14T17:03:59Z
published: 2026-09-14T17:03:59Z
canonical: "docs.unqork.io/setting-up-okta-for-sso-in-express-oidc-unqork-platform"
---

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

# Setting Up Okta for SSO in Express (OIDC)

This guide walks you through configuring Okta as an OpenID Connect (OIDC) identity provider for Express SSO in Unqork. Okta is a cloud-based identity and access management platform that provides authentication, authorization, and user management for applications. By configuring Okta as an SSO provider, end-users of your Unqork applications can authenticate through your organization's Okta identity platform instead of managing separate Unqork credentials.

This guide covers Express SSO. For Designer SSO, the configuration steps are similar but use the Designer domain instead of Express.

## Prerequisites

Before you begin, ensure you have:

**In Okta:**

- An Okta account with administrator access.
- Permissions to create and configure applications in Okta.
- An Okta tenant (organization) with at least one test user.

**In Unqork:**

- Administrator access to the Unqork environment.
- Access to Single Sign-On (SSO).
- At least one Express Role created in **Express Role Administration**.

**Knowledge:**

- Basic familiarity with Okta application configuration.
- Understanding of OIDC authentication flow.
- Awareness of which Unqork Express Role to assign as the default for SSO users.

## How Settings Map Between Okta and Unqork

Understanding the mapping between Okta configuration and Unqork SSO settings helps streamline the setup process.

### OIDC Configuration Fields

| Unqork Field | Okta Source | Example Value |
| --- | --- | --- |
| **Issuer** | Authorization Servers > Issuer URI | `https://your-company.okta.com/oauth2/default` |
| **Client ID** | Applications > General > Client ID | `0oa1b2c3d4e5f6g7h8i9` |
| **Client Secret** | Applications > General > Client | `abcdefghijklmnopqrstuvwxyz1234567890ABCD` |
| **Redirect URI** | Configured in Unqork, then added to Okta | `https://your-environment.unqork.io/auth/oidc/okta/cb` |
| **Scope** | Authorization Servers > Scopes | `openid profile email` |

### User Attribute Mappings

| Okta Claim | Unqork Attribute | Typical Use |
| --- | --- | --- |
| `{{ sub }}` | `userId` | Unique user identifier (Okta user ID) |
| `{{ email }}` | `email` | User email address |
| `{{ name }}` | `name` | User display name (full name) |
| `{{ preferred_username }}` | `email` or `userId` | Okta username (typically email) |
| `{{ phone_number }}` | `phone` | User phone number (if configured) |

**Note:** Okta uses standard OIDC claims. The `sub` claim contains the user's Okta ID, which is a unique identifier that Okta assigns to each user and never changes. Use `sub` as the match attribute for reliable user matching.

## Setting Up Okta

### Step 1: Sign In to Okta Admin Console

1. Navigate to your Okta Admin Console.
  - URL format: `https://your-company-admin.okta.com` or `https://your-company.okta.com/admin`.
2. Sign in with administrator credentials.

### Step 2: Create a New Application Integration

1. In the Okta Admin Console, navigate to **Applications** > **Applications**.
2. Click **Create App Integration**.

**Configure the integration:**

**Sign-in method:**

- Select **OIDC - OpenID Connect**.

**Application type:**

- Select **Web Application**.
- This type supports server-side authentication with a client secret.

1. Click **Next**.

### Step 3: Configure Application Settings

**General Settings:**

**App integration name:**

- Enter a descriptive name (for example, `Unqork Express SSO`).
- This name displays in the Okta dashboard and end-user interfaces.

**Logo (Optional):**

- Upload a logo if desired (displays in Okta End-User Dashboard).

**Grant type:**

- Check **Authorization Code** (required for OIDC authorization code flow).
- Check **Refresh Token** (enables token refresh without re-authentication).
- Leave **Implicit** unchecked (not recommended for server-side applications).

**Sign-in redirect URIs:**

- Leave blank for now (you'll add this after creating the Unqork SSO configuration).
- Alternatively, if you know your Unqork environment URL, add it now:
  - `https://your-environment.unqork.io/auth/oidc/okta/cb`

**Sign-out redirect URIs:**

- Leave blank unless you need a custom logout redirect.

**Controlled access:**

- Select who can access this application:
  - **Allow everyone in your organization to access** (most common for SSO).
  - **Limit access to selected groups** (if you want to restrict SSO to specific users).
  - **Skip group assignment for now** (assign groups later).

1. Click **Save**.

### Step 4: Note Your Application Configuration Values

After creating the application, gather the following values from the **General** tab:

**Client ID:**

- Located in the **Client Credentials** section.
- Format: 20-character string (for example, `0oa1b2c3d4e5f6g7h8i9`).
- Copy this value for use in Unqork.

**Client secret:**

- Located in the **Client Credentials** section.
- Click **Copy to clipboard** next to the secret value.
- **Important:** Keep this value secure.

**Issuer URI:**

1. Navigate to **Security** > **API** in the left menu.
2. Click the **Authorization Servers** tab.
3. Locate the **default** authorization server (or a custom authorization server if you created one).
4. Copy the **Issuer URI** value.
  - Format: `https://your-company.okta.com/oauth2/default`.
  - If using a custom authorization server: `https://your-company.okta.com/oauth2/{authServerId}`.

**Keep these values secure:** You'll need them to configure SSO in Unqork.

### Step 5: Configure Authorization Server (Optional)

If you want to customize scopes or claims, configure your authorization server:

1. Navigate to **Security** > **API** > **Authorization Servers**.
2. Click the **default** authorization server (or create a custom one).
3. Review the **Scopes** tab:
  - Verify , **profile**, and **email** scopes are present and active.
4. Review the **Claims** tab:
  - Standard claims (`sub`, `email`, `name`) are included by default.
  - Add custom claims if needed for your integration.

**Note:** For most SSO configurations, the default authorization server with standard scopes is sufficient.

## Configuring SSO in Unqork

### Step 1: Navigate to SSO Management

Navigate to Single Sign-On (SSO) in the UnqorkAI platform.

1. Click **Add SSO Configuration** and select **Express**.
2. On the configuration form, select **OIDC** as the protocol.

### Step 2: Configure Basic Information

**SSO Name:**

- Enter a unique name (for example, `Okta Express`).
- This name identifies the configuration in Unqork.

**Default Role:**

- Select an Express Role to assign to users who authenticate through Okta.
- Common choice: Create a role like `Authenticated User` with appropriate permissions.
- **Important:** Users will receive this role automatically on first login.

**Default Groups (Optional):**

- Select any Express Groups to assign to SSO users.
- Leave blank if you don't use groups.

### Step 3: Configure OIDC Protocol Settings

**OP Discovery URL / Issuer:**

- Paste the issuer URI from Step 4 above.
- Format: `https://your-company.okta.com/oauth2/default`.
- Example: `https://acme-corp.okta.com/oauth2/default`.

**OP Client ID:**

- Paste the **Client ID** from your Okta application.

**OP Client Secret:**

- Paste the **Client secret** from your Okta application.

**Redirect URI:**

- Unqork provides a default redirect URI pattern: `https://<host>/auth/oidc/<name>/cb`.
- You can use the default or enter a custom value.
- Copy this URI to add to Okta (for example, `https://your-environment.unqork.io/auth/oidc/okta/cb`).

**Scope:**

- Enter: `openid profile email`.
- This requests the OpenID Connect ID token with email and profile claims.

**PKCE Code Challenge Method:**

- Select **SHA256** for enhanced security.
- PKCE protects against authorization code interception attacks.
- Okta supports SHA256 PKCE by default.
- Options: Disable PKCE, SHA256, Plain.

**Store OIDC ID Token:**

- Check this if you need to access the ID token in workflows.
- Typically not required for standard authentication.

**Get claims from instead of UserInfo Endpoint:**

- Leave unchecked unless you have custom claims in the access token.
- Standard user claims come from the ID token.

### Step 4: Configure Attribute Mappings

Attribute mappings connect Okta user claims to Unqork user attributes.

**Default mappings:**

1. **User ID mapping:**.
  - Claim: `{{ sub }}`.
  - Attribute: `userId`.
  - This maps Okta's unique user identifier to the Unqork user ID.
2. **Email mapping:**.
  - Claim: `{{ email }}` or `{{ preferred_username }}`.
  - Attribute: `email`.
  - This populates the user's email address.

**To add a mapping:**

1. Click **Add Mapping**.
2. In the **Claim** field, enter the claim in template format (for example, `{{ sub }}`).
3. In the **Attribute** drop-down, select the Unqork attribute.
4. Repeat for each attribute you want to map.

**Available Unqork attributes:**

- `userId`: Unique user identifier
- `email`: User email address
- `name`: User display name
- `phone`: User phone number

**Match Attribute:**

- Select `userId` or `email` as the match attribute.
- This determines how Unqork identifies returning users.
- **Recommendation:** Use `userId` with the `{{ sub }}` claim for stable matching.

**Require User Exists:**

- Leave unchecked to create new users automatically on first login.
- Check this if only pre-existing Unqork users are permitted to authenticate.

### Step 5: Save the Configuration

1. Review all settings.
2. Click **Save Changes**.
3. Unqork creates the SSO configuration and displays the message: "SSO configuration created successfully".

## Completing the Okta Configuration

After saving the SSO configuration in Unqork, complete the setup in Okta.

### Add the Redirect URI to Okta

1. Return to the **Okta Admin Console**.
2. Navigate to **Applications** > **Applications**.
3. Click your application (for example, `Unqork Express SSO`).
4. Click **Edit** in the **General Settings** section.
5. Under **Sign-in redirect URIs**, click **Add URI**.
6. Paste the redirect URI from Unqork (for example, `https://your-environment.unqork.io/auth/oidc/okta/cb`).
7. Click **Save**.

**Important:** The redirect URI in Okta must match exactly what Unqork provides. Any mismatch will cause authentication to fail with a redirect_uri_mismatch error.

### Assign Users or Groups to the Application

1. In your Okta application, click the **Assignments** tab.
2. Click **Assign** > **Assign to People** or **Assign to Groups**.
3. Select the users or groups who should have access to Unqork.
4. Click **Assign** for each user or group.
5. Click **Done**.

**Note:** Users must be assigned to the Okta application to authenticate through SSO. If a user is not assigned, they will see an error when attempting to sign in.

## Testing Your Configuration

### Step 1: Access the SSO Preview

Navigate to Single Sign-On (SSO) in the UnqorkAI platform.

1. Locate your Okta configuration in the **Express** tab.
2. Click the **three-dot menu** for the configuration.
3. Select **Preview**.

Doing so opens the Okta-hosted login page in a new browser tab.

### Step 2: Authenticate with a Test User

1. On the Okta login page, enter the credentials for a test user in your Okta organization.
2. Click **Sign In**.
3. If this is the user's first login, Okta may prompt for:
  - MFA enrollment (if required by your Okta policies).
  - Consent to share profile information (if application requires consent).
4. Complete any required prompts.

### Step 3: Verify Successful Authentication

After successful authentication:

1. Okta redirects to Unqork with an authorization code.
2. Unqork exchanges the code for tokens.
3. You should be authenticated in the Unqork environment.

**If authentication succeeds:**

- You'll see the Unqork interface.
- Navigate to **Administration** > **Environment** > **User Management** to verify the user was created.
- Verify the user has the correct default role and attributes.

**If authentication fails:**

- Review the error message (if displayed).
- Check the browser console for errors.
- Proceed to the Troubleshooting section.

### Step 4: Verify User Attributes

1. Navigate to **Administration** > **Environment** > **User Management**.
2. Search for the test user by email or username.
3. Click the user to view their details.
4. Verify:
  - **Email**: Matches the Okta user email.
  - **User ID**: Populated with the Okta user ID (sub claim).
  - **Role**: Assigned the default role from your SSO configuration.
  - **Groups**: Assigned default groups (if configured).

## Troubleshooting

### Issue: "redirect_uri_mismatch" Error

**Cause:** The redirect URI in Okta does not match the URI Unqork provides.

**Solution:**

1. In Unqork, view the SSO configuration and copy the exact redirect URI.
2. In Okta, navigate to your application > **General Settings**.
3. Verify the **Sign-in redirect URIs** includes the exact URI from Unqork.
4. Check for:
  - Trailing slashes (Okta is strict about exact matches).
  - HTTP vs. HTTPS.
  - Typos in the domain or .
5. Save changes in Okta and retry.

### Issue: "invalid_client" Error

**Cause:** Client ID or client secret is incorrect or the application is misconfigured.

**Solution:**

1. Verify the **Client ID** in Unqork matches the Okta **Client ID** exactly.
2. Verify the **Client secret** is correct.
  - In Okta, navigate to your application > **General Settings** > **Client Credentials**.
  - Copy the secret again and update the Unqork SSO configuration.
3. Ensure the application type is **Web Application** (not SPA or Native).
4. Verify **Authorization Code** grant type is enabled in Okta.
5. Update the SSO configuration in Unqork if credentials were incorrect.

### Issue: "invalid_scope" Error

**Cause:** The requested scopes are not configured in the Okta authorization server.

**Solution:**

1. In Okta, navigate to **Security** > **API** > **Authorization Servers**.
2. Click the **default** authorization server (or your custom one).
3. Click the **Scopes** tab.
4. Verify the following scopes exist and are active:
  - **openid** (required).
  - **profile** (if you map name or other profile attributes).
  - **email** (if you map email).
5. If missing, click **Add Scope** and create them.
6. Save changes and retry.

### Issue: "User is not assigned to the client application" Error

**Cause:** The user attempting to authenticate is not assigned to the Okta application.

**Solution:**

1. In Okta, navigate to **Applications** > **Applications**.
2. Click your application.
3. Click the **Assignments** tab.
4. Verify the user is listed.
5. If not, click **Assign** > **Assign to People**.
6. Search for the user and click **Assign**.
7. Click **Done** and retry authentication.

### Issue: User Not Created on First Login

**Cause:** **Require User Exists** is enabled in the Unqork SSO configuration, or attribute mapping is incorrect.

**Solution:**

1. In Unqork, edit the SSO configuration.
2. Verify **Require User Exists** is unchecked (for automatic user creation).
3. Verify the **Match Attribute** is set to `userId` or `email`.
4. Verify the corresponding claim mapping exists:
  - If match attribute is `userId`, ensure `{{ sub }}` maps to `userId`.
  - If match attribute is `email`, ensure `{{ email }}` or `{{ preferred_username }}` maps to `email`.
5. Save changes and retry.

### Issue: Missing User Attributes After Login

**Cause:** Attribute mappings are incomplete or claims are not included in the ID token.

**Solution:**

1. Verify the **Scope** includes `email` and `profile` if you need those claims.
2. In Unqork, verify attribute mappings are configured:
  - `{{ sub }}` → `userId`
  - `{{ email }}` → `email`
  - `{{ name }}` → `name` (if needed)
3. In Okta, navigate to **Security** > **API** > **Authorization Servers** > **default**.
4. Click the **Claims** tab and verify the claims you're mapping exist.
5. Test with a user who has those attributes populated in Okta.

### Issue: "invalid_grant" Error

**Cause:** Authorization code expired or was already used, or PKCE verification failed.

**Solution:**

1. Retry authentication (authorization codes expire quickly).
2. Verify PKCE settings match between Unqork and Okta.
3. Check the browser console for PKCE-related errors.
4. If the issue persists, disable PKCE temporarily to test (not recommended for production).

### Issue: Claims Not Available in ID Token

**Cause:** Claims are not configured in the authorization server or are mapped incorrectly.

**Solution:**

1. Verify the **Scope** in Unqork includes the required scopes:
  - `openid`: Always required for OIDC
  - `profile`: Required for name and other profile claims
  - `email`: Required for email claim
2. In Okta, navigate to **Security** > **API** > **Authorization Servers** > **default** > **Claims**.
3. Verify standard claims (`sub`, `email`, `name`) exist and are included in the ID token.
4. If you need custom claims, add them in the **Claims** tab:
  - Click **Add Claim**.
  - Configure the claim name, value type, and mapping.
  - Set **Include in token type** to **ID Token**.
  - Click **Create**.
5. Test authentication to verify claims are present.

## Security Best Practices

### Use PKCE

Always set **PKCE Code Challenge Method** to **SHA256** in the Unqork SSO configuration. PKCE protects against authorization code interception attacks and is supported by Okta without additional configuration.

### Rotate Client Secrets Regularly

Okta lets you generate new client secrets:

1. In Okta, navigate to your application > **General Settings** > **Client Credentials**.
2. Click **Edit** next to the client secret.
3. Generate a new secret.
4. Update the Unqork SSO configuration with the new secret.
5. Test authentication to verify the new secret works.
6. Delete the old secret if no longer needed.

**Recommendation:** Rotate secrets every 6-12 months and document the expiration schedule.

### Assign Users and Groups Explicitly

Always use Okta's **Assignments** feature to control which users can access Unqork through SSO:

- Assign users individually for fine-grained control.
- Assign groups for easier management of large user populations.
- Review assignments regularly and remove users who no longer need access.

### Limit Scope to Required Claims

Only request scopes that you need. For basic authentication, `openid profile email` is sufficient. Avoid requesting unnecessary scopes that grant access to additional user data beyond authentication.

### Enable MFA in Okta

Require multi-factor authentication (MFA) for all users authenticating through Okta:

1. Navigate to **Security** > **Authentication Policies**.
2. Configure policies to require MFA.
3. Choose MFA factors (Okta Verify, SMS, hardware tokens).
4. Apply policies to your SSO application.

### Monitor Sign-In Logs

Okta provides detailed logs for authentication attempts:

1. Navigate to **Reports** > **System Log**.
2. Filter by application to see SSO authentication events.
3. Monitor for the following:
  - Failed login attempts (potential brute-force attacks).
  - Unusual sign-in locations or times.
  - Repeated invalid_client or invalid_grant errors.
4. Configure alerts for suspicious activity.

### Use Token Lifetime Policies

Configure appropriate token lifetimes in Okta:

1. Navigate to **Security** > **API** > **Authorization Servers** > **default**.
2. Click the **Access Policies** tab.
3. Configure access token and refresh token lifetimes.
4. Shorter lifetimes increase security but may require more frequent re-authentication.

## Advanced Configuration

### Mapping Okta Groups to Express roles

If you want to assign different Express roles based on Okta group membership:

1. **In Okta:**.
  - Navigate to **Security** > **API** > **Authorization Servers** > **default** > **Claims**.
  - Click **Add Claim**.
  - Configure the groups claim:
    - Name: `groups`.
    - Include in token type: **ID Token**.
    - Value type: **Groups**.
    - Filter: Select groups to include (for example, Regex: `.*` for all groups).
    - Include in: **The following scopes** > Select **profile**.
  - Click **Create**.
2. **In Unqork:**.
  - Add an attribute mapping:
    - Claim: `{{ groups }}` or `{{ groups[0] }}`.
    - Attribute: Custom attribute or role mapping logic.
  - **Note:** Advanced role mapping based on groups may require custom implementation.

### Custom Claims

If your organization uses custom attributes in Okta user profiles:

1. In Okta, navigate to **Directory** > **Profile Editor**.
2. Click **User (default)** to edit the user profile.
3. Add custom attributes if needed.
4. Navigate to **Security** > **API** > **Authorization Servers** > **default** > **Claims**.
5. Click **Add Claim** and map the custom attribute to a claim.
6. In Unqork, add a mapping for the custom claim.

### Custom Authorization Server

For advanced configurations, create a custom authorization server:

1. Navigate to **Security** > **API** > **Authorization Servers**.
2. Click **Add Authorization Server**.
3. Configure the server with custom scopes, claims, and policies.
4. Use the custom authorization server's issuer URI in Unqork.
5. Test thoroughly to ensure claims and scopes work as expected.

## Next Steps

After successfully configuring Okta for Express SSO:

1. **Test with multiple users**: Verify that different users authenticate correctly and receive appropriate roles.
2. **Enable MFA**: Configure multi-factor authentication policies in Okta for enhanced security.
3. **Set up group-based role assignment**: Map Okta groups to different Express roles (if needed).
4. **Update application modules**: Ensure your Unqork applications reference the correct Express roles for RBAC.
5. **Document the configuration**: Maintain a record of the SSO setup, including application details and secret rotation schedule.
6. **Set up monitoring**: Configure alerts for failed authentications and unusual sign-in patterns.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-07-10 | Initial publication. |

Okta is a cloud-based identity and access management (IAM) platform that helps organizations manage user identities, access rights, and credentials across multiple applications, websites, and databases.

OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials.

Identity provider (IdP) provide a service that creates, manages, and verifies users' digital identities, allowing them to securely authenticate and access different applications or services.

The Unqork front-end application framework that delivers Creator-built applications to end-users. Express is the layer end-users interact with—the published forms, screens, and navigation built in the Module Builder. Express is distinct from Express View, which is a Creator-facing preview tool in the IDE.

Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

URI (Uniform Resource Identifier) identifies a resource by name, location, or both.

The client_id is a public identifier for apps

The client secret is a secret known only to the application and the authorization server. The client secret acts as the applications password to the server.

Scope is a tool that limits an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.

A place on your operating system that stores recently copied content. The clipboard only stores one item at a time.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

An OpenID Provider (OP) is Identity Provider (IdP) that acts as a service for authenticating users, provide tokens, and confirm user consent. OIDC providers conform to OpenID Connect, using ID tokens to verify a user's identity.

Multi-factor authentication (MFA) is a security measure that requires users to provide multiple pieces of verification to access an account. Adding an extra layer of protection to prevent unauthorized access even if one credential is compromised. MFA is also known as two-step verification.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

In Unqork an application is a program used to perform specific tasks. An application can be one of two types: workflow or module.

Authentication secrets are a value of confidential information. For example, a password, security token, or cryptographic key, that is used to verify a user's identity during the authentication process to grant access to a system or application.

A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system.

RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network.