This plugin allows users to authenticate to a site with an Azure AD account using OAuth.
This plugin requires an app registration in the Azure AD portal.
Warning: guest users and users created with a linked Microsoft account may lead to strange behavior. See the “How are AD users matched to site users?” FAQ for more information.
Not affiliated with or approved by Microsoft.
After installing the plugin, an application must be created in Azure AD to allow for authentication.
- In the plugin’s settings (Settings -> SSO for Azure AD), make a note of the Redirect URL displayed in the “Endpoints” section.
- In the Azure AD admin panel for your directory, select “New registration”.
- Enter a name. This will be visible to users.
Note: unless you know you need to change this option, leave “Supported account types” set to “Accounts in this organizational directory only”.
- Under “Redirect URI”, select “Web” and enter the Redirect URL that you copied earlier.
If the “URL may not contain a query string” error appears, please see the dedicated FAQ entry for that error.
- Select “Register”.
- Make a note of the “Application (client ID)” and the “Directory (tenant) ID”.
- Select “Certificates & secrets”.
- Select “New client secret”
- Enter a description and select an expiration, then select “Add”.
Note: if you select any option other than “Never”, do not forget to create a new client secret and change it in the plugin settings before the current one expires!
- Make a note of the client secret.
- In the plugin’s settings, enter the values noted down earlier in the corresponding fields and save your changes.
The login button will not be displayed until the plugin has been fully configured.
Make sure that the following options are configured and valid inside the plugin’s settings (Settings -> SSO for Azure AD):
1. Application (client) ID
2. Client secret
3. Directory (tenant) ID
How are AD users matched to site users?
The plugin will look for a user whose email address is the same as their email address on Azure AD.
For example, when the user who logs in to Azure AD by entering
firstname.lastname@example.org in to the site, the plugin will look for a user with the email address
Warning: guest users and users created with a linked Microsoft account may have a different format. For example,
user_guestexample.com#EXTemail@example.com. (In some situations, the
#characters may be removed.)
What happens when an AD user who does not have an account on the site attempts to log in?
The behavior for this case is configurable.
In the “Login options” section of the plugin’s settings (Settings -> SSO for Azure AD), there is an option named “Create new users if they don’t already exist”.
If it is enabled, when a user logs in and the plugin cannot find the corresponding site user, a new one will be created with the same role as the site default for new signups.
The plugin can also automatically fill the user’s name on the new account by enabling the “Generate user profiles automatically” option.
The plugin will set the user’s username to be their email address.
Alternatively, the email address can be removed (
user) by enabling the “Create usernames without domain name” option.
Warning: if multiple users have the same name but different domain names (
firstname.lastname@example.org) enabling this option may cause conflicts.
If it is disabled, when a user logs in and the plugin cannot find the corresponding site user, the following error message will be displayed: “Your account has not been registered on this site. Please contact your administrator.”
How can I add the site administration panel to the Azure application list?
To add the site administration panel to the Azure application list, copy the “Homepage/Login URL” displayed in the “Endpoints” section of the plugin’s settings (Settings -> SSO for Azure AD).
This URL must be pasted in the “Home page URL” field in the “Branding” section of your app registration on the Azure AD portal.
Error while setting up on Azure AD: “URL may not contain a query string”
In some cases, Azure may reject the callback URL provided by the plugin with the error “URL may not contain a query string”.
In this case, URL rewrites are required. In the plugin settings page, enable “Use rewrites” and save.
The callback and login/homepage URLs listed in the plugin settings will change. These new URLs do not contain a query string and should therefore work.
Warning: if you had previously referenced the callback URL with a query string, those references must be changed to the new value displayed in the plugin settings.
Contributors & Developers
“SSO for Azure AD” is open source software. The following people have contributed to this plugin.Contributors
- Added support for URL rewrites
- The plugin now receives less data from Microsoft APIs (only the user’s email address)
- The plugin source now contains internationalization comments
- Breaking change: The plugin now matches users based on email address and not UPN
- “Scope” setting has been removed (the plugin now uses the Microsoft Graph API exclusively)
- Account creation can now automatically fill the user’s name from their Azure AD profile
- Account creation can now create usernames without the email domain
- Other minor changes