SAML Authentication with Microsoft Entra ID

Overview

This guide walks you through setting up SAML (Security Assertion Markup Language) authentication between Microsoft Entra ID (Azure AD) and SigNoz.

What you'll accomplish:

• Configure Microsoft Entra ID as an identity provider (IdP) for SigNoz
• Enable your team to access SigNoz using their existing Microsoft Entra ID accounts

Prerequisites

Before starting, ensure you have:

• Microsoft Entra ID account with administrative access
• SigNoz account (Cloud or Self-Hosted with License) with administrative access
• Your SigNoz instance URL (e.g., https://signoz.example.com)

Configuration Steps

Step 1: Create SAML Application in Microsoft Entra ID

1. Log in to your Microsoft Entra ID admin console and create a new SAML application.

Step 2: Configure SAML Settings

1. Once the application is created, go to Single Sign-On from the left sidebar, click on the SAML card option, and in the Basic SAML Configuration section, click the edit icon.
2. Entity Identifier (Entity ID): Enter your SigNoz instance host:port (e.g., signoz.example.com if your SigNoz instance URL is https://signoz.example.com)
3. Reply URL (Assertion Consumer Service URL): Enter your SigNoz instance URL with the redirect path /api/v1/complete/saml appended to it (e.g., https://signoz.example.com/api/v1/complete/saml)
4. Sign on URL: Enter your SigNoz instance URL (e.g., https://signoz.example.com)

Step 3: Export Metadata

1. Locate the App Federation Metadata URL in the SAML configuration page
2. Open this metadata page in a new tab

The metadata file contains important configuration details like:

• Microsoft Entra ID's signing certificate
• Single Sign-On service URLs
• Entity identifiers

Example metadata file structure:

   <EntityDescriptor ID="_2d8d...a006" entityID="https://sts.windows.net/00d562...816c79/" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
   ...
   <ds:X509Data>
       <ds:X509Certificate>certificate-content-here</ds:X509Certificate>
   </ds:X509Data>
   ...
   <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://login.microsoftonline.com/323a6......12688fe83e3s30/saml2"/>

For more details on the metadata page, see Microsoft's federation metadata documentation.

Step 4: Configure SigNoz for SAML Authentication

Now you'll configure SigNoz to accept authentication from Microsoft Entra ID:

1. Navigate to SigNoz Settings:

   • Go to your SigNoz dashboard
   • Click on Settings in the left sidebar
   • Navigate to Organization Settings
   • Click on Authenticated Domains

2. Add New Domain:

   • Click Add Domain
   • Enter the domain that your users would login with (e.g., if your user emails are in format john@example.com, enter example.com)

3. Enter Configuration Details:

   Copy

   Domain: example.com
   SAML ACS URL/SAML IDP URL: <idp-url>
   SAML X.509 Certificate: <some-certificate-data>
   SAML Entity ID: <entity-id>
   Skip AuthN Requests Signed: False

   Where to find these values:

   • Domain: The email domain for users who should use SSO (e.g., example.com for users with @example.com emails)
   • SAML ACS URL/SAML IDP URL: The ACS URL from the metadata file (between <md:SingleSignOnService Location="..."> tags)
   • SAML X.509 Certificate: The certificate content from the metadata file (between <ds:X509Certificate> tags)
   • SAML Entity ID: The entityID value from the metadata file

4. Save Configuration:

   • Click Save to apply the SAML configuration

Step 5: Test the Integration

1. Log out of SigNoz if you're currently logged in
2. Navigate to your SigNoz login page
3. Try logging in with a Microsoft Entra ID user email
4. Verify that you're redirected to Microsoft Entra ID for authentication
5. Complete the Microsoft Entra ID login process
6. Confirm you're successfully logged into SigNoz

Configure Group Claims (Optional)

To use group-based role mapping, configure Microsoft Entra ID to include the user's group memberships in the SAML assertion.

Add a Group Claim in Microsoft Entra ID

1. In your Microsoft Entra ID application, go to Single sign-on from the left sidebar
2. In the Attributes & Claims section, click Edit
3. Click Add a group claim
4. Select which groups to return in the claim (e.g., All groups, Security groups, or Groups assigned to the application)
5. Set Source attribute to Group ID

Customize the Group Claim Name

By default, Microsoft Entra ID emits the group claim as http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. SigNoz expects the claim to be named groups by default, so rename it:

1. In the Group Claims panel, expand Advanced options
2. Check Customize the name of the group claim
3. Set Name to groups
4. Click Save

With Group ID as the source attribute, the claim contains the group object IDs (GUIDs), not group display names. You can find a group's object ID in Microsoft Entra ID under Groups → select the group → Object Id. Use these object IDs in the SigNoz group mappings below.

Configure Role Mapping (Optional)

Role mapping automatically assigns SigNoz roles (signoz-viewer, signoz-editor, signoz-admin) to users when they log in via SAML, based on their Microsoft Entra ID group memberships.

Role Resolution Priority

When a user logs in, SigNoz determines their role using this priority (highest to lowest):

1. Use Role Attribute Directly: if enabled and the SAML assertion contains a role attribute, that value is used directly
2. Group to Role Mappings: the user is assigned the roles of all mapped groups they belong to
3. Default Role: fallback role from configuration
4. signoz-viewer: the ultimate default if nothing else is configured

Configure in SigNoz

1. Ensure you have configured the group claim in Microsoft Entra ID
2. Go to Settings → Organization Settings → Members & SSO → Authenticated Domains
3. Click on your SAML domain to edit it
4. In the Role Mapping (Advanced) section:

   • Set Default Role to signoz-viewer

   • Under Group to Role Mappings, add entries mapping each Microsoft Entra ID group object ID to a SigNoz role:

     Microsoft Entra ID Group (Object ID)	SigNoz Role
     a1b2c3d4-e5f6-7890-abcd-ef1234567890	signoz-admin
     b2c3d4e5-f6a7-8901-bcde-f12345678901	signoz-editor
     c3d4e5f6-a7b8-9012-cdef-123456789012	signoz-viewer

   • Leave Use Role Attribute Directly unchecked

5. Click Save

Troubleshooting

Common issues and solutions:

• "Authentication failed" error: Check that the redirect URI exactly matches https://${SIGNOZ_BASEURL}/api/v1/complete/saml in Microsoft Entra ID
• Groups not appearing or role not assigned: Verify the group claim name in Microsoft Entra ID matches the Groups field in SigNoz attribute mapping (rename it to groups, or set the field to the full claim URI; see Configure Group Claims), and that your group mappings use the group object IDs (GUIDs), not display names
• Locked out?: If you're unable to login because of faulty setup, use password authentication by appending ?password=Y to your login URL: <your-instance-url>/login?password=Y