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

This guide walks you through configuring Microsoft Entra ID (formerly Azure Active Directory) as a SAML 2.0 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 using SAML, 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 Administration > Environment > Single Sign-On (SSO).
• Access to Administration > Integration > Certificate Management.
• At least one Express Role created in Express Role Administration.

Knowledge:

• Basic familiarity with Microsoft Entra ID Enterprise Applications.
• Understanding of SAML 2.0 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 SAML configuration and Unqork SSO settings helps streamline the setup process.

SAML Configuration Fields

User Attribute Mappings

Note: Microsoft Entra ID uses standard SAML claims with URI namespaces. The NameID claim contains the user's User Principal Name (UPN) or email by default, which serves as a unique identifier. Use NameID as the match attribute for reliable user matching.

Setting Up Microsoft Entra ID

Step 1: Create a New Enterprise 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 Enterprise applications.
4. Click New application.
5. Click Create your own application.

Configure the application:

Name:

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

What are you looking to do with your application?

• Select Integrate any other application you don't find in the gallery (Non-gallery).

6. Click Create.

Step 2: Configure Basic SAML Settings

1. In your Enterprise application, navigate to Single sign-on in the left menu.
2. Select SAML as the single sign-on method.

Basic SAML Configuration:

At this point, you have two options:

Option A: Use Placeholder Values

• Enter temporary placeholder values for Identifier and Reply URL.
• Example Identifier (Entity ID): https://unqork-placeholder.
• Example Reply URL (Assertion Consumer Service URL): https://your-environment.unqork.io/placeholder.
• You'll update these later with the actual values from Unqork's SP metadata.

Option B: Wait to Configure

• Skip Basic SAML Configuration for now.
• Continue to Step 3 to download the IdP metadata.
• Configure Unqork SSO first, then return to complete this section.

Why placeholder values: Entra ID requires these fields before you can access the Federation Metadata XML. Unqork generates the correct values when you create the SSO configuration, creating a circular dependency. Using placeholders breaks this cycle.

3. Click Save (if you entered placeholder values).

Step 3: Download Federation Metadata XML

1. In the SAML Signing Certificate section, locate Federation Metadata XML.
2. Click Download to save the XML file.
3. Keep this file accessible for configuring Unqork.

Alternative: Copy metadata values manually

If you prefer to configure without uploading the full XML file, note these values from the Set up [Application Name] section:

• Login URL: The SAML SSO endpoint.
• Microsoft Entra Identifier: The IdP entity ID.
• Download the Certificate (Base64) from the SAML Signing Certificate section.

Step 4: Configure User Attributes and Claims

1. In the Attributes & Claims section, click Edit.
2. Review the default claims:
   • Unique User Identifier (Name ID): Default source is user.userprincipalname.
   • Name ID format: Default is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Recommended configuration:

Name ID:

• Keep the default user.userprincipalname for the Name ID claim.
• This provides a stable, unique identifier for each user.

Additional claims (if needed):

• Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress → user.mail
• Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name → user.displayname

3. Click Save after making any changes.

Step 5: Assign Users or Groups to the Application

1. Navigate to Users and groups in the left menu.
2. Click Add user/group.
3. Select users or groups who should have access to Unqork through SSO.
4. Click Assign.

Note: Only users assigned to the Enterprise application can authenticate through SAML SSO.

Configuring SSO in Unqork

Step 1: Navigate to SSO Management

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

1. Click Add SSO Configuration and select Express.
2. On the configuration form, select SAML 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: Upload or Configure IdP Metadata

Option A: Upload Federation Metadata XML (Recommended)

1. Click Upload Metadata or the file upload field.
2. Select the Federation Metadata XML file you downloaded from Entra ID.
3. Unqork parses the XML and auto-populates:
   • Identifier Format: The NameID format from the metadata.
   • Entry Point: The SAML SSO URL.
   • Certificate: The X.509 certificate for verifying SAML assertions.

Option B: Manual Configuration

If you prefer to enter values manually:

Identifier Format:

• Enter the NameID format from Entra ID.
• Default: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Entry Point:

• Paste the Login URL from Entra ID.
• Format: https://login.microsoftonline.com/{tenant-id}/saml2.

Certificate:

