Azure AD Connect: Single Sign-On with SAML 2.0 Identity Provider - Azure - Microsoft Entra (2023)

  • article

This document contains information on using a SAML 2.0 compliant SP-Lite profile-based identity provider as the preferred Security Token Service (STS)/Identity Provider. This scenario is useful when you already have a local user directory and password store that can be accessed using SAML 2.0. This existing user directory can be used to sign in to Microsoft 365 and other Azure AD-secured resources. SAML 2.0 SP-Lite profiles are based on the widely used Security Assertion Markup Language (SAML) federated identity standard to provide a login and attribute exchange framework.


For a list of 3rd party Idps that have been tested for use with Azure AD, seeAzure AD Federation Compatibility Matrix

Microsoft supports this sign-in experience because Microsoft cloud services, such as Microsoft 365, integrate with properly configured SAML 2.0 profile-based IdPs. SAML 2.0 identity providers are third-party products, so Microsoft does not provide support for their deployment, configuration, and troubleshooting best practices. Once properly configured, the integration with the SAML 2.0 identity provider can be tested using the Microsoft Connectivity Analyzer Tool, described in more detail below. For more information on identity providers based on SAML 2.0 SP-Lite profiles, please consult the organization that provides it.


In this login scenario using a SAML 2.0 identity provider, only a limited set of clients are available, including:

  • Web-based clients such as Outlook Web Access and SharePoint Online
  • Rich email clients using basic authentication and supported Exchange access methods (such as IMAP, POP, Active Sync, MAPI, etc.) (requires deployment of Enhanced Client Protocol endpoints), including:
    • Microsoft Outlook 2010/Outlook 2013/Outlook 2016, Apple iPhone (various iOS versions)
    • Various Google Android devices
    • Windows Phone 7、Windows Phone 7.8 和 Windows Phone 8.0
    • Windows 8 mail client and Windows 8.1 mail client
    • Windows 10 mail client

In this login scenario using a SAML 2.0 identity provider, all other clients are unavailable. For example, a Lync 2010 desktop client cannot log in to a service using a SAML 2.0 identity provider configured for single sign-on.

Azure AD SAML 2.0 protocol requirements

This document contains detailed requirements on the protocols and message formats that your SAML 2.0 identity provider must implement in order to federate with Azure AD to enable sign-in to one or more Microsoft cloud services (such as Microsoft 365). The SAML 2.0 relying party (SP-STS) for the Microsoft cloud service used in this scenario is Azure AD.

It is recommended that you ensure that your SAML 2.0 identity provider output messages resemble the example trace provided as closely as possible. Also, use specific attribute values ​​from the provided Azure AD metadata where possible. Once you are satisfied with the output message, you can test it using the Microsoft Connectivity Analyzer as described below.

The Azure AD metadata can be downloaded from this URL: Chinese customers using China-specific Microsoft 365 instances, the following federation endpoint should be used:

SAML protocol requirements

This section details how to put together request and response message pairs to help you format your messages properly.

Azure AD can be configured to work with identity providers that use the SAML 2.0 SP Lite profile and meet some specific requirements listed below. Using sample SAML request and response messages and automated and manual testing, you can work towards interoperability with Azure AD.

signature block requirements

In a SAML response message, the signing node contains information about the digital signature of the message itself. Signature blocks have the following requirements:

  1. The assertion node itself must be signed
  2. The RSA-sha1 algorithm must be used as the DigestMethod. Other digital signature algorithms are not accepted.
  3. You can also sign XML documents.
  4. The conversion algorithm must match the values ​​in the following examples:
  5. The SignatureMethod algorithm must match the following examples:


For increased security, the SHA-1 algorithm is deprecated. Make sure to use a more secure algorithm such as SHA-256. More informationcan be found.

Supported Bindings

Bindings are required transport-related communication parameters. The following requirements apply to binding

  1. HTTPS is a required transport.
  2. Azure AD will require an HTTP POST to submit the token during login.
  3. Azure AD will use HTTP POST to make an authentication request to the identity provider and REDIRECT to send a logout message to the identity provider.

required attribute

This table shows the requirements for specific attributes in SAML 2.0 messages.

Name IDThe value of this assertion must be the same as the Azure AD user's ImmutableID. It can contain up to 64 alphanumeric characters. Any non-html-safe characters must be encoded, for example the '+' character is displayed as '.2B'.
IDPE mailboxThe User Principal Name (UPN) is listed in the SAML response as the UserPrincipalName (UPN) of the user in Azure AD/Microsoft 365 with an element named IDPEmail. The UPN is in the format of an email address. UPN value in Windows Microsoft 365 (Azure Active Directory).
IssuerMust be the URI of an identity provider. Do not reuse the Issuer in the sample message. If you have multiple top-level domains in your Azure AD tenant, the Issuer must match the specified URI setting for each domain configuration.


