OpenID Connect Microsoft Azure Active Directory client
Provides Microsoft Azure Active Directory (Azure AD/Entra ID) authentication integration for Drupal through the OpenID Connect module.
openid_connect_windows_aad
Install
composer require 'drupal/openid_connect_windows_aad:8.x-1.4'
Overview
The OpenID Connect Microsoft Azure Active Directory client module is a specialized plugin for the OpenID Connect module that enables Drupal sites to authenticate users through Microsoft Azure Active Directory (now known as Microsoft Entra ID). It supports both standard Azure AD tenants and Azure AD B2C (Business to Consumer) configurations.
The module provides comprehensive integration with Microsoft's identity platform, including the ability to retrieve user information from Microsoft Graph API, map Azure AD group memberships to Drupal roles, and support for Single Sign-On/Single Sign-Out scenarios. Client secrets are securely stored using the Drupal Key module, enhancing security by separating sensitive credentials from configuration.
This module is essential for enterprise organizations using Microsoft 365 or Azure services who want to provide seamless authentication experiences for their Drupal-based applications and intranets.
Features
- Full OpenID Connect authentication flow with Microsoft Azure Active Directory and Azure AD B2C
- Microsoft Graph API integration for retrieving user profile and group membership information
- Automatic and manual mapping of Azure AD groups to Drupal roles with strict mode option
- Secure client secret storage using the Drupal Key module
- Single Sign-Out (SSO) support with front-channel logout capability
- Configurable authorization prompts (login, consent, select_account, create)
- Flexible subject key selection (sub or oid) for user identity mapping across applications
- Support for updating user email addresses on login from Azure AD
- Azure AD B2C v2 endpoint detection and compatibility
- Email address fallback using otherMails property from Graph API
Use Cases
Enterprise Intranet SSO
Organizations using Microsoft 365 can enable employees to log in to their Drupal-based intranet using their existing work accounts. Users authenticate once with Azure AD and gain access to both Microsoft services and the Drupal site without separate credentials.
Role-Based Access Control via AD Groups
Map Azure AD security groups to Drupal roles to automatically grant appropriate permissions. For example, members of the 'Content Editors' AD group automatically receive the 'editor' Drupal role, while 'Site Administrators' AD group members receive the 'administrator' role.
Customer-Facing B2C Authentication
Use Azure AD B2C to provide flexible sign-up and sign-in experiences for customers. Supports social identity providers and custom user flows configured in Azure, with user information flowing through to Drupal profiles.
Multi-Application Identity Sharing
When using the 'oid' subject key option, user identities are consistent across all Azure AD applications in the same tenant. This enables user data synchronization between multiple Drupal sites or with other applications using the same Azure AD tenant.
Single Sign-Out Across Applications
When a user logs out from any application in the Azure AD ecosystem (such as Office 365), the Drupal site receives a logout callback and terminates the user's Drupal session automatically, ensuring security compliance.
Tips
- Use Microsoft Graph API v1.0 instead of the deprecated Azure AD Graph API for best compatibility and future support
- Create separate Azure AD app registrations for development, staging, and production environments
- Use the Key module's file-based key provider in production to store secrets outside the database
- Configure the 'oid' subject key if you need to synchronize user data between multiple Drupal sites using the same Azure tenant
- Enable strict group mapping mode in production environments where role assignments must be centrally controlled through Azure AD
- Test logout functionality to ensure Single Sign-Out works correctly before going live
- Add the Front-channel logout URL to your Azure app registration to enable SSO logout initiated from other applications
Technical Details
Admin Pages 1
/admin/config/services/openid-connect
Configuration page for OpenID Connect clients. This module adds a 'Windows Azure AD' client type that can be added and configured from this page.
Hooks 3
hook_openid_connect_userinfo_save
Processes user data after OpenID Connect authentication. This module uses it to update email addresses and map Azure AD groups to Drupal roles.
hook_openid_connect_redirect_logout_alter
Alters the logout redirect response to add the logout_hint parameter for proper Azure AD logout. Parses the ID token to extract the login_hint claim.
hook_openid_connect_userinfo_alter
Alters userinfo data after retrieval. Stores both 'sub' and 'oid' claims and optionally maps 'oid' to 'sub' when using oid as the subject key.
Troubleshooting 5
Configure your Azure AD app registration to include the 'email' claim in the ID token. Alternatively, enable 'Use Graph API otherMails property for email address' or 'Hide missing email address warning' in the module settings.
Ensure you have selected either Microsoft Graph API or Azure AD Graph API (deprecated) as the User info endpoint configuration. The module cannot retrieve group information without a Graph API configured. Also verify the application has the 'GroupMember.Read.All' API permission in Azure.
Verify that: 1) The End Session endpoint is configured in the module settings, 2) SSOut is enabled in the main OpenID Connect settings, 3) The Front-channel logout URL is configured in the Azure AD app registration.
The 'oid' subject key requires a patch for the openid_connect module. See https://www.drupal.org/i/3298472 for more information and the required patch.
For OAuth v2.0 endpoints, the 'resource' parameter is not used. Ensure your endpoints are configured for the v2.0 protocol. For v1.0 endpoints, the module automatically adds the appropriate resource parameter.
Security Notes 6
- Client secrets are stored using the Drupal Key module, which supports various secure storage backends including file-based, environment variable, and external key management systems
- The Single Sign-Out endpoint (/openid-connect/windows_aad/signout) is publicly accessible to allow Azure AD to initiate logout, but it validates the session and configuration before performing any action
- Failed or suspicious logout attempts are logged for security monitoring
- The module supports both 'sub' (application-specific) and 'oid' (tenant-wide) subject keys - consider security implications when choosing which to use
- Strict role mapping mode ensures users cannot be granted roles outside of what Azure AD group membership allows
- All communication with Azure AD endpoints uses HTTPS