• Upload the Base64-encoded certificate from Entra ID to Certificate Management.
• Select the uploaded certificate from the drop-down.

Step 4: Configure Advanced SAML Settings (Optional)

Issuer (Entity ID):

• Leave blank to use Unqork's default entity ID.
• Optionally specify a custom entity ID if required by your organization.

Callback URL:

• Unqork displays the callback URL (Assertion Consumer Service URL).
• Format: https://your-environment.unqork.io/auth/saml/consume?idp={name}.
• Copy this URL for Step 6.

Use HTTP-POST Binding:

• Check this if your IdP requires HTTP-POST binding instead of HTTP-Redirect.
• Entra ID supports both, but HTTP-POST is more common for SAML responses.

Use Signed AuthnRequest:

• Check this if Entra ID requires signed authentication requests.
• Requires uploading a certificate to Unqork for signing requests.

Expect Encrypted Assertions:

• Check this if Entra ID sends encrypted SAML assertions.
• Requires additional certificate configuration for decryption.

Disable Requested AuthnContext:

• Check this if Entra ID does not support RequestedAuthnContext in SAML requests.
• Typically not needed for Entra ID.

Step 5: Configure Attribute Mappings

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

Default mappings:

1. User ID mapping:.

   • Claim: {{ NameID }}.
   • Attribute: userId.
   • This maps the SAML NameID (typically UPN or email) to the Unqork user ID.

2. Email mapping (Optional):.

   • Claim: {{ http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress }}.
   • Attribute: email.
   • This populates the user's email address from the email claim.

To add a mapping:

1. Click Add Mapping.
2. In the Claim field, enter the claim in template format.
   • For NameID: {{ NameID }}.
   • For other claims: Full URI in double curly braces.
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 {{ NameID }} 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 are permitted to authenticate.

Step 6: Save and Copy SP Metadata

1. Review all settings.
2. Click Save Changes.
3. Unqork creates the SSO configuration and displays the message: "SSO configuration created successfully".
4. After saving, Unqork generates SP (Service Provider) metadata.

Copy SP Metadata URL or XML:

Unqork provides SP metadata in two formats:

Option A: SP Metadata URL

• Unqork displays a metadata URL.
• Format: https://your-environment.unqork.io/auth/saml/metadata.xml?idp={name}.
• Copy this URL to provide to Entra ID.

Option B: Download SP Metadata XML

• Download the SP metadata XML file from Unqork.
• You'll upload this to Entra ID in the next section.

Providing Azure with SP Metadata XML

After creating the SSO configuration in Unqork, you must provide Entra ID with Unqork's Service Provider metadata to complete the trust relationship.

Step 1: Return to Azure Portal

1. Navigate to Microsoft Entra ID > Enterprise applications.
2. Select your application (for example, Unqork Express SSO).
3. Click Single sign-on in the left menu.

Step 2: Update Basic SAML Configuration

Option A: Upload SP Metadata File

1. In the Basic SAML Configuration section, click Edit.
2. Click Upload metadata file.
3. Select the SP metadata XML file you downloaded from Unqork.
4. Entra ID auto-populates:
   • Identifier (Entity ID): Unqork's entity ID.
   • Reply URL (Assertion Consumer Service URL): Unqork's callback URL.
5. Click Save.

Option B: Enter Values Manually

1. In the Basic SAML Configuration section, click Edit.
2. Enter the following values:

Identifier (Entity ID):

• Enter Unqork's entity ID from the SP metadata.
• Format: https://your-environment.unqork.io or custom entity ID.

Reply URL (Assertion Consumer Service URL):

• Enter the callback URL from Step 6 above.
• Format: https://your-environment.unqork.io/auth/saml/consume?idp={name}.

Sign on URL (Optional):

• Leave blank or enter: https://your-environment.unqork.io.

3. Click Save.

Important: The Identifier and Reply URL in Entra ID must match exactly what Unqork provides in the SP metadata. Any mismatch will cause authentication to fail.

Testing Your Configuration

Step 1: Access the SSO Preview

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

1. Locate your Entra ID SAML configuration in the Express tab.
2. Click the three-dot menu for the configuration.
3. Select Preview.

