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 Administration > Environment > 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

User Attribute Mappings

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.

3. 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).

4. 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 openid, 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 Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

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 Access Token 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 Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

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 path.

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.