Azure AD currently supports the following NameID format URI for SAML 2.0: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

Sample SAML request and response messages

Shows the request and response message pairs used for the login message exchange. The following is a sample request message sent from Azure AD to a sample SAML 2.0 identity provider. An example SAML 2.0 identity provider is Active Directory Federation Services (AD FS) configured to use the SAML-P protocol. Interoperability testing with other SAML 2.0 identity providers has also been done.


Below is a sample response message sent to Azure AD/Microsoft 365 from a sample SAML 2.0 compliant identity provider. /services/trust    < ds:Reference URI="#_7e3c1bcd-f180-4f78-83e1-7680920793aa">     CBn/5YqbheaJP425c0pHva9PhNY=   TciWMyHW2ZODrh/2xrvp5ggmcHBFEd9 vrp6DYXp +hZWJzmXMmzwmwS8KNRJKy8H7XqBsdELA1Msqi8I3TmWdnoIRfM/ZAyUppo8suMu6Zw+boE32hoQRnX9EWN/f0vH6zA/YKTzrjca6JQ8gAV1ErwvRWDpyMcwdYCiWALv9ScbkAcebO E1s1JctZ5RBXggdZWrYi72X+I4i6WgyZcIGai/rZ4v2otoWAEHS0y1yh1qT7NDPpl/McDaTGkNU6C+8VfjD78DrUXEcAfKvPgKlKrOMZnD1lCGsViimGY+LSuIdY45MLmyaa5UT4KWph6dA==   MIIC7jCCAdagAwIBAgIQRrjsbFPaXIlOG3GTv50fkjANBgkqhkiG9w0BAQsFADAzMTEwLwYDVQQDEyhBREZTIFNpZ25pbmcgLSBXUzIwMTJSMi0wLnN3a W5mb3JtZXIuY29tMB4XDTE0MDEyMDE1MTY0MFoXDTE1MDEyMDE1MTY0MFowMzExMC8GA1UEAxMoQURGUyBTaWduaW5nIC0gV1MyMDEyUjItMC5zd2luZm9ybWVyLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEP ADCCAQoCggEBAKe+rLVmXy1QwCwZwqgbbp1/+3ZWxd9T/jV0hpLIIWr+LCOHqq8n8beJvlivgLmDJo8f+EITnAxWcsJUvVai/35AhHCUq9tc9sqMp5PWtabAEMb2AU72/QlX/72D2/NbGQ q1BWYbqUpgpCZ2nSgvlWDHlCiUo//UGsvfox01kjTFlmqQInsJVfRxF5AcCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAi8c6C4zaTEc7aQiUgvnGQgCbMZbhUXXLGRpjvFLKaQzkwa9eq7WLJibc SNyGXBa/SfT5wJgsm3TPKgSehGAOTirhcqHheZyvBObAScY7GOT+u9pVYp6raFrc7ez3c+CGHeV/tNvy1hJNs12FYH4X+ZCNFIT9tprieR25NCdi5SWUbPZL0tVzJsHc1y92b2M2FxqRDohxQgJ vyJOpcg2mSBzZZIkvDg7gfPSUXHVS1MQs0RHSbwq/XdQocUUhl9/e/YWCbNNxlM84BxFsBUok1dH /gzBySx+Fc8zYi7cOq9yaBT3RLT6cGmFGVYZJW4FyhPZOCLVNsLlnPQcX3dDg9A==     ABCDEG1234567890       urn:federation:MicrosoftOnline     urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport    

Configure a SAML 2.0-compliant identity provider

This section contains guidance on how to configure a SAML 2.0 identity provider to federate with Azure AD to enable single sign-on access to one or more Microsoft cloud services, such as Microsoft 365, using the SAML 2.0 protocol. The SAML 2.0 relying party for the Microsoft cloud service used in this scenario is Azure AD.

Your SAML 2.0 identity provider needs to honor information about Azure AD relying parties. Azure AD publishes metadata in

It is recommended that you always import the latest Azure AD metadata when configuring a SAML 2.0 identity provider.


Azure AD does not read metadata from identity providers.

Add Azure AD as a relying party

