To configure the SSO (Single Sign-On) integration between Microsoft Azure AD (Microsoft Entra ID) and AdOpt, follow the steps below.
⚠️ Important: after completing the configuration, the login must be initiated through AdOpt's SSO URL. Testing directly using the "Test this application" button in Azure may use a different flow and result in RelayState-related errors.
1. Azure Configuration
1.1. Access the Azure portal
Access the Microsoft Azure portal and sign in with an account that has permission to configure enterprise applications.
In the menu, go to:
Microsoft Entra ID → Enterprise applications
1.2. Create or select the application
Create a new Enterprise application for AdOpt or select the application that has already been created.
Then, go to:
Single sign-on → SAML
1.3. Configure Basic SAML Configuration
In the Basic SAML Configuration section, enter the information provided on the Identity Provider configuration page in AdOpt:
Identifier (Entity ID): enter the value provided by AdOpt.
Reply URL (Assertion Consumer Service URL): enter the value provided by AdOpt.
These values must be copied exactly as they appear in the AdOpt configuration.
1.4. Configure Attributes & Claims
In the Attributes & Claims section, configure the attributes required for AdOpt to identify the authenticated user.
The required attributes are:
Claim | Source |
|
|
|
|
The configuration should be equivalent to:
name = user.userprincipalname
emailaddress = user.mail
Pay attention to the attribute names
The claim names must be configured exactly as shown below:
nameemailaddress
Do not replace these names with emails, name.formatted, or other attributes.
⚠️ Important: The "Namespace" field for both name and emailaddress must remain empty:
For example, the following error indicates that the application received a SAML response without the expected attributes:
Invalid SAML response received: Invalid user attributes: emails: The attribute emails is required, name.formatted: The attribute name.formatted is required
If the claims are configured correctly in Azure and this error persists, further technical analysis of the SAML response received by AdOpt may be required.
2. AdOpt Configuration
Create the Identity Provider
In the AdOpt dashboard, access your account settings:
Go to "SAML Single Sign-On (SSO)" and click "Create identity provider":
Then, define:
The (1) Identity provider name, which must:
not contain spaces;
not contain special characters;
be used later to initiate the SSO login.
The (2) Metadata URL is the address provided by the identity provider (in this case, Microsoft Azure AD / Entra ID) containing the information required for AdOpt to configure the SAML connection. This URL can be found in Azure under:
Enterprise applications → [Application] → Single sign-on → SAML Certificates
The (3) Organizations that authenticated users through this Identity Provider will have access to.
Finally, click (4) Create.
3. How to initiate SSO login
After completing the configuration, go to https://dash.goadopt.io/sso/login and enter the name of the Identity Provider configured in AdOpt.
Then:
You will be redirected to Microsoft Azure.
Authenticate through Azure.
Azure will send the SAML response to AdOpt.
AdOpt will process the response and log the user in.
⚠️ Important: we recommend validating the integration by initiating the login through AdOpt. The "Test this application" button available in Azure may initiate a different flow and result in RelayState-related errors, such as: required request parameter 'relayState' for method parameter type string is not present
This error, when occurs only during a test initiated from Azure, does not necessarily mean that the integration is incorrectly configured.
4. Configuration Checklist
Before testing access, confirm the following:
Azure
The AdOpt application was created under Enterprise applications.
The Identifier (Entity ID) is configured as provided by AdOpt.
The Reply URL is configured as provided by AdOpt.
The
nameclaim is configured asuser.userprincipalname.The
emailaddressclaim is configured asuser.mail.The user performing the test has access to the application in Azure.
AdOpt
The Identity Provider was created.
The Identity Provider name does not contain spaces or special characters.
The Azure Metadata URL was entered correctly.
The Organizations that should have access have been selected.
The configuration was saved.
Testing
Access was initiated through
https://dash.goadopt.io/sso/login.The correct Identity Provider name was entered.
The user was redirected to Azure.
Authentication in Azure was completed.
The user was redirected back to AdOpt.
5. Troubleshooting
Error related to emails or name.formatted
If, after authenticating in Azure, you receive an error similar to:
Invalid SAML response received: Invalid user attributes: emails: The attribute emails is required, name.formatted: The attribute name.formatted is required
First, confirm that the Azure Attributes & Claims are configured exactly as follows:
name = user.userprincipalname
emailaddress = user.mail
If these attributes are correct and the error persists, there is no need to change the claims randomly.
In this case, contact AdOpt Support and provide:
the Identity Provider name;
the URL used to initiate the login;
the complete error message displayed;
a screenshot of the Attributes & Claims configuration in Azure.
Our technical team can then verify the SAML response actually received by AdOpt and identify whether there is any discrepancy in attribute processing.
Error related to RelayState
If the error only appears when using the "Test this application" button directly in Azure, try testing again by initiating the login through
If the error also occurs during this flow, send the complete error message to AdOpt Support for further analysis.
Once the configuration is complete and the flow is initiated through AdOpt, the user should be authenticated through Azure and then redirected back to AdOpt with access to the Organizations configured for the Identity Provider.