Setting Up OIDC Using Microsoft Entra ID 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.-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 Microsoft Entra ID as an identity provider. To set up this configuration in Unqork, you must first create a Microsoft Azure account and register a Microsoft Entra ID 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.

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

What Is Microsoft Entra ID?

Microsoft Entra ID is an Azure 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. This article will help you determine the necessary data you must obtain from Microsoft Entra ID for use in Unqork.

To set up an Azure portal and a Microsoft Entra ID application, visit https://portal.azure.com/.

Setting Up Microsoft Entra ID

After creating your Azure account, the first step is to register a Microsoft Entra ID application. Then, you can locate and copy the necessary Microsoft Entra ID fields and paste them into the correct fields in your Unqork environment.

To register for Microsoft Entra ID:

1. Navigate and log into your Azure portal here: https://portal.azure.com/.
2. Set up a Microsoft Entra ID resource.
3. From the Manage menu to the left of the page, select App Registrations.
4. Click + New Registration.

A static image displaying the App Registrations page and the New Registration button.

5. In the *Name field, enter a name for your Microsoft Entra ID application. For example, unqork-sso.
6. Below Supported Account Types, select  Accounts in this organizational directory only (Default Directory only - Single tenant).

Your particular Directory management strategy may differ according to IT policies.

A static image displaying the configuration of a Microsoft Entra ID application.

Leave the Redirect URI URI (Uniform Resource Identifier) identifies a resource by name, location, or both. fields empty at this time. You'll configure these values at a later time.

7. Click Register. The Overview section of your new application displays.

Gathering Microsoft Entra ID Information for Unqork Configuration

With your application created, 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.

Overview Tab

With your Microsoft Entra ID application open, use the Overview tab to gather the following information:

A static image displaying the Application ID needed for OIDC configuration in Unqork.

Setting Description

Application (Client) ID

The Microsoft Entra Application (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.

Endpoints Tab

On the Overview page, click the Endpoints tab above your application details. A panel displays where you can gather the following information:

A static image displaying the Endpoints panel and the OpenID Connect Metadata Document value.

Setting Description

OpenID Connect Metadata Document

The OpenID Connect Metadata Document 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.

Certificates & Secrets Tab

Lastly, use the Certificates & Secrets tab to create a client secret and gather the following information:

Setting Description

Client Secret Value

The Microsoft Entra Client Secret Value 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 because it will no longer be available in the Azure portal after leaving it.

You'll use the Client Secret Value, not the Client Secret ID generated from Microsoft Entra ID.

To create a client secret:

1. Click + New Client Secret. The Add a Client Secret pane displays.
2. In the Description field, enter a description for the client secret.
3. From the Expires drop-down, select the amount of time the secret is available before expiring.

A static image displaying how to create a client secret.

4. Click Add. The pane closes and returns to the Certificates & Secrets page.
5. Copy the Value field and save it for later steps.

A static image displaying the Client Secret Value that must be copied for use in the OIDC configuration in Unqork.

Mapping Microsoft Entra ID to Unqork

With your Microsoft Entra ID configured, and your values copied, open the Unqork Designer Platform in your environment. You'll use these values to configure SSO Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. and map your Microsoft Entra ID credentials to Unqork.

A static image displaying the Basic Information configuration for Express SSO.
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.
7. From the Default Role drop-down, select Administrator.
8. Click Next. The Configure Protocol tab displays.
9. Below Select Protocol*, select OIDC.
10. In the OP Discovery URL / Issuer* field, paste the OpenID Connect Metadata Document value you copied from your Microsoft Entra ID application.
11. In the OP Client ID* field, paste the Application (Client) ID value you copied from your Microsoft Entra ID application.
12. In the OP Client Secret* field, paste the Client Secret Value value you copied from your Microsoft Entra ID application.
13. From the Scope drop-down, select openid, profile, and email.

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.

Copy the Redirect URI after creating it so you can authenticate your Microsoft Entra ID application in a later step.

15. Click Show Advanced Settings.
16. Set Store OIDC ID Token to (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.

A static image displaying the Configure Protocol configuration for Express SSO.

20. Click Create SSO.

Authenticate the Microsoft Entra ID Application

With your OIDC configuration set up in Unqork, return to the Microsoft Entra ID application to complete the authentication.

To authenticate your Microsoft Entra ID application:

1. Navigate to your Azure portal here: https://portal.azure.com/
2. Open your Microsoft Entra ID application.
3. From the Manage menu to the left of the page, select Authentication.
4. Click + Add Platform. The Configure Platform pane opens to the right of the page.
5. Click the Single-Page Application tile. The Configure Single-Page Application pane displays.

A static image displaying the Authentication tab and creating a single-page application platform.

6. Under *Redirect URIs, paste the Redirect URI URI (Uniform Resource Identifier) identifies a resource by name, location, or both. you created and copied in the Mapping Microsoft Entra ID to Unqork section of this article.
7. Set ID tokens (used for implicit and hybrid flows) to (Checked).

A static image displaying the Redirect URI configuration for a single-page application authentication.

8. Click Configure.

If your IT policy allows it, you can grant tenant-wide administration consent for new application registration. Otherwise, the first user who logs in receives a message that Administration consent is required.

To grant tenant-wide administration consent:

1. From the Manage menu to the left of the page, select API Permissions.
2. Because Unqork only requires User.Read permissions, click Grant Admin Consent Unqork. The Grant Admin Consent Confirmation modal A modal is a window that appears on top of the content you are currently viewing. displays.
3. Click Yes.

Testing Your SSO Setup

Test your SSO setup is by using Unqork's Single Sign-On Management page. If you're already logged into a Microsoft Entra ID 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 configuration.
2. From the Manage ▾ drop-down, select Preview. Your configuration opens 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-OIDC/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. Press Enter (or Return) on your keyboard. You're redirected to your Microsoft 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-OIDC/?destination=%23/display/<moduleID>.