You must enable communication between the SAML 2.0 identity provider and Azure AD. This configuration will depend on your particular identity provider, and you should refer to its documentation. You would typically set the relying party ID to be the same as the entity ID in the Azure AD metadata.


Verify that the clock on the SAML 2.0 identity provider server is synchronized with an accurate time source. Inaccurate clock time can cause federated logins to fail.

Install Windows PowerShell to log in with a SAML 2.0 identity provider

After configuring the SAML 2.0 identity provider for Azure AD login, the next step is to download and install the Azure Active Directory Module for Windows PowerShell. After installation, you'll use these cmdlets to configure your Azure AD domain as a federated domain.

The Azure Active Directory Module for Windows PowerShell is a download for managing organizational data in Azure AD. This module installs a set of cmdlets into Windows PowerShell; you run these cmdlets to set up single sign-on access to Azure AD and, in turn, to all cloud services you subscribe to. For instructions on how to download and install the cmdlets , see/previous-versions/azure/jj151815(v=azure.100)

Establish trust between SAML identity provider and Azure AD

Before you can configure federation on an Azure AD domain, it must configure a custom domain. You cannot federate the default domain provided by Microsoft. Microsoft's default domain ends with "". You will run a series of cmdlets in the Windows PowerShell command-line interface to add or switch domains for single sign-on.

Each Azure Active Directory domain that is to be federated using the SAML 2.0 identity provider must be added as a single sign-on domain or converted from a standard domain to a single sign-on domain. Adding or converting a domain establishes trust between the SAML 2.0 identity provider and Azure AD.

The following procedure walks you through converting an existing standard domain to a federated domain using SAML 2.0 SP-Lite.


After performing this step, your domain may experience an outage affecting users for up to 2 hours.

Configure domains in the Azure AD directory for federation

  1. Connect to your Azure AD directory as a tenant administrator:
Connect to MsolService
  1. Configure the required Microsoft 365 domains to use SAML 2.0 federation:
