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

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.

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, 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:https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml.For Chinese customers using China-specific Microsoft 365 instances, the following federation endpoint should be used:https://nexus.partner.microsoftonline-p.cn/federationmetadata/saml20/federationmetadata.xml.

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:

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.

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.

 urn:federation:MicrosoftOnline  

Below is a sample response message sent to Azure AD/Microsoft 365 from a sample SAML 2.0 compliant identity provider.

 http://WS2012R2-0.contoso.com/adfs/services/trust     http://WS2012R2-0.contoso.com/adfs /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     administrator@contoso.com     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 inhttps://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml.

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

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.

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 "onmicrosoft.com". 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.

Configure domains in the Azure AD directory for federation

1. Connect to your Azure AD directory as a tenant administrator:

Connect to MsolService

2. Configure the required Microsoft 365 domains to use SAML 2.0 federation:

$dom = "contoso.com" $BrandName = "示例 SAML 2.0 IDP" $LogOnUrl = "https://WS2012R2-0.contoso.com/passiveLogon" $LogOffUrl = "https://WS2012R2-0.contoso.com /passiveLogOff" $ecpUrl = "https://WS2012R2-0.contoso.com/PAOS" $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 = " http://WS2012R2-0.contoso.com/adfs/services/trust" $Protocol = "SAMLP" Set-MsolDomainAuthentication ` -DomainName $dom ` -FederationBrandName $BrandName ` -Authentication Federated ` -PassiveLogOnUri $LogOnUrl ` -ActiveLogOnUri $ ecpUrl ` -SigningCertificate $MySigningCert ` -IssuerUri $MyURI ` -LogOffUri $LogOffUrl ` -PreferredAuthenticationProtocol $Protocol

3. 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).

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 elwoodf1@contoso.com ` -ImmutableId ABCDEFG1234567890 ` -DisplayName "Elwood Folk" ` -FirstName Elwood ` -LastName Folk ` -AlternateEmailAddresses "Elwood.Folk@contoso.com" ` -UsageLocation "US"

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

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.

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.

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:

   

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.

   

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.

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