Setting Up OIDC Using Okta for Unqork Designer and Express

Overview

In this article, you'll learn how to configure an OIDC OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials.-based SSO Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. to authenticate users to Unqork using Okta as an identity provider 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.. 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 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. 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 A Secure Identity Cloud is a cloud-based service that manages and protects digital identities, granting secure access to applications and systems through authentication and authorization. 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 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. security, user management, and SSO Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services.. 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:

1. Navigate and log into your Okta Developer Dashboard here: https://developer.okta.com/login/.
2. From the Applications menu to the left of the page, select Applications.
3. Click Create Application.
4. In the Name* field, enter a name for your Okta application. For example, unqork-sso.
5. 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 OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials. 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 URI (Uniform Resource Identifier) identifies a resource by name, location, or both.. 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.

1. At the top right of the Unqork Designer Platform, click Settings ▾.
2. Select Administration.
3. Under Environment, click Single Sign-On (SSO).
4. At the top right, click + New SSO ▾.
5. Select Express. The Basic Information tab displays.
6. In the SSO Name field, enter a name for your SSO configuration.

Ensure you use the same OIDC name you entered in the Okta Redirect URIs field in the previous section of this article. SSO configuration names must be unique and cannot be edited after creation.

7. From the Default Role drop-down, select Authenticated.
8. Click Next. The Configure Protocol tab displays.

A static image displaying the Basic Information configuration for Express SSO.

9. Below Select Protocol*, select OIDC.
10. In the OP Discovery URL / Issuer* field, paste the Okta Domain value you copied from your Okta application.
11. In the OP Client ID* field, paste the Client ID value copied from your Okta application.
12. In the OP Client Secret* field, paste the Client Secret value copied from your Okta application.
13. 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.

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

15. Click Show Advanced Settings.
16. Set Store OIDC ID Token to Checked Box Icon (checked).
17. From the PKCE Code Challenge Method drop-down, select SHA256.
18. Click Next. The Attribute Mapping tab displays.
19. Configure any mappings and settings as necessary. These claims map to attributes in the currentUser object of the session's submission data.
20. Click Create SSO.

A static image displaying the Configure Protocol configuration for Express 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:

1. Access the Single Sign-On Management page and locate your SSO Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. configuration.
2. From the Manage ▾ drop-down, select Preview. Your configuration opens in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..

A static image displaying how to preview your SSO configuration on the Single Sign-On (SSO) Management page.

3. 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.
4. Open a private (or Incognito) browser and paste the URL.
5. 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>.