$dom = "" $BrandName = "示例 SAML 2.0 IDP" $LogOnUrl = "" $LogOffUrl = " /passiveLogOff" $ecpUrl = "" $MyURI = "urn:uri:MySamlp2IDP" $MySigningCert = "MIIC7jCCAdagAwIBAgIQRrjsbFPaXIlOG3GTv50fkjANBgkqhkiG9w0BAQsFADAzMTEwLw YDVQQDEyh BREZTIFNpZ25pbmcgLSBXUzIwMTJSMi0wLnN3aW5mb3JtZXIuY29tMB4XDTE0MDEyMDE1MTY0MFoXDT E1MDEyMDE1MTY0MFowMzExMC8GA1UEAxMoQURGUyBTaWduaW5nIC0gV1MyMDEyUjItMC5 zd2luZm9yb WVyLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKe+rLVmXy1QwCwZwqgbbp1/kupQ VcjKuKLitVDbssFyqbDTjP7WRjlVMWAHBI3kgNT7oE362Gf2WMJFf1b0H crsgLin7daRXpq4Qi6OA57 sW1YFMj3sqyuTP0eZV3S4+ZbDVob6amsZIdIwxaLP9Zfywg2bLsGnVldB0+XKedZwDbCLCVg+ 3ZWxd9 T/jV0hpLIIWr+LCOHqq8n8beJvlivgLmDJo8f+EITnAxWcsJUvVai/35AhHCUq9tc9sqMp5PWtabAEM b2AU72/QlX/72D2/NbGQq1BWYbqUpgpCZ2nSgvlWDHlCiUo//UGs vfox01kjTFlmqQInsJVfRxF5AcC AwEAATANBgkqhkiG9w0BAQsFAAOCAQEAi8c6C4zaTEc7aQiUgvnGQgCbMZbhUXXLGRpjvFLKaQzkwa9 eq7WLJibcSNyGXBa/SfT5wJgsm3TPKgSehGAOTirhcqH heZyvBObAScY7GOT+u9pVYp6raFrc7ez3c+ CGHeV/tNvy1hJNs12FYH4X+ZCNFIT9tprieR25NCdi5SWUbPZL0tVzJsHc1y92b2M2FxqRDohxQgJvy JOpcg2mSBzZIkvDg7gfPSUXHVS1MQ s0RHSbwq/XdQocUUhl9/e/YWCbNNxlM84BxFsBUok1dH/gzBy Sx+Fc8zYi7cOq9yaBT3RLT6cGmFGVYZJW4FyhPZOCLVNsLlnPQcX3dDg9A==" $uri = "" $Protocol = "SAMLP" Set-MsolDomainAuthentication ` -DomainName $dom ` -FederationBrandName $BrandName ` -Authentication Federated ` -PassiveLogOnUri $LogOnUrl ` -ActiveLogOnUri $ ecpUrl ` -SigningCertificate $MySigningCert ` -IssuerUri $MyURI ` -LogOffUri $LogOffUrl ` -PreferredAuthenticationProtocol $Protocol
  1. You can get the base64 encoded string of the signing certificate from the IDP metadata file. An example of this location is provided, but your implementation may vary slightly.
    MIIC5jCCAc6gAwIBAgIQLnaxUPzay6ZJsC8HVv/QfTANBgkqhkiG9w0BAQsFADAvMS0wKwYDVQQDEyRBREZTIFNpZ25pbmcgLSBmcy50ZWNobGFiY2VudHJhbC5vcmcwH hcNMTMxMTA0MTgxMzMyWhcNMTQxMTA0MTgxMzMyWjAvMS0wKwYDVQQDEyRBREZTIFNpZ25pbmcgLSBmcy50ZWNobGFiY2VudHJhbC5vcmcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCwMd VLTr5YTSRp+ccbSpuuFeXMfABD9mVCi2wtkRwC30TIyPdORz642MkurdxdPCWjwgJ0HW6TvXwcO9afH3OC5V//wEGDoNcI8PV4enCzTYFe/h//w51uqyv48Fbb3lEXs+aVl8155OAj2sO9IX6 4OJWKey82GQWK3g7LfhWWpp17j5bKpSd9DBH5pvrV+Q1ESU3mx71TEOvikHGCZYitEPywNeVMLRKrevdWI3FAhFjcCSO6nWDiMqCqiTDYOURXIcHVYTSof1YotkJ4tG6mP5Kpjzd4VQvnR7Pjb 47nhIYG6iZ3mR1F85Ns9+hBWukQWNN2hcD/uGdPXhpdMVpBAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAK7h7jF7wPzhZ1dPl4e+XMAr8I7TNbhgEU3+oxKyW/IioQbvZVw1mYVCbGq9R sw4KE06eSMybqHln3w5EeBbLS0MEkApqHY+p68iRpguqa+W7UHKXXQVgPMCpqxMFKonX6VlSQOR64FgpBme2uG+LJ8reTgypEKspQIN0WvtPWmiq4zAwBp08hAacgv868c0MM4WbOYU0rz MIR6Q+ceGVRImlCwZ5b7XKp4mJZ9hlaRjeuyVrDuzBkzROSurX1OXoci08yJvhbtiBJLf3uPOJHrhjKRwIt2TnzS9ElgFZlJiDIA26Athe73n43CT0af2IG6yC7e6sK4L3NEXJrwwUZk=   

For more information about 'Set-MsolDomainAuthentication', see:/previous-versions/azure/dn194112(v=azure.100).


you must use$ecpUrl = ""Only if you set the ECP extension for the identity provider. Exchange Online clients (excluding Outlook Web App (OWA)) rely on a POST-based activity endpoint. If your SAML 2.0 STS implementation has an ECP implementation of an active endpoint similar to Shibboleth's active endpoint, these rich clients may interact with Exchange Online services.

Once federation is configured, you can switch back to "non-federated" (or "managed"), but this change takes up to two hours to complete and requires each user to be assigned a new random password for cloud-based login. In some cases it may be necessary to switch back to "Managed" to reset errors in the settings. For more information on domain transitions, see:/previous-versions/azure/dn194122(v=azure.100).

Provide user principals to Azure AD / Microsoft 365

Before you can authenticate your users to Microsoft 365, you must provision Azure AD with a user principal corresponding to the assertion in the SAML 2.0 assertion. If these user principals are not known to Azure AD in advance, they cannot be used for federated login. Either Azure AD Connect or Windows PowerShell can be used to provision user principals.

Azure AD Connect can be used to provision principals for domains in Azure AD Directory from on-premises Active Directory. For more details, seeIntegrate on-premises directories with Azure Active Directory.

Windows PowerShell can also be used to automatically add new users to Azure AD and synchronize changes in the on-premises directory. To use the Windows PowerShell cmdlets, you must download theAzure Active Directory Module.

This procedure demonstrates how to add a single user to Azure AD.

  1. Connect to the Azure AD directory as a tenant administrator: Connect-MsolService.

  2. Create a new user principal:

    New-MsolUser ` -UserPrincipalName ` -ImmutableId ABCDEFG1234567890 ` -DisplayName "Elwood Folk" ` -FirstName Elwood ` -LastName Folk ` -AlternateEmailAddresses "" ` -UsageLocation "US"

