Setting Up OIDC Using Okta for Unqork Designer and Express

Overview

In this article, you'll learn how to configure an OIDC-based SSO to authenticate users to Unqork using Okta as an identity provider. To set up this configuration in Unqork, you must first create an Okta Developer account and register an Okta application to retrieve the necessary client IDs and secrets for your Unqork configuration. Once retrieved, you can use Unqork's Single Sign-On (SSO) Management page.

Discover how to use the Single Sign-On (SSO) Management page, view our Single Sign-On (SSO) Management article.

What Is Okta?

Okta is a secure identity cloud that connects all your applications, login portals, and devices together. After the initial setup, every application and program you use becomes available instantly. Common uses for the platform include API security, user management, and SSO. This article will help you determine the necessary data you must obtain from Okta for use in Unqork.

To set up an Okta Developer account and a application, visit https://developer.okta.com/login/.

Setting Up Okta

After creating your Okta account, the first step is to create an Okta application that meets your business needs. Then, locate and copy the necessary Okta fields from your Okta application and paste them into the correct fields in your Unqork environment.

Creating an Okta Application

To create an Okta application:

Navigate and log into your Okta Developer Dashboard here: https://developer.okta.com/login/.
From the Applications menu to the left of the page, select Applications.
Click Create Application.
In the Name* field, enter a name for your Okta application. For example, unqork-sso.
Click Save.

Gathering Okta Information for Unqork Configuration

With your application created, configure other settings to meet your needs and explore the necessary information required to configure your connection in Unqork.

There are a few crucial settings you need to adjust, and information you must copy to create your OIDC configuration in Unqork.

Client Credentials

Setting	Description
Client ID	The Client ID is equivalent to the OP Client ID setting required when configuring OIDC on the Unqork Single Sign-On (SSO) Management page. Copy this value and store it for later steps.
Client Secret	The Client Secret is equivalent to the OP Client Secret setting required when configuring OIDC on the Unqork Single Sign-On (SSO) Management page. Copy this value and store it for later steps.

General Settings

Setting	Description
Okta Domain	The Okta Domain value is equivalent to the OP Discovery URL / Issuer setting required when configuring OIDC on the Unqork Single Sign-On (SSO) Management page. Copy this value and store it for later steps.
Sign-In Redirect URIs	Use this field to enter your Unqork Redirect URI. This value is generated when you create OIDC SSO using the Unqork Single Sign-On (SSO) Management page. That said, you can predict the URI before creating your Unqork OIDC SSO using the following format: `https://{your-environment}.unqork.io/auth/oidc/{name_of_your_unqork_sso}/cb`. There are a few key concepts to highlight when creating your Redirect URI: Specify the protocol of your Redirect URI. For example, `https://`. You'll configure this protocol in the Configure Protocol field on the Unqork Single Sign-On (SSO) Management page. The value of `{name_of_your_unqork_sso}` represents the OIDC name you expect to create or already created on the Unqork Single Sign-On (SSO) Management page. The URI must end with `/cb`. Provide the Designer and Express URIs. For example: Designer: `https://training.unqork.io/auth/oidc/okta-oidc-designer-enablement/cb` Express: `https://trainingx.unqork.io/auth/oidc/enablement-okta/cb`

Setting

Description

Okta Domain

The Okta Domain value is equivalent to the OP Discovery URL / Issuer setting required when configuring OIDC on the Unqork Single Sign-On (SSO) Management page. Copy this value and store it for later steps.

Sign-In Redirect URIs

Use this field to enter your Unqork Redirect URI. This value is generated when you create OIDC SSO using the Unqork Single Sign-On (SSO) Management page. That said, you can predict the URI before creating your Unqork OIDC SSO using the following format: https://{your-environment}.unqork.io/auth/oidc/{name_of_your_unqork_sso}/cb.

There are a few key concepts to highlight when creating your Redirect URI:

Specify the protocol of your Redirect URI. For example, https://. You'll configure this protocol in the Configure Protocol field on the Unqork Single Sign-On (SSO) Management page.
The value of {name_of_your_unqork_sso} represents the OIDC name you expect to create or already created on the Unqork Single Sign-On (SSO) Management page.
The URI must end with /cb.
Provide the Designer and Express URIs. For example:

Designer: https://training.unqork.io/auth/oidc/okta-oidc-designer-enablement/cb
Express: https://trainingx.unqork.io/auth/oidc/enablement-okta/cb

For this example, no changes were made to the default Client Authentication, Grant Type (Authorization Code), or User Consent Required settings.

Mapping Okta to Unqork

With your Redirect URI configured in Okta, and your values copied, open the Unqork Designer Platform in your environment. You'll use these values to configure SSO and map your Okta credentials to Unqork.

At the top right of the Unqork Designer Platform, click Settings ▾.
Select Administration.
Under Environment, click Single Sign-On (SSO).
At the top right, click + New SSO ▾.
Select Express. The Basic Information tab displays.
In the SSO Name field, enter a name for your SSO configuration.
From the Default Role drop-down, select Authenticated.
Click Next. The Configure Protocol tab displays.
Below Select Protocol*, select OIDC.
In the OP Discovery URL / Issuer* field, paste the Okta Domain value you copied from your Okta application.
In the OP Client ID* field, paste the Client ID value copied from your Okta application.
In the OP Client Secret* field, paste the Client Secret value copied from your Okta application.
From the Scope drop-down, select openid and profile.
Typically, these scopes are sufficient. However, review the following documentation to ensure all scopes meet your needs: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
In the Redirect URI field, enter your Redirect URI, including the correct Unqork environment.
Ensure you use the same format you entered into the Okta Sign-In Redirect URIs field in the previous section of this article.
Click Show Advanced Settings.
Set Store OIDC ID Token to (checked).
From the PKCE Code Challenge Method drop-down, select SHA256.
Click Next. The Attribute Mapping tab displays.
Configure any mappings and settings as necessary. These claims map to attributes in the currentUser object of the session's submission data.
Click Create SSO.

Testing Your SSO Setup

The easiest way to test your SSO setup is by using Unqork's Single Sign-On Management page. If already logged into your Okta account, you might need to open the Single Sign-On Management page in a private browser.

To test your SSO setup:

Access the Single Sign-On Management page and locate your SSO configuration.
From the Manage ▾ drop-down, select Preview. Your configuration opens in Express View.
In the browser window, copy the Express View URL. The URL will be in the form of the following example: https://trainingx.unqork.io/auth/oidc/Enablement-okta/preview/express?destination=%23/display/123. The preview link ends simply with 123, which sufficient for testing purposes.
Open a private (or Incognito) browser and paste the URL.
Click Enter (or Return) on your keyboard. You're redirected to your Okta login screen.

After authenticating, you will be redirected to the /display/123 path in your Unqork environment. This path displays an error message, like Bad Gateway or Could Not Connect to API Server. This is expected behavior because /display/123 is an invalid module path. However, this message confirms that you have successfully logged into Unqork using SSO. To confirm, you can view authentication details by appending the /auth/me path. For example, https://trainingx.unqork.io/auth/me. Doing so lets you view the oidc authentication method and the name of the Unqork SSO configuration.

Users can also log in by entering the URL of the Unqork SSO configuration. If you do not have a default module configured for your environment, or you want to specify a particular landing page, add a ?destination parameter. For example, https://trainingx.unqork.io/auth/oidc/Enablement-okta/?destination=%23/display/<moduleID>.