Okta OIDC Provider Configuration Guide

Overview

This guide provides step-by-step instructions for configuring Okta as an OpenID Connect (OIDC) Identity Provider for XPressEntry. Once configured, users sign in to XPressEntry with their Okta credentials, and their Okta group memberships are mapped automatically to XPressEntry roles.

This document should be read alongside the OIDC Provider Configuration Guide, which describes the general requirements for any Identity Provider, including how to determine the correct redirect URI for your deployment.

Prerequisites

• Administrative access to the Okta admin console
• The XPressEntry redirect URI(s) — see the Redirect URI Configuration section of the main OIDC Provider Configuration Guide for details on determining the correct URI for your deployment
• Knowledge of which Okta groups should map to XPressEntry roles

Step 1: Create the Application in Okta

1. Log in to the Okta admin console
2. Navigate to Applications
3. Click Create App Integration
4. Select the following options:
   • Sign-in method: OIDC – OpenID Connect
   • Application type: Native Application
     
5. Click Next
6. Enter an application name (e.g., “XPressEntry”)
7. Configure the Sign-in redirect URIs. Add the following:
   • https://localhost:30001/auth/callback — for local access (client on the same machine as the XPressEntry Server)
   • https://<server-ip>:30001/auth/callback — for remote client access (replace <server-ip> with the public-facing IP or hostname of the XPressEntry Server)
   • https://localhost:30002/auth/callback — for the Authentication Test App (if testing)
     
8. Copy the Sign-in redirect URIs into the Sign-out redirect URIs field
9. Set access control: select Allow everyone in your org to access (or restrict as needed), and enable Immediate access if desired
10. Click Save
11. Copy the Client ID from the application’s General tab — this is needed for the XPressEntry configuration
    

Step 2: Configure the Authorization Server

The authorization server controls token issuance, including which scopes and claims are available and how long tokens remain valid.

1. Navigate to Security > API > Authorization Servers
2. Select the default authorization server (or create a custom one)
3. Verify an Access Policy exists that allows clients to access the server
4. Create or edit a policy (e.g., named “XPressEntry”), assigned to all clients or specifically to the XPressEntry application
   
   
5. Add a Rule to the policy with the Authorization Code grant type enabled
6. Configure user access (e.g., any user assigned to the app, or specific groups)
7. Configure the Access Token Lifetime — this determines how long a user’s session lasts before XPressEntry needs to refresh or re-authenticate
   

Step 3: Configure the Groups Claim

For XPressEntry to map Okta groups to internal roles, a groups claim must be included in the access token.

Option A: Add a Groups Claim via the Authorization Server

1. Navigate to Security > API > Authorization Servers and select your server
2. Go to the Claims tab
3. Click Add Claim
   
   
4. Configure the claim as follows:
   • Name: groups
   • Include in token type: Access Token
   • Value type: Groups
   • Filter: Matches regex .* (to include all groups), or use a more specific filter
   • Include in: Any scope (or specify openid)
5. Click Create
   

Option B: Use an Existing Groups Claim

If your Okta configuration already includes group information in another claim (e.g., via a custom claim or app profile attribute), inform the XPressEntry administrator of the claim name so it can be configured accordingly.

Step 4: Configure XPressEntry Server

After completing the Okta configuration, collect the following values:

Configure the Okta Provider

1. In XPressEntry Server, navigate to Tools > Settings
2. Go to the OAuth Settings tab
3. Click Add New
4. Enter the following details:
   • Name: “Okta” (or desired display name)
   • Provider Type: Okta
   • Discovery URL: Issuer URL from the Okta authorization server (from Step 2)
   • Client ID: Application Client ID from Okta (from Step 1)
   • Client Secret: if required by the application configuration
5. Click Save
   

Configure Role Mappings

1. If the group claim name is not “groups”, set the proper claim name in the Group Claim Name textbox
2. In the provider’s role mapping section, add a new mapping
3. Enter the Okta group name exactly as it appears in the token’s groups claim
4. Select the corresponding XPressEntry role to assign (e.g., “XPE Admins” > “Admin”)
5. Click Add
6. Repeat for each group that should be mapped
7. Click Save

Test the Login

1. On the XPressEntry Server login screen, click the Login Method dropdown
2. Select the Okta provider (it appears under the display name configured above)
3. Click Login
4. A browser window opens to the Okta login page
5. Enter your credentials and complete any MFA prompts
6. After successful authentication, you are logged in to XPressEntry

Troubleshooting

User has no roles after login

• Verify the groups claim is configured on the authorization server (see Step 3)
• Check that the group names in the token exactly match the group names configured in the XPressEntry role mappings
• Inspect the token payload to confirm the groups claim is present and populated

Token validation errors

• Verify the Discovery URL is the Issuer URL from the authorization server (not the Okta org URL)
• Ensure the authorization server has an active access policy and rule that includes the XPressEntry application
• Check that the access policy allows the Authorization Code grant type

Redirect URI mismatch

• The redirect URI must exactly match what is registered in Okta (including scheme, hostname, port, and path)
• Use localhost for local access (e.g., https://localhost:30001/auth/callback)
• Use the server’s public-facing IP or hostname for remote client access (e.g., https://192.168.1.100:30001/auth/callback)
• If testing with the Authentication Test App, ensure its redirect URI is also registered (e.g., https://localhost:30002/auth/callback)
• Verify HTTPS vs HTTP matches the XPressEntry Server configuration

Need additional assistance? Contact Telaeris Helpdesk.