Tutorial: Azure Active Directory single sign-on integration with SharePoint on-premises

In this tutorial, you learn how to integrate SharePoint on-premises with Azure Active Directory (Azure AD). When you integrate SharePoint on-premises with Azure AD, you can:

  • Control who has access to SharePoint on-premises in Azure AD.
  • Enable your users to be automatically signed in to SharePoint on-premises with their Azure AD accounts.
  • Manage your accounts in the Azure portal.

To learn more about software as a service (SaaS) app integration with Azure AD, see What is application access and single sign-on with Azure Active Directory?.

Prerequisites

To configure Azure AD integration with SharePoint on-premises, you need these items:

  • An Azure AD subscription. If you don't have an Azure AD environment, you can get a free account.
  • A SharePoint 2013 farm or newer.

Scenario description

In this tutorial, you configure and test Azure AD single sign-on (SSO) in a test environment. Users from Azure AD are able to access your SharePoint on-premises.

Create enterprise applications in the Azure portal

To configure the integration of SharePoint on-premises into Azure AD, you need to add SharePoint on-premises from the gallery to your list of managed SaaS apps.

To add SharePoint on-premises from the gallery:

  1. In the Azure portal, on the leftmost pane, select Azure Active Directory.

    Note

    If the element isn't available, you can also open it through the All services link at the top of the leftmost pane. In the following overview, the Azure Active Directory link is located in the Identity section. You can also search for it by using the filter box.

  2. Go to Enterprise applications, and then select All applications.

  3. To add a new application, select New application at the top of the dialog box.

  4. In the search box, enter SharePoint on-premises. Select SharePoint on-premises from the result pane.

    SharePoint on-premises in the results list

  5. Specify a name for your SharePoint on-premises instance, and select Add to add the application.

  6. In the new enterprise application, select Properties, and check the value for User assignment required?.

    User assignment required? toggle

    In this scenario, the value is set to No.

Configure and test Azure AD

In this section, you configure Azure AD SSO with SharePoint on-premises. For SSO to work, you establish a link relationship between an Azure AD user and the related user in SharePoint on-premises.

To configure and test Azure AD SSO with SharePoint on-premises, complete these building blocks:

Configure Azure AD single sign-on

In this section, you enable Azure AD SSO in the Azure portal.

To configure Azure AD SSO with SharePoint on-premises:

  1. In the Azure portal, select Azure Active Directory > Enterprise applications. Select the previously created enterprise application name, and select Single sign-on.

  2. In the Select a Single sign-on method dialog box, select the SAML mode to enable SSO.

  3. On the Set up Single Sign-On with SAML page, select the Edit icon to open the Basic SAML Configuration dialog box.

  4. In the Basic SAML Configuration section, follow these steps:

    SharePoint on-premises domain and URLs SSO information

    1. In the Identifier box, enter a URL by using this pattern: urn:<sharepointFarmName>:<federationName>.

    2. In the Reply URL box, enter a URL by using this pattern: https://<YourSharePointSiteURL>/_trust/.

    3. In the Sign on URL box, enter a URL by using this pattern: https://<YourSharePointSiteURL>/.

    4. Select Save.

    Note

    These values aren't real. Update these values with the actual sign-on URL, identifier, and reply URL.

  5. On the Set up Single Sign-On with SAML page, in the SAML Signing Certificate section, select Download to download the Certificate (Base64) from the given options based on your requirements and save it on your computer.

    The certificate download link

  6. In the Set up SharePoint on-premises section, copy the appropriate URLs based on your requirement:

    Note

    This URL can't be used as is in SharePoint. You must replace /saml2 with /wsfed. The SharePoint on-premises application uses a SAML 1.1 token, so Azure AD expects a WS Fed request from the SharePoint server. After authentication, it issues the SAML 1.1 token.

Configure SharePoint on-premises

  1. Create a new trusted identity provider in SharePoint Server 2016.

    Sign in to the SharePoint server, and open the SharePoint Management Shell. Fill in the values:

    • $realm is the identifier value from the SharePoint on-premises domain and URLs section in the Azure portal.
    • $wsfedurl is the SSO service URL.
    • $filepath is the file path to which you have downloaded the certificate file from the Azure portal.

    Run the following commands to configure a new trusted identity provider.

    Tip

    If you're new to using PowerShell or want to learn more about how PowerShell works, see SharePoint PowerShell.

    $realm = "urn:sharepoint:sps201x"
    $wsfedurl="https://login.microsoftonline.com/2c4f1a9f-be5f-10ee-327d-a95dac567e4f/wsfed"
    $filepath="C:\temp\SharePoint 2019 OnPrem.cer"
    $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($filepath)
    New-SPTrustedRootAuthority -Name "AzureAD" -Certificate $cert
    $map1 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" -IncomingClaimTypeDisplayName "name" -LocalClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
    $map2 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming
    $ap = New-SPTrustedIdentityTokenIssuer -Name "AzureAD" -Description "Azure AD SharePoint server 201x" -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map1,$map2 -SignInUrl $wsfedurl -IdentifierClaim $map1.InputClaimType
    
  2. Enable the trusted identity provider for your application.

    1. In Central Administration, go to Manage Web Application and select the web application that you want to secure with Azure AD.

    2. On the ribbon, select Authentication Providers and choose the zone that you want to use.

    3. Select Trusted Identity provider, and select the identify provider you just registered named AzureAD.

    4. Select OK.

    Configuring your authentication provider

Create an Azure AD test user in the Azure portal