Doing so 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 the user has not consented:
   • Entra ID may display a consent screen.
   • Click Accept to grant consent.
4. If Multi-Factor Authentication (MFA) is required:
   • Complete the MFA challenge (authenticator app, SMS code).

Step 3: Verify Successful Authentication

After successful authentication:

1. Entra ID generates a SAML assertion.
2. Entra ID posts the assertion to Unqork's callback URL.
3. Unqork validates the assertion and authenticates the user.
4. You should be authenticated in the Unqork environment.

If authentication succeeds:

• You'll see the Unqork interface.
• Navigate to Administration > Environment > User Management 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.

Step 4: Verify User Attributes

1. Navigate to Administration > Environment > User Management.
2. Search for the test user by email or username.
3. Click the user to view their details.
4. Verify:
   • Email: Matches the Entra ID user email or UPN.
   • User ID: Populated with the NameID value (typically UPN or email).
   • Role: Assigned the default role from your SSO configuration.
   • Groups: Assigned default groups (if configured).

Troubleshooting

Issue: "The SAML response signature validation failed" Error

Cause: The certificate in Unqork does not match the certificate Entra ID uses to sign SAML assertions.

Solution:

1. In Entra ID, navigate to Single sign-on > SAML Signing Certificate.
2. Verify the correct certificate is active (check the expiration date).
3. Download the Certificate (Base64).
4. In Unqork, navigate to Administration > Integration > Certificate Management.
5. Upload the new certificate.
6. Edit the SSO configuration and select the updated certificate.
7. Save changes and retry.

Issue: "The reply URL does not match" or "AADSTS50011" Error

Cause: The Reply URL (Assertion Consumer Service URL) in Entra ID does not match Unqork's callback URL.

Solution:

1. In Unqork, view the SSO configuration and copy the exact callback URL.
2. In Entra ID, navigate to Single sign-on > Basic SAML Configuration.
3. Verify the Reply URL matches the Unqork callback URL exactly.
4. Check for:
   • Trailing slashes.
   • HTTP vs. HTTPS.
   • Typos in the domain or path.
5. Save changes in Entra ID and retry.

Issue: "The Identifier does not match" Error

Cause: The Identifier (Entity ID) in Entra ID does not match Unqork's entity ID.

Solution:

