How to Configure Azure Entra SAML SSO

What is this guide about?

This guide explains how to configure Azure Entra ID (formerly Azure Active Directory) as a SAML identity provider for meshStack. Using SAML eliminates the need for client secret rotation, providing a more secure and maintenance-free authentication solution based on certificate trust.

Challenge

You want to enable single sign-on (SSO) with Azure Entra ID for meshStack without the operational burden of managing and rotating client secrets. Client secrets expire regularly and require manual intervention, which can lead to service interruptions if not managed properly. SAML-based authentication establishes trust through certificates, eliminating this maintenance overhead.

Prerequisites

• Administrative access to your Azure Entra ID tenant
• Permission to create Enterprise Applications in Azure Entra ID
• Contact with meshcloud support to coordinate the SAML configuration
• Users in Azure Entra ID who need access to meshStack

Advantages of SAML Over OIDC

When integrating Azure Entra ID with meshStack, you have two options: OIDC (OpenID Connect) or SAML. Here's why SAML may be the better choice:

Aspect	OIDC	SAML
Authentication Method	Client ID + Client Secret	Certificate-based trust
Secret Rotation	Required (typically 90 days or less)	Not required
Maintenance Overhead	High - manual secret updates needed	Low - certificates are long-lived
Security Risk	Secrets can expire unexpectedly	Certificate-based trust is more robust
Configuration Complexity	Simpler initial setup	Slightly more complex initial setup

tip

SAML is the recommended approach for production environments where you want to minimize operational overhead and avoid service interruptions from expired client secrets.

Step-by-Step Guide

1. Create Enterprise Application in Azure Entra ID

1. Sign in to the Azure Portal
2. Navigate to Azure Entra ID → Enterprise Applications
3. Click + New application
4. Select Create your own application
5. Enter a name like meshStack SAML SSO
6. Select Integrate any other application you don't find in the gallery (Non-gallery)
7. Click Create

2. Configure Basic SAML Settings

1. In your newly created Enterprise Application, navigate to Single sign-on from the left menu

2. Select SAML as the single sign-on method

3. Click Edit in the Basic SAML Configuration section

4. The URLs for your meshStack installation typically follow this pattern:

   • Identifier (Entity ID): https://sso.{customer-meshStack-url}/auth/realms/meshfed
   • Reply URL (Assertion Consumer Service URL): https://sso.{customer-meshStack-url}/auth/realms/meshfed

   Contact meshcloud support to confirm the exact values for your installation.

5. Enter these values in the corresponding fields

6. Click Save

3. Obtain SAML Metadata URL

1. In the SAML Certificates section, find App Federation Metadata Url
2. Copy this URL - it will be used to configure the SAML identity provider in meshStack
3. Share this metadata URL with meshcloud support through secure channels

tip

The App Federation Metadata URL provides all necessary SAML configuration details dynamically. This eliminates the need to download and share XML files manually.

4. Configure User Attributes and Claims

meshStack requires specific user attributes to function correctly. Configure the following claims:

1. In the Attributes & Claims section, click Edit
2. Ensure the following claims are configured:

Claim Name	Source Attribute	Required
email	user.mail	Yes
firstName	user.givenname	Yes
lastName	user.surname	Yes
username	user.userprincipalname	Yes

3. For the euid (external user ID) attribute used in externally-provisioned identities, configure based on your organization's needs:

   • Use user.userprincipalname for userPrincipalName-based lookup
   • Use user.mail for email-based lookup
   • Ensure this matches your Identity and Access Management configuration

4. Click Save

5. Assign Users and Groups

1. Navigate to Users and groups in your Enterprise Application
2. Click + Add user/group
3. Select the users or groups who should have access to meshStack
4. Click Assign

tip

Consider creating an Azure Entra ID group specifically for meshStack users. This makes it easier to manage access at scale and allows for automated provisioning through user group provisioning.

6. Coordinate with meshcloud Support

After completing the Azure Entra ID configuration:

1. Provide the App Federation Metadata URL to meshcloud support
2. Share any custom attribute mappings you configured
3. Confirm the Entity ID and Reply URL values if you haven't already

meshcloud support will:

• Configure the SAML identity provider in the meshStack Identity Broker (meshIdB) using your metadata URL
• Provide you with the final SAML configuration details
• Test the integration and confirm it's working

7. Test the Integration

1. Navigate to your meshStack URL
2. Click on the login option for Azure Entra ID SAML
3. You should be redirected to Azure Entra ID for authentication
4. After successful authentication, you should be redirected back to meshStack and logged in

warning

Test the integration thoroughly with a few users before rolling it out to your entire organization. Verify that user attributes are mapped correctly and users have the appropriate permissions in meshStack.

SAML Assertion Encryption (Optional)

SAML assertion encryption provides an additional security layer by encrypting the SAML response payload. This ensures that even if the SAML response is intercepted, the assertion content (including user attributes) cannot be read without the decryption key.

What is SAML Assertion Encryption?

SAML assertion encryption uses public-key cryptography to encrypt the assertion content:

• meshStack's Identity Broker (Keycloak) provides a public encryption certificate
• Azure Entra ID uses this certificate to encrypt SAML assertions before sending them
• Only meshStack's Identity Broker can decrypt the assertions using its private key

warning

SAML assertion encryption requires an Azure Entra ID Premium license (P1 or P2). Verify your licensing before attempting to configure this feature, as the token encryption certificate option is not available in the free or basic tiers.

Benefits:

• Enhanced security: Protects user attributes and identity data in transit
• Compliance: Helps meet stricter security requirements for regulated industries
• Data protection: Prevents assertion content from being read if intercepted

Configuration Steps

To enable SAML assertion encryption:

1. Request encryption certificate from meshcloud support

   • Contact meshcloud support to receive the public encryption certificate for your meshStack installation
   • This certificate is specific to your meshStack Identity Broker (Keycloak) instance

2. Upload certificate to Azure Entra ID

   • In your Enterprise Application, navigate to Single sign-on
   • In the SAML Certificates section, find Token encryption certificate
   • Click Import Certificate
   • Upload the encryption certificate file provided by meshcloud support
   • Click Save

3. Verify encryption is enabled

   • Contact meshcloud support to confirm that encrypted assertions are being received and processed correctly
   • Test the authentication flow to ensure it works with encryption enabled

tip

SAML assertion encryption is optional but recommended for production environments handling sensitive data. The basic SAML configuration without encryption is still secure, as SAML responses are already signed and transmitted over HTTPS.

Troubleshooting

Users Can't Sign In

• Verify users are assigned to the Enterprise Application
• Check that all required user attributes (email, firstName, lastName) are being sent in the SAML assertion
• Confirm the Entity ID and Reply URL match what meshcloud support provided

Missing User Attributes

• Review the Attributes & Claims configuration in Azure Entra ID
• Ensure source attributes are populated for all users (e.g., user.mail, user.givenname)
• Check with meshcloud support that attribute names match what meshStack expects

SAML Assertion Errors

• Verify the Federation Metadata XML shared with meshcloud support is current
• Ensure the SAML certificate hasn't expired
• Check Azure Entra ID sign-in logs for detailed error messages

Related Resources

Concepts

• Identity and Access Management
• Users and Groups

Settings

• Configuring your Identity Provider
• User Group Provisioning
• Identity Lookup

Guides

• How to Manage a Workspace
• How to Kickstart Your IDP