The objective of this section is to create a test user in the Azure portal.

  1. In the Azure portal, on the leftmost pane, select Azure Active Directory. In the Manage pane, select Users.

  2. Select All users > New user at the top of the screen.

  3. Select Create User, and in the user properties, follow these steps. You might be able to create users in your Azure AD by using your tenant suffix or any verified domain.

    1. In the Name box, enter the user name. We used TestUser.

    2. In the User name box, enter TestUser@yourcompanydomain.extension. This example shows TestUser@contoso.com.

      The User dialog box

    3. Select the Show password check box, and then write down the value that appears in the Password box.

    4. Select Create.

    5. You can now share the site with TestUser@contoso.com and permit this user to access it.

Create an Azure AD security group in the Azure portal

  1. Select Azure Active Directory > Groups.

  2. Select New group.

  3. Fill in the Group type, Group name, Group description, and Membership type boxes. Select the arrows to select members, and then search for or select the members you want to add to the group. Choose Select to add the selected members, and then select Create.

Create an Azure AD security group

Grant permissions to an Azure AD account in SharePoint on-premises

To grant access to an Azure AD user in SharePoint on-premises, share the site collection or add the Azure AD user to one of the site collection's groups. Users can now sign in to SharePoint 201x by using identities from Azure AD, but there are still opportunities for improvement to the user experience. For instance, searching for a user presents multiple search results in the people picker. There's a search result for each of the claims types that are created in the claim mapping. To choose a user by using the people picker, you must enter their user name exactly and choose the name claim result.

Claims search results

There's no validation on the values you search for, which can lead to misspellings or users accidentally choosing the wrong claim type. This situation can prevent users from successfully accessing resources.

To fix this scenario with the people picker, an open-source solution called AzureCP provides a custom claims provider for SharePoint 2013, 2016, and 2019. It uses the Microsoft Graph API to resolve what users enter and perform validation. For more information, see AzureCP.

Note

Without AzureCP, you can add groups by adding the Azure AD group's ID, but this method isn't user friendly and reliable. Here's how it looks:

Add an Azure AD group to a SharePoint group

Grant permissions to an Azure AD group in SharePoint on-premises

To assign Azure AD security groups to SharePoint on-premises, it's necessary to use a custom claims provider for SharePoint server. This example uses AzureCP.

Note

AzureCP isn't a Microsoft product and isn't supported by Microsoft Support. To download, install, and configure AzureCP on the on-premises SharePoint farm, see the AzureCP website.

  1. Configure AzureCP on the SharePoint on-premises farm or an alternative custom claims provider solution. To configure AzureCP, see this AzureCP website.

  2. In the Azure portal, select Azure Active Directory > Enterprise applications. Select the previously created enterprise application name, and select Single sign-on.

  3. On the Set up Single Sign-On with SAML page, edit the User Attributes & Claims section.

  4. Select Add a group claim.

  5. Select which groups associated with the user should be returned in the claim. In this case, select All groups. In the Source attribute section, select Group ID and select Save.

To grant access to the Azure AD security group in SharePoint on-premises, share the site collection or add the Azure AD security group to one of the site collection's groups.

  1. Browse to SharePoint Site Collection. Under Site Settings for the site collection, select People and groups.

  2. Select the SharePoint group, and then select New > Add Users to this Group. As you type the name of your group, the people picker displays the Azure AD security group.

    Add an Azure AD group to a SharePoint group

Grant access to a guest account to SharePoint on-premises in the Azure portal

You can grant access to your SharePoint site to a guest account in a consistent way because the UPN now gets modified. For example, the user jdoe@outlook.com is represented as jdoe_outlook.com#ext#@TENANT.onmicrosoft.com. To share your site with external users, you need to add some modifications in your User Attributes & Claims section in the Azure portal.

  1. In the Azure portal, select Azure Active Directory > Enterprise applications. Select the previously created enterprise application name, and select Single sign-on.

  2. On the Set up Single Sign-On with SAML page, edit the User Attributes & Claims section.

  3. In the Required claim zone, select Unique User Identifier (Name ID).

  4. Change the Source Attribute property to the value user.localuserprincipalname, and select Save.

    User Attributes & Claims initial

  5. Using the ribbon, go back to SAML-based Sign-on. Now the User Attributes & Claims section looks like this:

    User Attributes & Claims final

    Note

    A surname and given name aren't required in this setup.

  6. In the Azure portal, on the leftmost pane, select Azure Active Directory and then select Users.

  7. Select New Guest User.

  8. Select the Invite User option. Fill in the user properties, and select Invite.

  9. You can now share the site with MyGuestAccount@outlook.com and permit this user to access it.

    Sharing a site with a guest account

Configure the trusted identity provider for multiple web applications

The configuration works for a single web application, but additional configuration is needed if you intend to use the same trusted identity provider for multiple web applications. For example, assume you extended a web application to use the URL https://sales.contoso.com and you now want to authenticate users to https://marketing.contoso.com. To do this, update the identity provider to honor the WReply parameter and update the application registration in Azure AD to add a reply URL.

  1. In the Azure portal, select Azure Active Directory > Enterprise applications. Select the previously created enterprise application name, and select Single sign-on.

  2. On the Set up Single Sign-On with SAML page, edit Basic SAML Configuration.

    Basic SAML Configuration

  3. For Reply URL (Assertion Consumer Service URL), add the URL for the additional web applications and select Save.

    Edit the basic SAML configuration

  4. On the SharePoint server, open the SharePoint 201x Management Shell and run the following commands. Use the name of the trusted identity token issuer that you used previously.

     $t = Get-SPTrustedIdentityTokenIssuer "AzureAD"
     $t.UseWReplyParameter=$true
     $t.Update()
    
  5. In Central Administration, go to the web application and enable the existing trusted identity provider.

You might have other scenarios where you want to give access to your SharePoint on-premises instance for your internal users. For this scenario, you have to deploy Microsoft Azure Active Directory Connect to permit syncing your on-premises users with Azure AD. This setup is discussed in another article.

Additional resources