Microsoft Entra ID Integration Guide

This guide will walk you through setting up a Microsoft Entra ID application and configuring it with our platform for single sign-on authentication.

Prerequisites

• Administrative access to your Microsoft Entra ID (Azure AD) tenant
• Administrative access to your organization's account on our platform

Part 1: Creating an Application in Microsoft Entra ID

Follow Microsoft's official guide to create and configure an application in Entra ID: Establish applications in Microsoft Entra ID

Key Configuration Requirements

When setting up your Entra ID application, ensure you configure the following:

Required Information to Collect:

• Tenant ID (Directory ID) - Found in the application overview
• Client ID (Application ID) - Found in the application overview
• Client Secret - Generated under "Certificates & secrets"

Required Configuration Settings:

• Redirect URI: https://your-platform-domain.com/auth/entra/callback
  • Replace your-platform-domain.com with your actual platform domain
• API Permissions: Ensure the following permissions are granted:
  • User.Read
  • GroupMember.Read.All (required for group synchronization)
  • openid, profile, email

Group Synchronization Setup

Why Configure Groups? When groups are sent with user authentication, our platform can automatically add users to matching user groups. If a group name from Entra ID matches an existing user group name in our platform, the user will be automatically added to that group, streamlining access management.

To enable group synchronization with our platform's user groups:

1. In your Entra ID application, go to "Token configuration"
2. Click "+ Add groups claim"
3. Select the appropriate group types to include:
   • "Groups assigned to the application" (recommended) - Only sends groups that are specifically assigned to this application
   • "Security groups" - Sends all security groups the user belongs to
   • "All groups" - Sends all groups (security, distribution, and directory roles)
4. Choose "Group ID" as the source attribute (recommended for reliability)
5. Important: Also enable group name information so our platform can match group names
6. Click "Add"

Recommended Approach: Use "Groups assigned to the application" option, then assign only the relevant groups to your Entra ID application. This gives administrators precise control over which groups are sent to the platform without exposing all organizational groups.

Group Assignment: If using "Groups assigned to the application", you'll also need to:

1. Go to your application in Entra ID
2. Navigate to "Users and groups"
3. Click "+ Add user/group"
4. Select the groups you want to be available in the platform
5. Assign them to the application

Group Name Matching: Ensure that the groups you assign in Entra ID have names that exactly match the user group names in our platform. When a user logs in, they will be automatically added to any platform user groups that match their Entra ID group memberships.

Note: The GroupMember.Read.All permission is required for the platform to read user group memberships.

Part 2: Configuring Your Platform

Platform Configuration Steps

1. Log into your platform as an administrator
2. Navigate to Admin Settings > Integrations > Microsoft Entra ID
3. Click [+ Create] to add a new integration
4. Fill in the configuration fields:
   • Name: Enter a descriptive name (e.g., "Company SSO")
   • Tenant ID: Paste your Directory (tenant) ID from Entra ID
   • Client ID: Paste your Application (client) ID from Entra ID
   • Secret: Paste your client secret value from Entra ID
   • Callback URL: This is automatically provided - use this URL in your Entra ID application's redirect URI configuration
   • Account: Select the default account for user access (optional)
   • User Group: Select the default user group for new users (optional)
5. Save the configuration
6. Test the integration with a known user account

Important: Copy the Callback URL provided in the platform and ensure it matches exactly with the Redirect URI configured in your Entra ID application.

Part 3: Testing and Troubleshooting

Testing the Integration

1. Test with a known user account:
   • Attempt to log in using the Microsoft Entra ID option
   • Verify successful authentication and proper user data mapping
2. Check user provisioning:
   • Confirm new users are created correctly
   • Verify existing users can link their accounts

Common Issues and Solutions

Issue: "AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application"
Solution: Double-check that the Redirect URI in Entra ID exactly matches your platform's callback URL

Issue: "AADSTS700016: Application with identifier 'xxx' was not found in the directory"
Solution: Verify the Client ID is correctly copied and the application exists in the correct tenant

Issue: "AADSTS7000215: Invalid client secret is provided"
Solution: Generate a new client secret and update your platform configuration

Issue: Users can authenticate but profile information is missing
Solution: Check API permissions and ensure proper scopes are requested

Need Help?

If you encounter issues during setup:

1. Check the troubleshooting section above
2. Review Microsoft's official Entra ID documentation
3. Contact your platform support team with specific error messages
4. Ensure you have the necessary administrative permissions in both systems