Setting Up Microsoft Entra ID for SSO in Express (OIDC)

This guide walks through configuring Microsoft Entra ID (formerly Azure Active Directory) as an OpenID Connect (OIDC) identity provider for Express SSO in Unqork. Microsoft Entra ID is Microsoft's cloud-based identity and access management service that provides authentication and authorization for applications and users. By configuring Entra ID as an SSO provider, end-users of your Unqork applications can authenticate through your organization's Microsoft identity platform instead of managing separate Unqork credentials.

This guide covers Express SSO. For Designer SSO, the configuration steps are similar but use the Designer domain instead of Express.

Prerequisites

Before you begin, ensure you have:

In Microsoft Entra ID:

• An Azure subscription with access to Microsoft Entra ID (formerly Azure AD).

• Permissions to register applications in Entra ID.

• An Entra ID tenant with at least one test user.

In Unqork:

• Administrator access to the Unqork environment.

• Access to Single Sign-On (SSO).

• At least one Express Role created in Express Role Administration.

Knowledge:

• Basic familiarity with Microsoft Entra ID app registrations.

• Understanding of OIDC authentication flow.

• Awareness of which Unqork Express Role to assign as the default for SSO users.

How Settings Map Between Microsoft Entra ID and Unqork

Understanding the mapping between Entra ID configuration and Unqork SSO settings helps streamline the setup process.

OIDC Configuration Fields

User Attribute Mappings

Note: Microsoft Entra ID uses standard OIDC claims. The sub claim contains the user's object ID, which is a unique identifier (GUID) that Entra ID assigns to each user and never changes. Use sub or oid as the match attribute for reliable user matching.

Setting Up Microsoft Entra ID

Step 1: Register a New Application