For more information on the "New-MsolUser" checkout,/previous-versions/azure/dn194096(v=azure.100)


The "UserPrincipalName" value must match what you would send in the SAML 2.0 assertion for "IDPEmail" and the "ImmutableID" value must match what you would send in the "NameID" assertion.

Authenticating single sign-on using SAML 2.0 IDP

As an administrator, before authenticating and managing single sign-on (also known as identity federation), review the information and follow the steps in the following articles to set up single sign-on with a SAML 2.0 SP-Lite-based identity provider:

  1. You have reviewed the Azure AD SAML 2.0 protocol requirements
  2. You have configured a SAML 2.0 Identity Provider
  3. Install Windows PowerShell for single sign-on with a SAML 2.0 identity provider
  4. Establish trust between SAML 2.0 identity provider and Azure AD
  5. Provision a known test user principal to Azure Active Directory (Microsoft 365) through Windows PowerShell or Azure AD Connect.
  6. Use configuration directory synchronizationAzure AD Connect.

After setting up single sign-on with a SAML 2.0 SP-Lite based identity provider, you should verify that it is working.


If you're converting your domain instead of adding it, it can take up to 24 hours for single sign-on to be set up. Before authenticating single sign-on, you should complete Active Directory synchronization setup, synchronize directories, and activate your synchronization users.

Use this tool to verify that single sign-on is set up correctly

To verify that single sign-on is set up correctly, you can perform the following procedure to confirm that you are able to log in to the cloud service using your corporate credentials.

Microsoft provides a tool that you can use to test SAML 2.0-based identity providers. Before running the test harness, you must configure an Azure AD tenant to federate with your identity provider.


Connectivity Analyzer requires Internet Explorer 10 or later.

  1. downloadConnectivity Analyzer.

  2. Click Install Now to start downloading and installing the tool.

  3. Select "I can't set up federation with Office 365, Azure, or other services that use Azure Active Directory."

  4. After downloading and running the tool, you will see the connection diagnostic window. The tool walks you step-by-step through testing a federated connection.

  5. Connectivity Analyzer will open your SAML 2.0 IDP for you to log in, enter the credentials of the user principal you are testing:

    Azure AD Connect: Single Sign-On with SAML 2.0 Identity Provider - Azure - Microsoft Entra (1)

  6. On the Federation Test Login window, you should enter the account name and password for the Azure AD tenant configured to federate with your SAML 2.0 identity provider. The tool will attempt to log in using these credentials, and detailed results of the tests performed during the login attempt will be provided as output.

    Azure AD Connect: Single Sign-On with SAML 2.0 Identity Provider - Azure - Microsoft Entra (2)

  7. This window shows the results of failed tests. Clicking Review detailed results will display information about the results of each test that has been performed. You can also save the results to disk for sharing.


Connectivity analyzer also tests Active Federation using WS* and ECP/PAOS based protocols. If you don't use these, you can ignore the error: Test the active login flow with the identity provider's active federation endpoint.

Manually verify that single sign-on is set up correctly

Manual authentication provides additional steps that you can take to ensure that your SAML 2.0 identity provider works correctly in many situations. To verify that single sign-on is set up correctly, complete the following steps:

  1. On a domain-joined computer, log in to your cloud service using the same login you use with your company credentials.
  2. Click inside the password box. If Single Sign-On is set up, the password box will be grayed out and you will see the following message: "You now need to log in at ."
  3. Click the "Sign in at " link. If you are able to log in, then single sign-on is set.

Next step

  • Active Directory Federation Services management and customization using Azure AD Connect
  • Azure AD Federation Compatibility Matrix
  • Azure AD Connect custom installation
Top Articles
Latest Posts
Article information

Author: Catherine Tremblay

Last Updated: 02/24/2023

Views: 6283

Rating: 4.7 / 5 (47 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Catherine Tremblay

Birthday: 1999-09-23

Address: Suite 461 73643 Sherril Loaf, Dickinsonland, AZ 47941-2379

Phone: +2678139151039

Job: International Administration Supervisor

Hobby: Dowsing, Snowboarding, Rowing, Beekeeping, Calligraphy, Shooting, Air sports

Introduction: My name is Catherine Tremblay, I am a precious, perfect, tasty, enthusiastic, inexpensive, vast, kind person who loves writing and wants to share my knowledge and understanding with you.