1. In Unqork, check the entity ID in the SP metadata or SSO configuration.
2. In Entra ID, navigate to Single sign-on > Basic SAML Configuration.
3. Verify the Identifier (Entity ID) matches Unqork's entity ID.
4. Update the identifier if needed.
5. Save changes and retry.

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 (for 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 {{ NameID }} maps to userId.
   • If match attribute is email, ensure the email claim 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 SAML assertion.

Solution:

1. In Unqork, verify attribute mappings are configured:
   • {{ NameID }} → userId
   • {{ http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress }} → email (if needed)
2. In Entra ID, navigate to Single sign-on > Attributes & Claims.
3. Verify the claims you're mapping exist and are configured correctly.
4. Test with a user who has those attributes populated in Entra ID.
5. Review the SAML assertion in browser developer tools to see which claims are present.

Issue: "The certificate is expired or not yet valid" Error

Cause: The X.509 certificate used to sign SAML assertions has expired or the system clock is incorrect.

Solution:

1. In Entra ID, navigate to Single sign-on > SAML Signing Certificate.
2. Check the expiration date of the active certificate.
3. If expired, create a new certificate:
   • Click New certificate.
   • Set the expiration date.
   • Make the new certificate active.
   • Download the new certificate.
4. Upload the new certificate to Unqork's Certificate Management.
5. Update the SSO configuration to use the new certificate.
6. Retry authentication.

Issue: "AADSTS50105: The signed in user is not assigned to a role" Error

Cause: The user attempting to authenticate is not assigned to the Enterprise application in Entra ID.

Solution:

1. In Entra ID, navigate to your Enterprise application.
2. Click Users and groups in the left menu.
3. Verify the user is listed.
4. If not, click Add user/group.
5. Search for the user and click Assign.
6. Retry authentication.

Issue: NameID Format Mismatch

Cause: The NameID format in the SAML request does not match what Entra ID expects.

Solution:

1. In Entra ID, navigate to Single sign-on > Attributes & Claims.
2. Click on the Unique User Identifier (Name ID) claim.
3. Note the Name ID format value.
4. In Unqork, verify the Identifier Format matches the Entra ID format.
5. Common formats:
   • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
   • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
   • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
6. Update the Unqork configuration if needed and retry.

Security Best Practices

Rotate SAML Signing Certificates Regularly

Entra ID SAML signing certificates expire periodically:

1. Monitor certificate expiration dates in SAML Signing Certificate section.
2. Before expiration, create a new certificate in Entra ID.
3. Download the new certificate and upload to Unqork.
4. Update the Unqork SSO configuration to use the new certificate.
5. Test authentication with the new certificate.
6. After confirming it works, delete the old certificate from Entra ID.

Recommendation: Set calendar reminders 30 days before certificate expiration.

Use Signed AuthnRequest

Enable signed authentication requests for enhanced security:

1. Upload a signing certificate to Unqork's Certificate Management.
2. In the Unqork SSO configuration, check Use Signed AuthnRequest.
3. Select the signing certificate.
4. In Entra ID, verify signed requests are accepted (default behavior).

Require Encrypted Assertions

For sensitive environments, require encrypted SAML assertions:

1. Upload an encryption certificate to Unqork's Certificate Management.
2. In the Unqork SSO configuration, check Expect Encrypted Assertions.
3. Select the encryption certificate.
4. In Entra ID, configure assertion encryption (requires Advanced SAML settings).

Assign Users and Groups Explicitly

Always use Entra ID's Users and groups feature to control which users can access Unqork through SSO:

• Assign users individually for fine-grained control.
• Assign groups for easier management of large user populations.
• Review assignments regularly and remove users who no longer need access.

Enable MFA in Entra ID

Require multi-factor authentication for all users authenticating through Entra ID:

1. Navigate to Microsoft Entra ID > Security > Conditional Access.
2. Create a policy that requires MFA for your Unqork application.
3. Choose MFA methods (Microsoft Authenticator, phone call, SMS).
4. Apply the policy to all users or specific groups.

Monitor Sign-In Logs

Entra ID provides detailed logs for SAML authentication attempts:

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

2. Filter by application to see SSO authentication events.

3. Monitor for the following:

   • Failed login attempts.
   • Unusual sign-in locations or times.
   • SAML assertion validation failures.

4. Configure alerts for suspicious activity using Azure Monitor.

Use 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 Single sign-on > Attributes & Claims.
   • Click Add a group claim.
   • Select groups to include (all groups, security groups, or specific groups).
   • Choose the claim name format (for example, groups or custom namespace).
   • Save the configuration.

2. In Unqork:.

   • Add an attribute mapping:
     • Claim: {{ http://schemas.microsoft.com/ws/2008/06/identity/claims/groups }} or custom claim.
     • Attribute: Custom attribute for role mapping logic.
   • Note: Advanced role mapping based on groups may require custom implementation.

Custom NameID Format

If your organization requires a specific NameID format:

1. In Entra ID, navigate to Single sign-on > Attributes & Claims.
2. Click on the Unique User Identifier (Name ID) claim.
3. Change the Name ID format to your required format:
   • Email address: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
   • Persistent: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
   • Unspecified: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
4. Change the Source attribute if needed (for example, user.mail instead of user.userprincipalname).
5. Save the configuration.
6. Update the Unqork SSO configuration to match the new NameID format.

Custom SAML Claims

If your organization uses custom attributes in Entra ID user profiles:

1. In Entra ID, navigate to Users and ensure custom attributes are populated.
2. Navigate to Single sign-on > Attributes & Claims.
3. Click Add new claim.
4. Configure the claim:
   • Name: Custom claim name or URI.
   • Source: Attribute.
   • Source attribute: Select the custom user attribute.
5. Save the claim.
6. In Unqork, add a mapping for the custom claim.

Next Steps

After successfully configuring Entra ID SAML SSO for Express:

1. Test with multiple users: Verify that different users authenticate correctly and receive appropriate roles.
2. Enable MFA: Configure Conditional Access policies in Entra ID 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 certificate expiration dates.
6. Set up monitoring: Configure alerts for failed authentications and certificate expiration.