Setting Up OIDC Using Auth0 for Unqork Designer and Express

Overview

In this article, you'll learn how to configure OIDC OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials. to make 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. calls between your Unqork-hosted page using SSO Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. and Auth0 Auth0 is an identity access management (IAM) platform that enables developers to add authentication and authorization features to their applications.. To set up this configuration in Unqork, you must first create an Auth0 account 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.

To learn more about the Single Sign-On (SSO) Management page, view our Single Sign-On (SSO) Management article.

What Is Auth0?

Auth0 is an Okta Okta is a cloud-based identity and access management (IAM) platform that helps organizations manage user identities, access rights, and credentials across multiple applications, websites, and databases. platform that provides developers with tools and services for configuring authentication and authorization flows to their applications. Common uses for the platform include API 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 can help you determine the necessary data you obtain from Auth0 for use in Unqork.

To set up an Auth0 account and application, visit https://auth0.com/.

Setting Up Auth0

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

To create an Auth0 application:

1. Navigate and log into your Auth0 Developer Dashboard here: https://manage.auth0.com/.
2. Click Create Application.
3. In the Name* field, enter a name for your Auth0 application. For example, unqork-sso.
4. Below the Choose Application Type & Technology section, use the tabs to configure the appropriate application to meet your business needs.

In this example, Single Page Application and JavaScript were selected.

5. Click Continue.

Gathering Auth0 Information for Unqork Configuration

With your application created, configure other settings to meet your needs. For this example, you'll open the application Settings 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. These settings include:

Setting Description

Client ID

The Auth0 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 Auth0 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.

Allowed Callback URLs

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/auth0-oidc-designer-enablement/cb

  • Express: https://trainingx.unqork.io/auth/oidc/enablement-auth0/cb

OpenID Configuration

This field is part of the Advanced settings in Auth0. The OpenID Configuration 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.

Examples of Allowed Callback URLs:

A static image displaying the Allowed Callback URLs field to enter your Redirect URI.

Locating OpenID Configuration in Advanced Settings:

A static image displaying the OpenID Configuration that must be copied for use on the Single Sign-On (SSO) Management page.

Mapping Auth0 to Unqork

With your Redirect URI configured in Auth0, and your values copied, open the Unqork Designer Platform in your environment. You'll use these values to configure SSO and map your Auth0 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 Auth0 Allowed Callback URLs 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 Auth0 OpenID Configuration value you copied from your Auth0 application.
11. In the OP Client ID* field, paste the Auth0 Client ID value copied from your Auth0 application.
12. In the OP Client Secret* field, paste the Auth0 Client Secret value copied from your Auth0 application.
13. From the Scope drop-down, select openid.
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 Auth0 Allowed Callback URLs 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. Access the page and locate your SSO configuration. From the Manage ▾ drop-down, select Preview. Your configuration opens in Express View, displaying your SSO login page.

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

The following steps occur with your SSO configuration:

1. Auth0 issues a JSON Web Token (JWT) A JSON Web Token is an Internet standard for creating data with optional signature and/or optional encryption whose payload holds JSON that asserts some number of claims. Tokens are signed either using a private secret or a public/private key. and sends it to your Unqork environment.

Auth0 does not send the JWT directly to the front-end application, or a module you can access in the Module Builder.

2. Auth0 then sends the JWT to the Redirect URI entered in the OIDC configuration on Auth0's side.
3. The Unqork platform decodes the JWT and creates a session for the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product..
4. The Unqork platform removes everything from the JWT except the claims listed in your OIDC configuration. These claims map to attributes in the currentUser object of the session's submission data.
5. The OIDC configuration in Unqork maps the attribute to the claim value.

Resources