Export (0) Print
Expand All

Configure SAML-based claims authentication with AD FS in SharePoint 2013

 

Applies to: SharePoint Server 2013, SharePoint Foundation 2013

Topic Last Modified: 2014-07-23

Summary: Learn how to configure Security Assertion Markup Language (SAML)-based claims authentication using Active Directory Federation Services version 2.0 (AD FS).

The procedures in this article describe how to configure AD FS to act as an Identity Provider Security Token Service (IP-STS) for a SharePoint 2013 web application. In this configuration, AD FS issues SAML-based security tokens consisting of claims so that client computers can access web applications that use claims-based authentication. You can use an alternative identity provider than AD FS, but it must support the WS-Federation standard.

For information about why you would use SAML-based authentication, see Plan for user authentication methods in SharePoint 2013.

You can use AD FS with the Windows Server 2012, Windows Server 2008, or Windows Server 2008 R2 operating systems to build a federated identity management solution that extends distributed identification, authentication, and authorization services to web-based applications across organization and platform boundaries. By deploying AD FS, you can extend your organization’s existing identity management capabilities to the Internet.

For a version of these procedures that are configured in a standardized test lab, see Test Lab Guide: Demonstrate SAML-based Claims Authentication with SharePoint Server 2013.

Before you begin this operation, you should be familiar with the concepts in the following article:

NoteNote:
Because SharePoint 2013 runs as websites in Internet Information Services (IIS), administrators and users depend on the accessibility features that browsers provide. SharePoint 2013 supports the accessibility features of supported browsers. For more information, see the following resources:

