Zoomed Image
USA
800 691 9120
UK
01225 704844

SSO with OKTA

xAssets Configuration Guide
Single Sign On

SSO with OKTA

This page provides step-by-step instructions for configuring OKTA as the single sign-on provider for xAssets. The integration uses PKCE (Proof Key for Code Exchange) authentication, so a client secret is not required.

Prerequisites

  • An OKTA account with administrator access
  • Configuration-level access to xAssets
  • The SSOADMIN account created and in the Admins group (see SSO Introduction and Setup)

Step 1: Create an Application in OKTA

  1. Log in to the OKTA admin console
  2. Navigate to Applications > Create App Integration

Screenshot

  1. Choose OIDC - OpenID Connect as the sign-in method
  2. Choose Single-Page Application as the application type

Screenshot

Screenshot

  1. Configure the application with the following settings:
Setting Value
Application Type Single-Page App (SPA)
Grant Type Authorization Code
User Consent Require consent
Sign-in Redirect URIs https://mycompanyname.hosted.xassets.net/a.aspx (replace with your xAssets URL)
  1. Save the application

Step 2: Configure an Authorisation Server

  1. In the OKTA admin console, navigate to Security > API
  2. Add an Authorisation Server (or use the default one)

Screenshot

  1. Ensure the following scopes are enabled: openid, email, and profile

Screenshot

  1. Add a claim called user that points to user.login:

Screenshot

This claim maps the OKTA username to the token, which xAssets uses to identify the user.

Step 3: Create a Credential Pack in xAssets

  1. Navigate to Discover > Prepare > Credentials (or Settings > Credentials)
  2. Click Create Credentials
  3. Configure the credential pack as follows:
Field Value
Pack Name OKTA-SSO
Domain Your OKTA domain (e.g., dev-xxxxxxxx-admin.okta.com)
Username The Client ID from the application's General tab
Password Any random value (this field is not used with PKCE authentication, but must not be blank)

Screenshot

  1. Save the credential pack

Step 4: Set the Authentication Type

  1. Navigate to Admin > Settings
  2. Set the AUTHENTICATIONID to the OKTA option
  3. Ensure the AUTHENTICATIONSCRIPT points to the Authentication.xsc script (this should be set automatically)

Step 5: Test the Login

  1. Open a new private/incognito browser window
  2. Navigate to your xAssets URL
  3. You should be redirected to the OKTA login page
  4. After successful authentication, you should be returned to xAssets and logged in

If the login fails, see Troubleshooting. To bypass SSO for troubleshooting, add ?logondirect=direct to your xAssets URL.

Tip: If you receive a "redirect_uri mismatch" error from OKTA, check that the Sign-in Redirect URI in your OKTA application exactly matches your xAssets URL, including the protocol and path.