1. Sign in to the Azure Portal (https://portal.azure.com).

2. Navigate to Microsoft Entra ID (or search for "Entra ID" in the search bar).

3. In the left navigation, select App registrations.

4. Click New registration.

Configure the app registration:

Name:

• Enter a descriptive name (for example, Unqork Express SSO).

• This name displays in consent screens and admin interfaces.

Supported account types:

• Select Accounts in this organizational directory only (Single tenant).

• This restricts authentication to users in your Entra ID tenant.

• Alternative: Select Accounts in any organizational directory (Multi-tenant) if you need to support multiple tenants.

Redirect URI:

• Leave blank for now (you'll add this after creating the Unqork SSO configuration).

• Alternatively, if you know your Unqork environment URL, you can add it now:

  • Platform: Web.

  • URI: https://your-environment.unqork.io/auth/oidc/entra-id/cb.

5. Click Register.

Step 2: Note Your Application Configuration Values

After registering the application, gather the following values from the Overview page:

Application (client) ID:

• This is your Client ID.

• Format: GUID (for example, abcd1234-5678-90ef-ghij-klmnopqrstuv).

• Copy this value for use in Unqork.

Directory (tenant) ID:

• This is your Tenant ID.

• Format: GUID (for example, 12345678-1234-1234-1234-123456789abc).

• Used to construct the issuer URL.

Issuer URL:

• Construct the issuer URL using your tenant ID:

  • Format: https://login.microsoftonline.com/{tenant-id}/v2.0.

  • Example: https://login.microsoftonline.com/12345678-1234-1234-1234-123456789abc/v2.0.

• This is the value you'll enter in Unqork's OP Discovery URL / Issuer field.

Keep these values secure: You'll need them to configure SSO in Unqork.

Step 3: Create a Client Secret

1. In your app registration, navigate to Certificates & secrets in the left menu.

2. Click the Client secrets tab.

3. Click New client secret.

Configure the client secret:

Description:

• Enter a descriptive name (for example, Unqork SSO Secret).

Expires:

• Select an expiration period:

  • 6 months (recommended for production with rotation policy).

  • 12 months.

  • 24 months.

  • Custom (specify exact date).

• Important: Set a calendar reminder to rotate the  before it expires.

4. Click Add.

Copy the secret value:

• After creating the secret, copy the Value (not the Secret ID).

• Critical: This value is only shown once. If you navigate away without copying it, you must create a new secret.

• Store this securely for use in Unqork.

Step 4: Configure API Permissions

1. In your app registration, navigate to API permissions in the left menu.

2. Click Add a permission.

3. Select Microsoft Graph.

4. Select Delegated permissions.

Add the following permissions:

• OpenId permissions:

  • Check  (required for OIDC).

  • Check profile (to retrieve user profile attributes).

  • Check email (to retrieve user email address).

5. Click Add permissions.

Grant admin consent (if required):

If your organization requires admin consent:

1. Click Grant admin consent for [Your Organization].

2. Click Yes to confirm.

3. Permissions display a green checkmark in the Status column.

Note: Admin consent is typically required in enterprise environments. Without it, users see a consent prompt on first login.

Step 5: Configure Token Configuration (Optional)

By default, Entra ID includes standard OIDC claims in tokens. If you need additional claims or custom attributes:

1. Navigate to Token configuration in the left menu.

2. Click Add optional claim.

3. Select ID token type.

4. Check additional claims you want to include (for example, family_name, given_name).

5. Click Add.

Note: This step is optional. Standard claims (sub, email, name) are sufficient for most SSO configurations.

Configuring SSO in Unqork

Step 1: Navigate to SSO Management

Navigate to Single Sign-On (SSO) in the Unqork IDE.

1. Click Add SSO Configuration and select Express.

2. On the configuration form, select OIDC as the protocol.

Step 2: Configure Basic Information

SSO Name:

• Enter a unique name (for example, Entra ID Express).

• This name identifies the configuration in Unqork.

Default Role:

• Select an Express Role to assign to users who authenticate through Entra ID.

• Common choice: Create a role like Authenticated User with appropriate permissions.

• Important: Users will receive this role automatically on first login.

Default Groups (Optional):

• Select any Express Groups to assign to SSO users.

• Leave blank if you don't use groups.

Step 3: Configure OIDC Protocol Settings

OP Discovery URL / Issuer:

• Paste the issuer URL constructed in Step 2 above.

• Format: https://login.microsoftonline.com/{tenant-id}/v2.0.

• Example: https://login.microsoftonline.com/12345678-1234-1234-1234-123456789abc/v2.0.

OP Client ID:

• Paste the Application (client) ID from your Entra ID app registration.

OP Client Secret:

• Paste the Client secret value from Step 3 above.

Redirect URI:

• Unqork provides a default redirect URI pattern: https://<host>/auth/oidc/<name>/cb.

• You can use the default or enter a custom value.

• Copy this URI to add to Entra ID (for example, https://your-environment.unqork.io/auth/oidc/entra-id/cb).

Scope:

• Enter: openid profile email.

• This requests the OpenID Connect ID token with email and profile claims.

• Add offline_access to enable refresh tokens (for example: openid profile email offline_access). With this scope, Unqork silently refreshes the access token on expiration without prompting the end-user to log in again. See SSO Concepts for how Unqork uses refresh tokens.

PKCE Code Challenge Method:

• Select SHA256 for enhanced security.

• PKCE protects against authorization code interception attacks.

• Entra ID supports SHA256 PKCE by default.

• Options: Disable PKCE, SHA256, Plain.

Store OIDC ID Token:

• Check this if you need to access the ID token in workflows.

• Typically not required for standard authentication.

Get claims from  instead of UserInfo Endpoint:

• Leave unchecked unless you have custom claims in the access token.

• Standard user claims come from the ID token.

Step 4: Configure Attribute Mappings

Attribute mappings connect Entra ID user claims to Unqork user attributes.

Default mappings:

1. User ID mapping:.

   • Claim: {{ sub }}.

   • Attribute: userId.

   • This maps Entra ID's unique user identifier (object ID) to the Unqork user ID.

2. Email mapping:.

   • Claim: {{ email }} or {{ preferred_username }}.

   • Attribute: email.

   • This populates the user's email address.

   • Note: Use {{ preferred_username }} if email is not included in the ID token.

To add a mapping:

1. Click Add Mapping.

2. In the Claim field, enter the claim in template format (for example, {{ sub }}).

3. In the Attribute drop-down, select the Unqork attribute.

4. Repeat for each attribute you want to map.

Available Unqork attributes:

• userId: Unique user identifier

• email: User email address

• name: User display name

• phone: User phone number

Match Attribute:

• Select userId or email as the match attribute.

• This determines how Unqork identifies returning users.

• Recommendation: Use userId with the {{ sub }} claim for stable matching.

Require User Exists:

• Leave unchecked to create new users automatically on first login.

• Check this if only pre-existing Unqork users should be allowed to authenticate.

Step 5: Save the Configuration

1. Review all settings.

2. Click Save Changes.

3. Unqork creates the SSO configuration and displays the message: "SSO configuration created successfully".

Completing the Entra ID Configuration

After saving the SSO configuration in Unqork, complete the setup in Entra ID.

Add the Redirect URI to Entra ID

1. Return to the Azure Portal.

2. Navigate to Microsoft Entra ID > App registrations.

3. Select your application (for example, Unqork Express SSO).

4. In the left menu, select Authentication.

5. Under Platform configurations, click Add a platform (if no platforms exist) or Add URI under Web.

6. Select Web as the platform.

7. Under Redirect URIs, add the redirect URI from Unqork.

   • Example: https://your-environment.unqork.io/auth/oidc/entra-id/cb.

8. Under Implicit grant and hybrid flows, leave all checkboxes unchecked (not needed for OIDC authorization code flow).

9. Click Configure (if adding a new platform) or Save (if adding a URI).

Important: The redirect URI in Entra ID must match exactly what Unqork provides. Any mismatch will cause authentication to fail with a redirect_uri_mismatch error.

Configure Token Settings (Optional)

If you need to customize token behavior:

1. In your app registration, select Token configuration.

2. Configure optional claims as needed.

3. Save changes.

Testing Your Configuration

Step 1: Access the SSO Preview

Navigate to Single Sign-On (SSO) in the Unqork IDE.

1. Locate your Entra ID configuration in the Express tab.

2. Click the three-dot menu for the configuration.

3. Select Preview.

This opens the Entra ID-hosted login page in a new browser tab.

Step 2: Authenticate with a Test User

1. On the Entra ID login page, enter the credentials for a test user in your tenant.

2. Click Sign in.

3. If this is the user's first login and admin consent was not granted:

   • Entra ID displays a consent screen listing the requested permissions.

   • Click Accept to grant consent.

4. If Multi-Factor Authentication (MFA) is required:

   • Complete the MFA challenge (authenticator app, SMS code, or other methods).

Step 3: Verify Successful Authentication

After successful authentication:

1. Entra ID redirects to Unqork with an authorization code.

2. Unqork exchanges the code for tokens.

3. You should be authenticated in the Unqork environment.

If authentication succeeds:

• You'll see the Unqork interface.

• Navigate to Express User Administration to verify the user was created.

• Verify the user has the correct default role and attributes.

If authentication fails:

• Review the error message (if displayed).

• Check the browser console for errors.

• Proceed to the Troubleshooting section below.

Step 4: Verify User Attributes

Navigate to Express User Administration in the Unqork IDE.

1. Search for the test user by email or username.

2. Click the user to view their details.

3. Verify:

   • Email: Matches the Entra ID user email or UPN.

   • User ID: Populated with the Entra ID object ID (GUID format).

   • Role: Assigned the default role from your SSO configuration.

   • Groups: Assigned default groups (if configured).

Troubleshooting

Issue: "redirect_uri_mismatch" Error

Cause: The redirect URI in Entra ID does not match the URI Unqork provides.

Solution:

1. In Unqork, view the SSO configuration and copy the exact redirect URI.

2. In Entra ID, navigate to your app registration > Authentication.

3. Verify the Redirect URIs includes the exact URI from Unqork.

4. Check for:

   • Trailing slashes (Entra ID is strict about exact matches).

   • HTTP vs. HTTPS.

   • Typos in the domain or .

5. Save changes in Entra ID and retry.

Issue: "invalid_client" Error

Cause: Client ID or client secret is incorrect, expired, or the app registration is misconfigured.

Solution:

1. Verify the Client ID in Unqork matches the Entra ID Application (client) ID exactly.

2. Verify the Client secret is correct and has not expired.

   • In Entra ID, navigate to Certificates & secrets.

   • Check the Expires column for your secret.

   • If expired, create a new secret and update the Unqork SSO configuration.

3. Ensure the app registration is not disabled or deleted.

4. Update the SSO configuration in Unqork if credentials were incorrect.

Issue: "invalid_scope" Error

Cause: The requested scopes are not configured or consented in Entra ID.

Solution:

1. In Entra ID, navigate to your app registration > API permissions.

2. Verify the following permissions are present:

   • openid (required).

   • profile (if you map name or other profile attributes).

   • email (if you map email).

3. If admin consent is required, click Grant admin consent for [Your Organization].

4. Save changes and retry.

Issue: "AADSTS50011: The redirect URI specified in the request does not match"

Cause: Same as redirect_uri_mismatch, but error originates from Entra ID.

Solution:

1. Follow the same resolution steps as "redirect_uri_mismatch" error above.

2. Ensure the redirect URI is added under the Web platform (not SPA or Mobile).

3. Verify the URI does not have URL-encoded characters that don't match Unqork's format.

Issue: User Not Created on First Login

Cause: Require User Exists is enabled in the Unqork SSO configuration, or attribute mapping is incorrect.

Solution:

1. In Unqork, edit the SSO configuration.

2. Verify Require User Exists is unchecked (to allow automatic user creation).

3. Verify the Match Attribute is set to userId or email.

4. Verify the corresponding claim mapping exists:

   • If match attribute is userId, ensure {{ sub }} or {{ oid }} maps to userId.

   • If match attribute is email, ensure {{ email }} or {{ preferred_username }} maps to email.

5. Save changes and retry.

Issue: Missing User Attributes After Login

Cause: Attribute mappings are incomplete or claims are not included in the ID token.

Solution:

1. Verify the Scope includes email and profile if you need those claims.

2. In Unqork, verify attribute mappings are configured:

   • {{ sub }} → userId

   • {{ email }} or {{ preferred_username }} → email

   • {{ name }} → name (if needed)

3. In Entra ID, verify the user has the attributes you're trying to map:

   • Navigate to Users and select the test user.

   • Verify attributes like email and display name are populated.

4. If using optional claims, verify they're configured in Token configuration.

5. Test with a user who has those attributes populated.

Issue: "AADSTS700016: Application not found in the directory"

Cause: Client ID is incorrect or the app registration was deleted.

Solution:

1. Verify the Client ID in Unqork matches the Entra ID Application (client) ID exactly.

2. In Entra ID, verify the app registration exists in App registrations.

3. Ensure you're signed in to the correct Azure tenant.

4. Update the Unqork SSO configuration with the correct Client ID.

Issue: Claims Not Available in ID Token

Cause: Entra ID does not include certain claims by default.

Solution:

1. Verify the Scope in Unqork includes the required scopes:

   • openid: Always required for OIDC

   • profile: Required for name and other profile claims

   • email: Required for email claim

2. For claims not included by default (for example, family_name, given_name):

   • Navigate to Token configuration in your app registration.

   • Click Add optional claim > ID.

   • Select the claims you need.

   • Click Add.

3. Test authentication to verify claims are present.

Issue: "AADSTS65001: The user or administrator has not consented"

Cause: Admin consent was not granted for the requested permissions.

Solution:

1. In Entra ID, navigate to your app registration > API permissions.

2. Click Grant admin consent for [Your Organization].

3. Click Yes to confirm.

4. Verify all permissions show a green checkmark in the Status column.

5. Retry authentication.

Security Best Practices

Use PKCE

Always set PKCE Code Challenge Method to SHA256 in the Unqork SSO configuration. PKCE protects against authorization code interception attacks and is supported by Entra ID without additional configuration.

Rotate Client Secrets Regularly

Entra ID lets you create multiple client secrets with different expiration dates:

1. Before a secret expires, create a new secret in Entra ID.

2. Update the Unqork SSO configuration with the new secret.

3. Test authentication to verify the new secret works.

4. Delete the old secret after confirming the new one is active.

Recommendation: Set secrets to expire in 6-12 months and establish a rotation schedule.

Use Single Tenant Account Type

Always select Accounts in this organizational directory only (Single tenant) unless you have a specific need for multi-tenant authentication. Single tenant restricts authentication to users in your Entra ID tenant, reducing the attack surface.

Limit Scope to Required Claims

Only request scopes that you need. For basic authentication, openid profile email is sufficient. Avoid requesting unnecessary scopes or permissions that grant access to user data beyond authentication.

Grant Admin Consent Centrally

Grant admin consent for the application in Entra ID instead of requiring individual users to consent. This prevents users from being prompted and ensures consistent permission grants across the organization.

Monitor Sign-In Logs

Entra ID provides detailed sign-in logs for authentication attempts:

1. Navigate to Microsoft Entra ID > Sign-in logs.

2. Monitor for the following:

   • Failed login attempts (potential brute-force attacks).

   • Unusual sign-in locations or times.

   • Sign-ins from unmanaged devices.

3. Configure alerts for suspicious activity using Azure Monitor.

Enable Conditional Access Policies

Use Entra ID Conditional Access to enforce additional security requirements:

• Require MFA for all SSO authentications.

• Block sign-ins from untrusted locations.

• Require compliant or managed devices.

• Apply session controls (sign-in frequency, persistent browser sessions).

Advanced Configuration

Mapping Entra ID Groups to Express roles

If you want to assign different Express roles based on Entra ID group membership:

1. In Entra ID:.

   • Navigate to your app registration > Token configuration.

   • Click Add groups claim.

   • Select Security groups or All groups.

   • Choose the token types to include groups in (select ID).

   • Click Add.

2. In Unqork:.

   • Add an attribute mapping:

     • Claim: {{ groups }} or {{ groups[0] }}.

     • Attribute: Custom attribute or role mapping logic.

   • Note: Advanced role mapping based on groups may require custom implementation.

Custom Claims

If your organization uses custom attributes or extensions in Entra ID:

1. Configure custom claims in Token configuration.

2. Map the custom claim to a Unqork attribute in the SSO configuration.

3. Test to verify the claim is present in the ID token.

Next Steps

After successfully configuring Entra ID for Express SSO:

1. Test with multiple users: Verify that different users authenticate correctly and receive appropriate roles.

2. Configure Conditional Access: Set up MFA and device compliance policies for enhanced security.

3. Set up group-based role assignment: Map Entra ID groups to different Express roles (if needed).

4. Update application modules: Ensure your Unqork applications reference the correct Express roles for RBAC.

5. Document the configuration: Maintain a record of the SSO setup, including app registration details and secret expiration dates.

6. Set up monitoring: Configure alerts for failed authentications and unusual sign-in patterns.