Debug SAML-based single sign-on to applications in Azure Active Directory
Microsoft identity platform (v2.0) is an evolution of the Azure Active Directory (Azure AD) developer platform (v1.0). It allows developers to build applications that sign in all Microsoft identities and get tokens to call Microsoft APIs such as Microsoft Graph or APIs that developers have built. This content is for the older, Azure AD v1.0 endpoint. We recommend that you use the v2.0 endpoint for new projects. For more info, read Why update to Microsoft identity platform (v2.0)? as well as Microsoft identity platform limitations.
Before you begin
We recommend installing the My Apps Secure Sign-in Extension. This browser extension makes it easy to gather the SAML request and SAML response information that you need to resolving issues with single sign-on. In case you cannot install the extension, this article shows you how to resolve issues both with and without the extension installed.
To download and install the My Apps Secure Sign-in Extension, use one of the following links.
Test SAML-based single sign-on
To test SAML-based single sign-on between Azure AD and a target application:
Sign in to the Azure portal as a global administrator or other administrator that is authorized to manage applications.
In the left blade, select Azure Active Directory, and then select Enterprise applications.
From the list of enterprise applications, select the application for which you want to test single sign-on, and then from the options on the left select Single sign-on.
To open the SAML-based single sign-on testing experience, go to Test single sign-on (step 5). If the Test button is greyed out, you need to fill out and save the required attributes first in the Basic SAML Configuration section.
In the Test single sign-on blade, use your corporate credentials to sign in to the target application. You can sign in as the current user or as a different user. If you sign in as a different user, a prompt will ask you to authenticate.
If you are successfully signed in, the test has passed. In this case, Azure AD issued a SAML response token to the application. The application used the SAML token to successfully sign you in.
If you have an error on the company sign-in page or the application's page, use one of the next sections to resolve the error.
Resolve a sign-in error on your company sign-in page
When you try to sign in, you might see an error on your company sign-in page that's similar to the following example.
To debug this error, you need the error message and the SAML request. The My Apps Secure Sign-in Extension automatically gathers this information and displays resolution guidance on Azure AD.
To resolve the sign-in error with the My Apps Secure Sign-in Extension installed
- When an error occurs, the extension redirects you back to the Azure AD Test single sign-on blade.
- On the Test single sign-on blade, select Download the SAML request.
- You should see specific resolution guidance based on the error and the values in the SAML request.
- You will see a Fix it button to automatically update the configuration in Azure AD to resolve the issue. If you don't see this button, then the sign-in issue is not due to a misconfiguration on Azure AD.
If no resolution is provided for the sign-in error, we suggest that you use the feedback textbox to inform us.
To resolve the error without installing the My Apps Secure Sign-in Extension
- Copy the error message at the bottom right corner of the page. The error message includes:
- A CorrelationID and Timestamp. These values are important when you create a support case with Microsoft because they help the engineers to identify your problem and provide an accurate resolution to your issue.
- A statement identifying the root cause of the problem.
- Go back to Azure AD and find the Test single sign-on blade.
- In the text box above Get resolution guidance, paste the error message.
- Click Get resolution guidance to display steps for resolving the issue. The guidance might require information from the SAML request or SAML response. If you’re not using the My Apps Secure Sign-in Extension, you might need a tool such as Fiddler to retrieve the SAML request and response.
- Verify that the destination in the SAML request corresponds to the SAML Single Sign-On Service URL obtained from Azure AD.
- Verify the issuer in the SAML request is the same identifier you have configured for the application in Azure AD. Azure AD uses the issuer to find an application in your directory.
- Verify AssertionConsumerServiceURL is where the application expects to receive the SAML token from Azure AD. You can configure this value in Azure AD, but it’s not mandatory if it’s part of the SAML request.
Resolve a sign-in error on the application page
You might sign in successfully and then see an error on the application's page. This occurs when Azure AD issued a token to the application, but the application does not accept the response.
To resolve the error, follow these steps:
If the application is in the Azure AD Gallery, verify that you've followed all the steps for integrating the application with Azure AD. To find the integration instructions for your application, see the list of SaaS application integration tutorials.
Retrieve the SAML response.
- If the My Apps Secure Sign-in extension is installed, from the Test single sign-on blade, click download the SAML response.
- If the extension is not installed, use a tool such as Fiddler to retrieve the SAML response.
Notice these elements in the SAML response token:
User unique identifier of NameID value and format
Claims issued in the token
Certificate used to sign the token.
For more information on the SAML response, see Single Sign-on SAML protocol.
Now that you have reviewed the SAML response, see Error on an application's page after signing in for guidance on how to resolve the problem.
If you're still not able to sign in successfully, you can ask the application vendor what is missing from the SAML response.
Now that single sign-on is working to your application, you could Automate user provisioning and de-provisioning to SaaS applications or get started with Conditional Access.