This topic describes how to configure your SharePoint alternate access mapping (AAM) application and Active Directory Federation Services (AD FS) 2.0 server to allow users to access your SharePoint AAM application using AD FS 2.0. For information about publishing SharePoint AAM applications through Forefront Unified Access Gateway (UAG), see SharePoint publishing solution guide.

Microsoft SharePoint Server contains a security token service, which is a specialized web service that is designed to respond to requests for security tokens and provide identity management.

Prerequisites

Before you can configure SharePoint AAM applications with AD FS 2.0:

  • You must export the ADFS Token-signing certificate from the AD FS 2.0 Management console and save it to a location to which the SharePoint server has access.

  • Plan your AAM configuration if it is a new application or an existing application, in particular, make sure that the AAM name (webappurl in the following procedures) that you publish through Forefront UAG is the same as the relying party that you configure on the AD FS 2.0 server.

How web applications that use a security token service work

Web applications that use a security token service handle requests to issue, manage, and validate security tokens. Security tokens consist of a collection of identity claims (such as a user's name, role, or an anonymous identifier). Tokens can be issued in different formats, such as Security Assertion Markup Language (SAML) tokens. Security tokens can be protected with an X.509 certificate to protect the token's contents in transit and to enable validation of trusted issuers.

An Identity Provider-STS (IP-STS) is a web service that handles requests for trusted identity claims. An IP-STS uses a database called an identity store to store and manage identities and their associated attributes. The identity store for an identity provider may use a SQL database table, or may use a complex identity store, such as Active Directory Domain Services (AD DS).

An IP-STS is available to clients who want to create and manage identities, and to relying party applications that must validate identities presented to them by clients. Each IP-STS has a federated trust relationship with, and issues tokens to, federation partner Relying Party STS web applications, each of which are referred to as an RP-STS. Clients interact with the IP-STS when they request security tokens that represent an identity that is contained in the identity store of the IP-STS. After authentication, the IP-STS issues a trusted security token that the client can present to a relying party application. Relying party applications can establish trust relationships with an IP-STS. This enables them to validate the security tokens issued by an IP-STS. After the trust relationship is established, relying party applications can examine security tokens presented by clients and determine the validity of the identity claims they contain.

A relying party STS (RP-STS) is an STS that receives security tokens from a trusted federation partner IP-STS. In turn, the RP-STS issues new security tokens to be consumed by a local relying party application. The use of RP-STS web applications in federation with IP-STS web applications enables organizations to offer web single-sign-on (SSO) to users from partner organizations. Each organization continues to manage its own identity stores.

Configure a SharePoint claims-based web application using Windows PowerShell

Perform the following procedure to use Windows PowerShell to configure a SharePoint claims-based web application.

To configure a SharePoint claims-based web application using Windows PowerShell

  1. On the SharePoint server, on the Start menu, click All Programs.

  2. Click Microsoft SharePoint 2010 Products.

  3. Click SharePoint 2010 Management Shell.

  4. From the Windows PowerShell command prompt (that is, PS C:\>), import the SharePoint system modules, as shown in the following example:

      Copy Code 
    ImportSystemModules

  5. Verify that the user that you will use to configure the SharePoint web application is a member of the SharePoint_Shell_Access role, as shown in the following example:

      Copy Code 
    Add-SPShellAdmin –UserName domain\username

  6. Create an x509Certificate2 object, as shown in the following example:

      Copy Code 
    $cert = New-Object 
System.Security.Cryptography.X509Certificates.X509Certificate2("<ADFS token signing certificate>")

    Make sure to enter the correct path to the ADFS token-signing certificate that you exported from your organization’s AD FS 2.0 server.

  7. Create a claim type mapping to use in your trusted authentication provider, as shown in the following example:

      Copy Code 
    $map1 = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" 
-IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming

  8. Create a value for the realm parameter to be used when creating the trusted login provider, as shown in the following example:

      Copy Code 
    $realm = "urn:" + $env:ComputerName + ":SP2010"

  9. Create a value for the signinurl parameter that points to the AD FS 2.0 server web application, as shown in the following example:

      Copy Code 
    $signinurl = "https://<ADFS_FQDN>/adfs/ls/"

    Make sure to enter the full computer name of your AD FS 2.0 server, for example, adfs.contoso.com.

  10. Create the trusted login provider, using the same IdentifierClaim value as in the claim mapping ($map1.InputClaimType), as shown in the following example:

      Copy Code 
    $ap = New-SPTrustedIdentityTokenIssuer -Name "<Provider_name>" 
-Description "<Provider_name_description>" -Realm $realm -ImportTrustCertificate $cert 
-ClaimsMappings $map1 -SignInUrl $signinurl -IdentifierClaim $map1.InputClaimType

    You can enter any name and description for the trusted login provider, for example, you can set the name “ADFS2.0” and the description “AD FS 2.0 login provider”

  11. Create an authentication provider that uses Integrated Windows Authentication (IWA). This authentication provider allows you to log on to the SharePoint site and define user access permissions.

      Copy Code 
    $ap2 = New-SPAuthenticationProvider -UseWindowsIntegratedAuthentication

  12. Create a value for the web application URL, as shown in the following example:

      Copy Code 
    $webappurl = "https://<Application URL>"

    You can use any URL for the web application URL. Users type this URL into their browser when accessing the published SharePoint site.

  13. Create a value for the application pool account (for the current user) to be used when creating the SharePoint web application, as shown in the following example:

      Copy Code 
    $account = "DOMAIN\" + $env:UserName
    Important:
    The application pool account must be a managed account. To create a managed account, use New-SPManagedAccount.

  14. Create the new web application using the trusted login provider and the IWA authentication provider, as shown in the following example. The IWA authentication provider should be removed from the web application before you deploy it to your end users.

      Copy Code 
    $wa = New-SPWebApplication -Name "<Application_name>" -SecureSocketsLayer 
-ApplicationPool "SharePoint SSL" -ApplicationPoolAccount $account 
-Url $webappurl -Port 443 -AuthenticationProvider $ap, $ap2

    You can enter any name for the web application, for example, “Claims-based application”.

    Note:
    If you use an existing ApplicationPool, you cannot specify an ApplicationPoolAccount.

  15. Create a claim object that will be used when creating the site for your new web application, as shown in the following example:

      Copy Code 
    $claim = New-SPClaimsPrincipal -TrustedIdentityTokenIssuer $ap –Identity $env:UserName

  16. Create a site (the default team site) for your new SharePoint web application, as shown in the following example:

      Copy Code 
    $site = New-SPSite $webappurl –OwnerAlias $claim.ToEncodedString() -template "STS#0"

  17. Add the ADFS token-signing certificate to the list of trusted root authorities, as shown in the following example:

      Copy Code 
    New-SPTrustedRootAuthority -Name "ADFS Token-Signing Root Authority" -Certificate $cert
    Note:
    You must add every root certificate in this manner with a different name for the SPTrustedRootAuthority. For example, if you use a domain certification authority that issues a certificate that you use for token signing, you must create the certificate object (as shown in step 5) and run this New-SPTrustedRootAuthority command for both the issued certificate as well as the root certificate.

Adding a secondary site administrator

After you have configured a SharePoint claims-based web application, you should add a secondary site collection administrator that you can use to log on to the site using IWA. This is necessary so that you can easily configure authorization for the SharePoint site. See also Configuring authorization for the SharePoint site.

To add a secondary site collection administrator

  1. On the SharePoint server, click Start, and then click SharePoint 2010 Central Administration.

  2. In SharePoint 2010 Central Administration, click Application Management, and then under Site Collections, click Change site collection administrators.

  3. On the Site Collection Administrators page, in the Site Collection list, select your claims-based web application.

  4. Under Secondary site collection administrator, enter a user in the format domain\user, or click Browse to open the Select People dialog box and select a user.

  5. After you have selected the user, click OK.

Edit the SharePoint web application bindings

After you have configured a SharePoint claims-based web application, you must edit the site bindings.

To edit the SharePoint web application bindings

  1. On the SharePoint server, click Start, click All Programs, click Administrative Tools, and then click Internet Information Services (IIS) Manager.

  2. In the IIS console, go to the claims-based web application site. This is the application that you created in the previous procedure.

  3. In the left pane, right-click the claims-based web application, and click Edit Bindings.

  4. On the Site Bindings dialog box, click https and click Edit.

  5. Under SSL Certificate, select a certificate that matches the newly created site, and then click OK.

  6. On the Site Bindings dialog box, click Close.

Configuring authorization for the SharePoint site

After you have configured a SharePoint claims-based web application, you must configure authorization for the web application. By default, after creating the site, users cannot access it. To allow other users to access the site, you must grant them permissions. After granting access to end users, you should disable the IWA authentication provider.

To configure SharePoint site authorization

  1. On a computer in the same domain as the SharePoint server, open a new browser window, go to the SharePoint claims-based application website, and sign in using Windows Authentication with the user name and password of the secondary site collection administrator.

  2. On the web site, click Site Actions, and then click Site Settings.

  3. On the Site Settings page, under Users and Permissions, click People and groups.

  4. In the Groups list, click the group to which you want to add users or create a new group.

  5. On the group membership page, click New to add people to the group.

  6. On the Grant Permissions dialog box, click the Browse icon.

  7. On the Select People and Groups dialog box, in the Find box, enter the user name or group that you want to add, and click the Search icon.

    Important:
    When adding users, you must enter the user details according to the format of the claim value of the claim type that you configured for the SharePoint claim-based application. For example, contoso\user, or user@contoso.com.

  8. In the results pane, all users or groups that match your search term are shown. Double-click each user or group that you want to add.

    Note:
    When using the search function, the SharePoint server does not check if the results of the search correspond to valid users.Make sure that you add users defined in your trusted login provider. For example, if you created a trusted login provider with the name ADFS2.0, you must add users only if they appear in the results pane under the title “Trusted: ADFS2.0”.

  9. On the Select People and Groups dialog box, click OK.

  10. On the Grant Permissions dialog box, click OK.

  11. On the SharePoint server, in SharePoint 2010 Central Administration, under Application Management, click Manage web applications.

  12. On the Web Applications page, click the claims-based web application, and then click Authentication Providers.

  13. On the Authentication Providers dialog box, click the Zone for your web application.

  14. On the Edit Authentication dialog box, in Claims Authentication Types, clear the Enable Windows Authentication check box, and then click Save.

  15. Close the Authentication Providers dialog box.

Configure the SharePoint server as a relying party of the Federation Service

After configuring the claims-based web application and editing the site bindings, you must configure the SharePoint server as a relying party trust on the AD FS 2.0 server.

To configure SharePoint as a relying party trust

  1. On the AD FS 2.0 server, click Start, click All Programs, click Administrative Tools, and then click AD FS 2.0 Management.

  2. Under the AD FS 2.0\Trust Relationships folder, right-click Relying Party Trusts, and then click Add Relying Party Trust to open the Add Relying Party Trust Wizard.

  3. On the Welcome page, click Start.

  4. On the Select Data Source page, click Enter data about the relying party manually, and then click Next.

  5. On the Specify Display Name page, under Display name, enter a friendly name for this relying party trust, and then click Next.

  6. On the Choose Profile page, click AD FS 2.0 profile, and then click Next.

  7. On the Configure Certificate page, click Next.

    It is not necessary to configure a token encryption certificate, but if you require claims to be encrypted, you can configure it here.

  8. On the Configure URL page, select the Enable support for the WS-Federation Passive protocol check box. Under Relying party WS-Federation Passive protocol URL, enter the URL for your SharePoint web application with ‘_trust’ appended. For example, if your SharePoint web application URL is https://app1.contoso.com, enter https://app1.contoso.com/_trust/. Click Next.

  9. On the Configure Identifiers page, under Relying party trust identifier, enter the realm value that you created when defining the trusted login provider, for example, urn:sp_server:SP2010. Click Add, and then click Next.

    Note:
    The Relying party trust identifier is case sensitive.

  10. On the Choose Issuance Authorization Rules page, click Permit all users to access this relying party, and then click Next.

  11. On the Ready to Add Trust page, review the settings, and then click Next.

  12. On the Finish page, click Close. This action automatically displays the Edit Claim Rules dialog box.

  13. On the Edit Claim Rules dialog box, on the Issuance Transform Rules tab, click Add Rule. The Add Transform Claim Rule Wizard opens.

  14. On the Select Rule Template page, in the Claim rule template list, click Pass Through or Filter an Incoming Claim, and then click Next.

  15. On the Configure Rule page, do the following:

    1. Under Claim rule name, enter E-mail.

    2. In the Incoming claim type list, select E-Mail Address.

      Note:
      The claim type must match the claim type that you used when configuring the SharePoint server. If you configured the trusted login provider using a claim type other than emailaddress you must choose that claim type here.
    3. Click Finish.

  16. On the Edit Claim Rules dialog box, click OK.