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

This guide walks through configuring Microsoft Entra ID (formerly Azure Active Directory) as a SAML 2.0 identity provider for Designer SSO in Unqork. Entra ID is Microsoft's cloud-based identity and access management service that provides authentication and authorization for applications and resources. By configuring Entra ID as an SSO provider, Creators can authenticate through your organization's existing Entra ID directory instead of managing separate Unqork credentials.

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

Prerequisites

Before you begin, ensure you have:

In Microsoft Entra ID:

• An Azure subscription with access to Microsoft Entra ID.
• Global Administrator or Application Administrator role in Entra ID.
• At least one test user in your Entra ID directory.

In Unqork:

• Administrator access to the Unqork environment.
• Access to Administration > Environment > Single Sign-On (SSO).
• Understanding of Creator roles and permissions in Unqork.

Knowledge:

• Basic familiarity with Microsoft Entra ID enterprise applications.
• Understanding of SAML 2.0 authentication flow.
• Awareness of which Creator 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.

SAML Configuration Fields

User Attribute Mappings

Note: Entra ID uses full URI namespaces for SAML claims. The email claim serves as both the Name ID and the email attribute in Unqork.

Setting Up Microsoft Entra ID

Step 1: Create an Enterprise Application

1. Sign in to the Microsoft Entra admin center (https://entra.microsoft.com).
2. Navigate to Identity > Applications > Enterprise applications.
3. Click New application.
4. Click Create your own application.
5. Enter a name (for example, Unqork Designer SSO).
6. Select Integrate any other application you don't find in the gallery (Non-gallery).
7. Click Create.

Note: This creates a custom SAML application for your Unqork environment. Entra ID will display the application overview page.

Step 2: Assign Users or Groups

Before configuring SAML, assign at least one test user to the application.

1. In your enterprise application, navigate to Users and groups.
2. Click Add user/group.
3. Under Users, click None Selected.
4. Search for and select a test user.
5. Click Select.
6. Click Assign.

Note: Only assigned users can authenticate through this SSO configuration. You can assign individual users or entire groups.

Step 3: Configure SAML Single Sign-On

1. In your enterprise application, navigate to Single sign-on.
2. Select SAML as the single sign-on method.
3. Entra ID displays the SAML configuration page with five sections.

Section 1: Basic SAML Configuration

Click Edit in the Basic SAML Configuration section:

Identifier (Entity ID):

• Enter a temporary placeholder (for example, unqork-designer-temp).
• You will update this later with the actual SP Entity ID from the metadata XML.

Reply URL (Assertion Consumer Service URL):

• Enter a temporary placeholder (for example, https://your-environment.unqork.io/auth/saml/temp).
• You will update this later with the actual callback URL from Unqork.

Sign on URL (Optional):

• Leave blank or enter your Unqork environment URL.

Click Save

Note: These temporary values let you complete the initial configuration. You will replace them after configuring SSO in Unqork and downloading the SP metadata XML.

Section 2: Attributes & Claims

Entra ID provides default claim mappings. Verify the following claims exist:

To verify or edit claims:

1. Click Edit in the Attributes & Claims section.
2. Verify the Unique User Identifier (Name ID) is set to user.mail with format Email address.
3. Verify the additional claims exist as listed above.
4. If email claim is missing, click Add new claim:
   • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
   • Source attribute: user.mail.
5. Click Save.

Section 3: SAML Certificates

1. Locate the Certificate (Base64) row.
2. Click Download to download the certificate file.
3. Note the App Federation Metadata Url (you will use this in Unqork).

Keep the certificate file secure: You will upload this to Unqork or paste its contents into the certificate field.

Section 4: Set up Unqork Designer SSO

This section displays placeholder URLs. You will return to this section after configuring SSO in Unqork to update the Reply URL and Identifier.

Step 4: Note Your Configuration Values

Gather the following values to use in Unqork:

Federation Metadata URL:

• Copy the App Federation Metadata Url from the SAML Certificates section.
• Format: https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml?appid={app-id}.

Certificate:

• Open the downloaded certificate file in a text editor.
• Copy the entire contents (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----).

Login URL (Entry Point):

• Navigate to the Single sign-on page.
• Note the Login URL from Section 4.
• Format: https://login.microsoftonline.com/{tenant-id}/saml2.

Keep these values accessible: You will paste them into the Unqork SSO configuration form.

Setting Up Microsoft Entra ID as a SAML Configuration in Single Sign-On (SSO) Management

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 Designer.
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 Designer).
• This name identifies the configuration in Unqork and is used in the callback URL.

Default Role:

• Select a Creator role to assign to users who authenticate through Entra ID.
• Common choice: Environment:BASIC (basic Creator access with view permissions).
• Important: This role determines the user's environment-level permissions for creating and managing resources.

Step 3: Configure SAML Protocol Settings

IdP Metadata XML:

You have two options to provide the identity provider metadata:

Option 1: Upload Metadata XML (Recommended)

1. Click Upload Metadata.
2. Enter the App Federation Metadata Url from Entra ID.
3. Click Fetch.
4. Unqork retrieves and parses the metadata automatically.
5. Verify that Entry Point and Certificate fields populate.

Option 2: Manual Configuration

1. Leave IdP Metadata XML blank.
2. Manually enter Entry Point, Certificate, and other fields (see below).

Entry Point:

• If using metadata upload, this auto-populates.
• If manual, paste the Login URL from Entra ID.
• Format: https://login.microsoftonline.com/{tenant-id}/saml2.

Certificate:

• If using metadata upload, this auto-populates.
• If manual, paste the full certificate contents from the downloaded Base64 certificate file.
• Include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

Identifier Format:

• Select urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
• This matches Entra ID's default Name ID format.

Callback URL:

• Unqork provides a default callback URL pattern: https://<host>/auth/saml/consume?idp=<name>.
• You can use the default or enter a custom value.
• Copy this URL to add to Entra ID later (for example, https://your-environment.unqork.io/auth/saml/consume?idp=entra-id).

Step 4: Configure Attribute Mappings

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

Default mappings:

1. Email mapping:.

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

2. Name mapping:.

   • Claim: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.
   • Attribute: name.
   • This populates the user's display name.

To add a mapping:

1. Click Add Mapping.
2. In the Claim field, enter the full claim URI (for example, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress).
3. In the Attribute drop-down, select the Unqork attribute.
4. Repeat for each attribute you want to map.

Available Unqork attributes:

• email: User email address
• name: User display name
• firstName: User first name
• lastName: User last name

Match Attribute:

• Select email as the match attribute.
• This determines how Unqork identifies returning users.
• Recommendation: Use email for Designer SSO as it is stable and unique in Entra ID.

Require User Exists:

• Leave unchecked to create new Designer users automatically on first login.
• Check this if only pre-existing Unqork Designer users are permitted to authenticate.

Step 5: Configure Advanced Settings (Optional)

Use HTTP-POST Binding:

• Leave checked (default).
• Entra ID requires POST binding for assertions.

Use Signed AuthnRequest:

• Leave unchecked unless Entra ID requires signed authentication requests.
• Signing is optional for Entra ID.

Expect Encrypted Assertions:

• Leave unchecked unless you configure assertion encryption in Entra ID.
• Entra ID supports encryption but does not require it by default.

Disable Requested AuthnContext:

• Leave unchecked.
• Entra ID supports AuthnContext in SAML requests.

Step 6: 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.".

After saving, Unqork generates the SP metadata XML file. You will use this file to update the configuration in Entra ID.

Providing Entra ID With SP Metadata XML

After saving the SSO configuration in Unqork, you must update Entra ID with the Service Provider (SP) metadata. This resolves the circular dependency where Entra ID needs the callback URL and Unqork needs the IdP metadata.

Step 1: Download the SP Metadata XML from Unqork

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

1. Locate your Entra ID Designer configuration.
2. Click the three-dot menu for the configuration.
3. Select Download Metadata.
4. Save the metadata.xml file.

This file contains the SP Entity ID and Assertion Consumer Service URL that Entra ID requires.

Step 2: Extract Values from the Metadata XML

Open the metadata.xml file in a text editor and locate the following values:

SP Entity ID:

• Found in the <EntityDescriptor> tag's entityID attribute.
• Format: https://your-environment.unqork.io/auth/saml/metadata.xml?idp=entra-id.

Assertion Consumer Service URL:

• Found in the <AssertionConsumerService> tag's Location attribute.
• Format: https://your-environment.unqork.io/auth/saml/consume?idp=entra-id.

Note: You can also manually construct these URLs using the callback URL pattern from the Unqork SSO configuration.

Step 3: Update Entra ID Basic SAML Configuration

1. Return to the Microsoft Entra admin center.
2. Navigate to Identity > Applications > Enterprise applications.
3. Select your Unqork Designer SSO application.
4. Navigate to Single sign-on.
5. Click Edit in the Basic SAML Configuration section.

Replace the placeholder values:

Identifier (Entity ID):

• Delete the temporary placeholder (for example, unqork-designer-temp).
• Enter the SP Entity ID from the metadata XML.
• Example: https://your-environment.unqork.io/auth/saml/metadata.xml?idp=entra-id.

Reply URL (Assertion Consumer Service URL):

• Delete the temporary placeholder.
• Enter the Assertion Consumer Service URL from the metadata XML.
• Example: https://your-environment.unqork.io/auth/saml/consume?idp=entra-id.

Click Save

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

Step 4: Verify the Configuration

1. Review the Basic SAML Configuration section to ensure the Identifier and Reply URL are correct.
2. Verify the Attributes & Claims section includes the email claim.
3. Verify the SAML Certificates section displays the active certificate.
4. Verify assigned users or groups can access the application.

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 Designer configuration.
2. Click the three-dot menu for the configuration.
3. Select Preview.

This opens the Entra ID 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 assigned to the enterprise application.
2. Click Sign In.
3. If prompted, complete any multi-factor authentication challenges.
4. If this is the user's first login to this application, Entra ID may display a consent prompt.
5. Click Accept to grant permissions.

Step 3: Verify Successful Authentication

After successful authentication:

1. Entra ID sends a SAML assertion to Unqork.
2. Unqork validates the assertion and creates or updates the user.
3. You should be authenticated in the Unqork Designer interface.

If authentication succeeds:

• You will see the Unqork Designer home page.
• Navigate to Administration > Creator Permissions > Creator (User) Administration to verify the user was created.
• Verify the user has the correct Creator role and permissions.

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 and Permissions

Navigate to Administration > Creator Permissions > Creator (User) Administration in the Unqork IDE.

1. Search for the test user by email.
2. Click the user to view their details.
3. Verify:
   • Email: Matches the Entra ID user email.
   • Name: Populated with the Entra ID display name.
   • Role: Assigned the default Creator role from your SSO configuration.

Troubleshooting

Issue: "AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application"

Cause: The callback URL in the SAML request does not match the Reply URL in Entra ID.

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 callback URL from Unqork exactly.
4. Check for:
   • Query Parameter format (?idp= vs. /idp/).
   • Trailing slashes.
   • HTTP vs. HTTPS.
   • Typos in the domain or path.
5. Save changes in Entra ID and retry.

Issue: "AADSTS700016: Application with identifier was not found in the directory"

Cause: The SP Entity ID in the SAML request does not match the Identifier in Entra ID.

Solution:

1. Download the SP metadata XML from Unqork.
2. Locate the entityID in the <EntityDescriptor> tag.
3. In Entra ID, navigate to Single sign-on > Basic SAML Configuration.
4. Verify the Identifier (Entity ID) matches the entityID from the metadata XML exactly.
5. Save changes in Entra ID and retry.

Issue: "SAML assertion validation failed: Certificate verification failed"

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

Solution:

1. In Entra ID, navigate to Single sign-on > SAML Certificates.
2. Verify the Status of the certificate is Active.
3. Download the Certificate (Base64) again.
4. In Unqork, edit the SSO configuration.
5. Replace the Certificate field with the newly downloaded certificate contents.
6. Ensure you include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
7. 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 email.
4. Verify the email claim mapping exists:
   • Claim: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
   • Attribute: email.
5. In Entra ID, verify the test user has an email address populated in their profile.
6. 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:
   • Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress → email
   • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name → name
2. In Entra ID, navigate to Single sign-on > Attributes & Claims.
3. Verify the claims exist and are mapped to the correct source attributes.
4. Verify the test user has values for those attributes in their Entra ID profile.
5. Test with a user who has all attributes populated.

Issue: "User is not assigned to a role for the application"

Cause: The user is not assigned to the Entra ID enterprise application.

Solution:

1. In Entra ID, navigate to Enterprise applications > Your application.
2. Navigate to Users and groups.
3. Verify the test user or a group containing the test user is assigned.
4. If not assigned, click Add user/group and assign the user.
5. Wait a few minutes for the assignment to propagate.
6. Retry authentication.

Issue: Entra ID Login Prompt Displays But Authentication Never Completes

Cause: Browser is blocking cookies or third-party redirects, or there is a network issue.

Solution:

1. Check the browser console for errors (press F12).
2. Look for CORS errors, cookie blocking messages, or network failures.
3. Try the authentication flow in a different browser or private/incognito window.
4. Verify your network can reach to login.microsoftonline.com.
5. Disable browser extensions that block trackers or cookies temporarily.
6. If using a corporate network, verify there are no firewall rules blocking SAML traffic.

Issue: Certificate Expired Error

Cause: The SAML signing certificate in Entra ID has expired.

Solution:

1. In Entra ID, navigate to Single sign-on > SAML Certificates.
2. Check the End date of the active certificate.
3. If expired, generate a new certificate:
   • Click New Certificate.
   • Set the expiration date (maximum 3 years).
   • Click Save.
   • Set the new certificate as Active.
4. Download the new Certificate (Base64).
5. In Unqork, edit the SSO configuration and replace the Certificate field.
6. Save changes and retry.

Security Best Practices

Rotate Certificates Before Expiration

Entra ID SAML certificates expire after a configured period (default 3 years). Set a reminder to rotate certificates before expiration:

1. Generate a new certificate in Entra ID.
2. Update the Unqork SSO configuration with the new certificate.
3. Test authentication to verify the new certificate works.
4. Mark the old certificate as inactive in Entra ID.

Use Certificate Management for Multi-Environment Deployments

If you manage multiple Unqork environments (development, staging, production), use Unqork's certificate management feature:

1. Upload certificates to Administration > Integration > Certificate Management.
2. Reference certificates by ID in SSO configurations.
3. Update certificates centrally without editing each SSO configuration.

Enable Signed AuthnRequests for Enhanced Security

For additional security, configure Unqork to sign SAML authentication requests:

1. In Unqork, edit the SSO configuration.
2. Check Use Signed AuthnRequest.
3. Save changes.
4. Download the updated SP metadata XML.
5. In Entra ID, configure the application to require signed requests (if supported).

Limit User Access with Conditional Access Policies

Use Entra ID Conditional Access to enforce additional security requirements:

1. Navigate to Protection > Conditional Access.
2. Create a new policy targeting your Unqork application.
3. Configure conditions:
   • Require multi-factor authentication.
   • Restrict access to specific locations or IP ranges.
   • Require compliant or managed devices.
4. Enable the policy.

Monitor Authentication Activity

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

1. Navigate to Monitoring > Sign-in logs.
2. Filter by your Unqork application.
3. Monitor for the following:
   • Failed sign-in attempts (potential brute-force attacks).
   • Sign-ins from unexpected locations.
   • High volume of authentication errors.

Use Groups for Role Mapping

Instead of assigning Creator roles individually, use Entra ID groups and role mappings:

1. Create groups in Entra ID (for example, Unqork Developers, Unqork Admins).
2. Assign groups to the enterprise application.
3. In Unqork, configure role mappings to grant Creator roles based on group membership.
4. Manage user access by adding or removing users from groups in Entra ID.

Advanced Configuration

Mapping Entra ID Groups to Creator Roles

To assign different Creator roles based on Entra ID group membership:

1. In Entra ID, navigate to Single sign-on > Attributes & Claims.
2. Click Add a group claim.
3. Select Groups assigned to the application.
4. Choose Source attribute: Cloud-only group display names or sAMAccountName.
5. Click Save.

This adds a groups claim to the SAML assertion containing the user's group names.

6. In Unqork, edit the SSO configuration.
7. Under Role Mappings, click Add Role Mapping.
8. Configure the mapping:
   • Claim: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups or groups (depending on claim format).
   • Value: The exact group name from Entra ID (for example, Unqork Admins).
   • Role: Select the Creator role to grant (for example, Environment:Admin).
9. Repeat for each group-to-role mapping.
10. Save the SSO configuration.

Note: The claim name may vary depending on Entra ID configuration. Inspect the SAML assertion in browser developer tools to verify the exact claim name.

Using Custom Attributes

To pass custom user attributes from Entra ID to Unqork:

1. In Entra ID, add a custom claim:

   • Navigate to Single sign-on > Attributes & Claims.
   • Click Add new claim.
   • Name: Choose a custom name (for example, department).
   • Source attribute: Select the Entra ID attribute (for example, user.department).
   • Click Save.

2. In Unqork, add an attribute mapping:

   • Edit the SSO configuration.
   • Click Add Mapping.
   • Claim: The custom claim name (for example, department).
   • Attribute: Map to a Unqork user attribute if available, or store as custom data.

Note: Unqork supports a limited set of user attributes. Custom claims may require additional configuration or custom workflows to store and use.

Next Steps

After successfully configuring Entra ID for Designer SSO:

1. Test with multiple users: Verify that different users authenticate correctly and receive appropriate Creator roles.
2. Configure role mappings: If users should receive different Creator roles based on Entra ID groups, configure advanced role mappings.
3. Document the configuration: Maintain a record of the SSO setup, including certificate expiration dates and group mappings, for your team and future administrators.
4. Set up monitoring: Configure alerts for certificate expiration and monitor sign-in logs for authentication failures.
5. Plan certificate rotation: Schedule certificate rotation before the current certificate expires.