You must install and configure a server that runs AD FS 2.0. For more information, see the AD FS 2.0 Deployment Guide (http://go.microsoft.com/fwlink/p/?LinkId=191723).

This phase has the following procedures:

  1. Configure AD FS for a relying party

  2. Configure the claim rule

  3. Export the token signing certificate

Use the procedure in this section to configure a relying party. The relying party defines how the AD FS recognizes the relying party application and issues claims to it.

To configure AD FS for a relying party
  1. Verify that the user account that is performing this procedure is a member of the Administrators group on the local computer. For additional information about accounts and group memberships, see Understanding Local Users and Groups

  2. On the AD FS server, open the Active Directory Federation Services (AD FS) 2.0 Management console.

  3. In the navigation pane, expand Trust Relationships, and then double-click the Relying Party Trusts folder.

  4. In the right pane, click Add Relying Party Trust.

    This opens the Active Directory Federation Services (AD FS) 2.0 configuration wizard.

  5. On the Welcome to the Add Relying Party Trust Wizard page, click Start.

  6. Select Enter data about the relying party manually, and then click next.

  7. Type a relying party name and then click Next.

  8. Make sure Active Directory Federation Services (AD FS) 2.0 Profile is selected, and then click Next.

  9. Do not use an encryption certificate. Click Next.

  10. Click to select the Enable support for the WS-Federation Passive protocol check box.

  11. In the WS-Federation Passive protocol URL field, type the name of the web application URL, and append /_trust/ (for example, https:// app1.contoso.com/_trust/). Click Next.

    NoteNote:
    The name of the URL has to use Secure Sockets Layer (SSL).
  12. Type the name of the relying party trust identifier (for example, urn:sharepoint:contoso), and then click Add. Click Next. Note that this will be the realm value when you configure a new SPTrustedIdentityTokenIssuer in Phase 3.

  13. Select Permit all users to access this relying party. Click Next.

  14. On the Ready to Add Trust page, there is no action required, click Next.

  15. On the Finish page, click Close. This opens the Rules Editor Management console. Use this console and the next procedure to configure the mapping of claims from your chosen directory source to SharePoint 2013.

Use the procedure in this step to send values of a Lightweight Directory Access Protocol (LDAP) attribute as claims and specify how the attributes will map to the outgoing claim type.

To configure a claim rule
  1. Verify that the user account that is performing this procedure is a member of the Administrators group on the local computer. For additional information about accounts and group memberships, see Default local groups

  2. On the Issuance Transform Rules tab, click Add Rule.

  3. On the Select Rule Template page, select Send LDAP Attributes as Claims. Click Next.

  4. On the Configure Rule page, type the name of the claim rule in the Claim rule name field.

  5. From the Attribute Store drop-down list, select Active Directory.

  6. In the Mapping of LDAP attributes to outgoing claim types section, under LDAP Attribute, select E-Mail-Addresses.

  7. Under Outgoing Claim Type, select E-Mail Address.

  8. Under LDAP Attribute, select User-Principal-Name.

  9. Under Outgoing Claim Type, select UPN.

  10. Click Finish, and then click OK.

Use the procedure in this section to export the token signing certificate of the AD FS server with which you want to establish a trust relationship, and then copy the certificate to a location that SharePoint 2013 can access.

To export a token signing certificate
  1. Verify that the user account that is performing this procedure is a member of the Administrators group on the local computer. For additional information about accounts and group memberships, see Default local groups

  2. On the AD FS server, open the Active Directory Federation Services (AD FS) 2.0 Management console.

  3. In the navigation pane, expand Service, and then click the Certificates folder.

  4. Under Token signing, click the primary token certificate as indicated in the Primary column.

  5. In the right pane, click View Certificate link. This displays the properties of the certificate.

  6. Click the Details tab.

  7. Click Copy to File. This starts the Certificate Export Wizard.

  8. On the Welcome to the Certificate Export Wizard page, click Next.

  9. On the Export Private Key page, click No, do not export the private key, and then click Next.

  10. On the Export File Format page, select DER encoded binary X.509 (.CER), and then click Next.

  11. On the File to Export page, type the name and location of the file that you want to export, and then click Next. For example, enter C:\ADFS.cer.

  12. On the Completing the Certificate Export Wizard page, click Finish.

This phase has the following procedures:

  1. Exporting multiple parent certificates

  2. Import a token signing certificate by using Windows PowerShell

  3. Define a unique identifier for claims mapping by using Windows PowerShell

  4. Create a new authentication provider

To complete the configuration of the AD FS server, copy the .CER file to the computer that is running AD FS.

The token signing certificate may have one or more parent certificates in its chain. If it does, every certificate in that chain has to be added to the SharePoint 2013 list of trusted root authorities.

To determine whether one or more parent certificates exist, follow these steps.

NoteNote:
These steps should be repeated until all certificates are exported up to the root authority certificate.
To export multiple parent certificates
  1. Verify that the user account that is performing this procedure is a member of the Administrators group on the local computer. For additional information about accounts and group memberships, see Default local groups

  2. Open the Active Directory Federation Services (AD FS) 2.0 Management console.

  3. In the navigation pane, expand Service, and then click the Certificates folder.

  4. Under Token signing, click the primary token certificate as indicated in the Primary column.

  5. In the right pane, click View Certificate link. This displays the properties of the certificate.

  6. Click the Certification tab. This displays any other certificate(s) in the chain.

  7. Click the Details tab.

  8. Click Copy to File. This starts the Certificate Export Wizard.

  9. On the Welcome to the Certificate Export Wizard page, click Next.

  10. On the Export Private Key page, click No, do not export the private key, and then click Next.

  11. On the Export File Format page, select DER encoded binary X.509 (.CER), and then click Next.

  12. On the File to Export page, type the name and location of the file that you want to export, and then click Next. For example, enter C:\adfsParent.cer.

  13. On the Completing the Certificate Export Wizard page, click Finish.

Use this section to import the token signing certificates to the trusted root authority list that resides on the SharePoint Server. This step must be repeated for every token signing certificate in the chain until the root certification authority is reached.

To import a token signing certificate by using Windows PowerShell
  1. Verify that you have the following memberships:

    • securityadmin fixed server role on the SQL Server instance.

    • db_owner fixed database role on all databases that are to be updated.

    • Administrators group on the server on which you are running the Windows PowerShell cmdlets.

    • Add memberships that are required beyond the minimums above.

    An administrator can use the Add-SPShellAdmin cmdlet to grant permissions to use SharePoint 2013 Products cmdlets.

    NoteNote:
    If you do not have permissions, contact your Setup administrator or SQL Server administrator to request permissions. For additional information about Windows PowerShell permissions, see Add-SPShellAdmin.
  2. Start the SharePoint 2013 Management Shell.

    • For Windows Server 2008 R2:

      • In the SharePoint 2013 environment, on the Start menu, click All Programs, click Microsoft SharePoint 2013 Products, and then click SharePoint 2013 Management Shell.

    • For Windows Server 2012:

      • In the SharePoint 2013 environment, on the Start screen, click SharePoint 2013 Management Shell.

        If SharePoint 2013 Management Shell is not on the Start screen:

      • Right-click Computer, click All apps, and then click SharePoint 2013 Management Shell.

    For more information about how to interact with Windows Server 2012, see Common Management Tasks and Navigation in Windows Server 2012 R2 and Windows Server 2012.

  3. From the Windows PowerShell command prompt, import the parent certificate of the token signing certificate (that is, the root authority certificate), as shown in the following syntax:

    $root = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("<PathToParentCert>")
    
    New-SPTrustedRootAuthority -Name "Token Signing Cert Parent" -Certificate $root
    
  4. From the Windows PowerShell command prompt, import the token signing certificate that was copied from the AD FS server, as shown in the following syntax:

    $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("<PathToSigningCert>")
    
    New-SPTrustedRootAuthority -Name "Token Signing Cert" -Certificate $cert
    

For additional information about the New-SPTrustedRootAuthority cmdlet, see New-SPTrustedRootAuthority

Use the procedure in this section to define a unique identifier for claims mapping. Typically, this information is in the form of an e-mail address and the administrator of the trusted STS will have to provide this information because only the owner of the STS knows which claim type will be always unique for each user.

To define a unique identifier for claims mapping by using Windows PowerShell
  1. From the Windows PowerShell command prompt, create the email address claim mapping, as shown in the following syntax:

    $emailClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
    
  2. From the Windows PowerShell command prompt, create the UPN claim mapping as shown in the following syntax:

    $upnClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" -IncomingClaimTypeDisplayName "UPN" -SameAsIncoming
    
  3. From the Windows PowerShell command prompt, create the role claim mapping as shown in the following syntax:

    $roleClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming
    

    This claim mapping is used for server-to-server authentication scenarios. For more information, see Plan for server-to-server authentication in SharePoint 2013.

  4. From the Windows PowerShell command prompt, create the Primary SID claim mapping as shown in the following syntax:

    $sidClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid" -IncomingClaimTypeDisplayName "SID" -SameAsIncoming
    

    This claim mapping is used for server-to-server authentication scenarios.

For additional information about the New-SPClaimTypeMapping cmdlet, see New-SPClaimTypeMapping

Use the procedure in this section to create a new SPTrustedIdentityTokenIssuer.

To create a new authentication provider by using Windows PowerShell
  1. From the Windows PowerShell command prompt, create a new authentication provider, as shown in the following syntax.

    NoteNote:
    The $realm variable is the name of the relying party trust identifier configured in AD FS, and the $cert variable is the one that was used from the Import a token signing certificate by using Windows PowerShell section. The SignInUrl parameter is to the AD FS server.
    $realm = "urn:sharepoint:<WebAppName>"
    
    $signInURL = "https://<YourADFSServerName>/adfs/ls"
    
    $ap = New-SPTrustedIdentityTokenIssuer -Name <ProviderName> -Description <ProviderDescription> -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $emailClaimMap,$upnClaimMap,$roleClaimMap,$sidClaimMap -SignInUrl $signInURL -IdentifierClaim $emailClaimmap.InputClaimType
    

    Include $roleClaimMap and $sidClaimMap in the list of ClaimsMappings for server-to-server authentication scenarios.

For additional information about the New-SPTrustedIdentityTokenIssuer cmdlet, see New-SPTrustedIdentityTokenIssuer

This phase has the following procedures:

  1. Associate an existing web application with the AD FS identity provider

  2. Create a new web application with the AD FS identity provider

  3. Enable token replay protection

To configure an existing web application to use SAML sign-in, the trusted identity provider in the claims authentication type section must be changed.

To configure an existing web application to use the AD FS identity provider
  1. Verify that the user account that is performing this procedure is a member of the Farm Administrators SharePoint group.

  2. In Central Administration, on the home page, click Application Management.

  3. On the Application Management page, in the Web Applications section, click Manage web applications.

  4. Click the appropriate web application.

  5. From the ribbon, click Authentication Providers.

  6. Under Zone, click the name of the zone. For example, Default.

  7. On the Edit Authentication page in the Claims Authentication Types section, select Trusted Identity provider, and then click the name of your SAML provider (<ProviderName> from the New-SPTrustedIdentityTokenIssuer command). Click OK.

  8. Next, you must enable SSL for this web application. You can do this by adding an alternate access mapping for the “https://” version of the web application’s URL and then configuring the web site in the Internet Information Services (IIS) Manager console for an https binding. For more information about how to set up SSL for IIS, see How to Setup SSL on IIS 7.0.

When creating a new web application to use SAML sign-in, you must configure claims authentication for the AD FS trusted identity provider. See Create claims-based web applications in SharePoint 2013 and do the following:

  • In the Security Configuration section of the New Web Application dialog box, for Use Secure Sockets Layer (SSL), select Yes.

    For information about how to set up SSL for IIS, see How to Setup SSL on IIS 7.0.

  • In the Claims Authentication Types section of the New Web Application dialog box, select Trusted Identity provider, and then click the name of your SAML provider (<ProviderName> from the New-SPTrustedIdentityTokenIssuer command).

To allow users to authenticate by using an email addresses as their SAML-based identity, as specified in the New-SPTrustedIdentityTokenIssuer command with the -IdentifierClaim $emailClaimmap.InputClaimType parameter, you must add their email addresses with appropriate permissions to the web application.

Use the following procedure to configure a web application for permissions based on email addresses.

To configure a web application for permissions based on email addresses
  1. In Central Administration, on the home page, click Application Management.

  2. On the Application Management page, in the Web Applications section, click Manage web applications.

  3. Click the appropriate web application, and then click User Policy.

  4. In Policy for Web Application, click Add Users.

  5. In the Add Users dialog box, click the appropriate zone in Zones, and then click Next.

  6. In the Add Users dialog box, click the Browse icon in the lower-right of the Users box.

  7. In the Select People and Groups dialog box, type the email address of a user account in Find, and then click the Search icon.

  8. In the search results, click EmailAddress under the name of your AD FS identity provider, click the email address of the user under Display Name, click Add, and then click OK.

  9. In Permissions, click the appropriate level of permissions.

  10. Repeat steps 6 through 9 for additional email addresses of users with the same level of permissions.

  11. Click Finish, and then click OK.

To provide additional security for SharePoint 2013 web applications that use SAML-based claims authentication, you can use the Windows Identity Foundation (WIF) token replay detection feature. Token replay protection can prevent an attacker from trying to intercept and use a user’s security token. For more information, see How To: Enable Token Replay Detection.

Use the procedure in this section to enable replay detection on a SharePoint web application that is configured for SAML claims authentication.

To enable replay protection
  1. On the server running SharePoint 2013, open the Internet Information Services (IIS) Manager snap-in.

  2. In the console tree of Internet Information Services (IIS) Manager, right-click the site that corresponds to the name of the web application, and then click Explore.

  3. In the folder window, double-click the Web.Config file.

  4. In the <Configuration> section, find the <microsoft.identityModel> section.

  5. Add the following as a new section to the <microsoft.identityModel> section:

    <service>
        <tokenReplayDetection enabled="true" capacity="<NumberOfTokensToBeCached>" expirationPeriod="<TokenCacheExpiration>">
    </service>
    

    in which:

    • <NumberOfTokensToBeCached> is the number of tokens to store in the token replay detection cache.

    • <TokenCacheExpiration> is the time after which a token in the replay detection cache is removed, in <hours>:<minutes>:<seconds> format.

  6. Save your changes to the Web.Config file.

If the farm running SharePoint 2013 is behind a load balancer, enabling token replay detection requires session affinity in your load balancer even though SharePoint 2013 web applications do not require it. To avoid the session affinity requirement, use the information in ACS Security Guidelines.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft