Claims-based authentication "Cheat Sheet" Part 2

  • Article

 

On part 1 of these blog post series we went over the process of configuring forms based authentication. In this second part we will talk about configuring a SAML based sign-in (also known as claims sign-in).

 

In the upcoming blog posts, we will discuss more scenarios like mixed mode authentication and multi-auth, so stay tuned for more on these.

 

Make sure you read the part 1 of this blog in order to get the information about pre-requisites for this guide.

 

Sign-in using a SAML claims token scenario overview

In windows authentication, the user present a windows token to SharePoint in order to request access. This token is given by the AD domain controller during authentication. In the case of SAML sign-in, the user will present a SAML token, in this case, the user gets the token from an STS (Security Token Service).

 

SAML sign-in is generally used in enterprise federation scenarios, for example: provide access to a partner. This authentication mechanism is also used in other scenarios like extranet and even internally, for example: Provide access to users from the same company but in a domain that is not part of the forest where SharePoint lives.

 

You can find more information about claims scenarios in the "Geneva" team blog. Another good resource that talks about claims sign-in scenarios can be found here.

 

Pre-requisites to run this scenario

For this example, we will use Geneva Server as the trusted STS (authentication provider) for our SharePoint web application. Click here to learn more about how to setup AD FSv2 (aka Geneva Server).

 

The link noted above describes how to configure the STS, below I describe how these steps relate to SharePoint SAML sign-in:

 

On the step "Federation Service Name Page" the STS certificate is defined. You will need to export this cert (without the private keys) and copy to the machine where SharePoint 2010 is installed. During trust establishment, you will be required to use this cert.

 

Once AD FSv2 STS has been configured, you will need to create a new relying party application, SharePoint in this case, so the STS can issue user tokens for SharePoint. You can find information about this on the Geneva Team blog and also in TechNet, below are the basic steps to create the relying party for SharePoint:

 

  • Open up the Microsoft Geneva Server Management shortcut on the desktop
    • In the left pane:
      • Expand Policy
      • Select Relying Parties
      • In the right pane
      • Add Relying Party...
      • A wizard will appear
      • Select Start
      • Choose "Enter relying party configuration manually" Click Next
      • Give a Name. Click Next
      • Leave "Geneva" Server Profile selected. Click Next
      • You will not use a encryption cert. Click Next
      • Select Enable support for Web-browser-based identity federation
      • Give the Web App url and append /_trust/
        • Click Next
      • Add the following entry as a identifier (realm)
        • urn:COMPUTERNAME:Geneva
        • Click Add
        • Click next
      • Click Next on the summary page
      • Click Close
    • A new dialog will appear
    • Rules Editor: we will map claims from LDAP to send to SharePoint
    • In the Left Pane
      • New Rule
      • Predefined Rules
      • Create Claims from LDAP Attribute Store
        • Right Pane
        • Drop down Attribute Store:
        • Select Enterprise Active Directory User Account Store
        • Under LDAP Attribute select sAMAccountName
        • Under Out Going Claim Type select E-Mail Address
      • Left Pane
        • Click the Save Icon
      • Close the dialog

 

 

 

Steps to configure claims-based authentication in SharePoint 2010 beta

At a high level, the steps needed to configure this authentication mode are:

 

  1. Define a trust with an STS (Geneva server in this example)
    1. Select a claim from the "incoming" token that will be used as unique identifier for the user
    1. (optional) Define which claims from the incoming token we will be accepted and how they will show up in SharePoint 2010 (claims mappings)
      1. Note: All claims from incoming token that don't have a mapping will be discarded.
    1. Select the certificate that will be used to validate that the token was issued by the trusted STS (our assumption here is that the cert from Geneva Server was provided to us and: it is already deployed in all farm machines or import via SharePoint claims functions so it can be distributed to all machines in the farm).
  1. Create a new SharePoint web application and enable this authentication provider

 

In order to do what's described above, you can use SharePoint Central Administration or PowerShell cmdlets, below I'll describe both options and same as in previous blog post, we will use a sample script that facilitates the use of the cmdlets. This script is also very good reference to learn how to use these PowerShell cmdlets. 

 

PowerShell sample script instructions:

We created a PowerShell script that you can use to deploy these scenarios in a very easy way, below we will discuss how to use this script in the different scenarios. Feel free to play with the script to accommodate your specific requirements, it is also a great tool to learn how to use our new SharePoint 2010 beta PowerShell cmdlets.

 

The sample script can be found  here

 

Note: In order to use the script, copy the files from the above link to where the SharePoint 2010 beta is installed, you will need to create a directory (in any location) to place the files.

 

Pre-requisite step - Prepare an Identity Provider STS (IP-STS)

You can use your own STS or use Geneva Server. In the steps noted below, we will assume Geneva Server as the external IP-STS. To learn about Geneva Server and how to setup, go to: Geneva Server RC anouncement

 

Step 1 - Establish a trust with the Identity Provider STS (IP-STS)

 

Via PowerShell

$waurl = "https://" + $env:ComputerName

$title = "SAML-Claims"

 

1.1 Get certificate of the STS we want to trust

Export the certificate of the Geneva Server and copy it to a location where the SharePoint server has access. To make more readable and clean the user of the PowerShell cmdlets, I will create an object with this cert:

 

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\geneva.cer")

 

1.2 Define the claim that will be used as unique identifier of the user (claims mappings)
For this example we will use email as the user identifier. In real world scenarios, the administrator of the trusted STS will need to provide this information, the reason is that only the owner of the STS knows which value in the token will be always unique per user. It is also important to note that the URI we are using in claim type for email is not mandatory, the administrator of the trusted STS could create its own URI to represent email. In this example we use the one defined by OASIS.

 

$map = New-SPClaimTypeMapping -IncomingClaimType "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming

 

1.3 (Optional) Define additional claim mappings

You can define additional claims that we want to keep from the incoming token, for example if the trusted STS also include roles of the user, we may want to keep that claim so we can ACL resources in SharePoint using these claims. In this example we will not create additional claim mappings.

 

One last comment about claim mappings; All claims are per trusted STS (authentication provider), this means that if SharePoint establish a second trust with a different STS, the claims from that STS will not clash with the ones from the other trusted STS. The reason for this is that the claim also contains the original issuer value which makes it different for each trusted STS.

 

1.4 Create a new authentication provider

In this step, we will create the SharePoint authentication provider that the web application will use.

 

$realm = "urn:" + $env:ComputerName + ":Geneva"

$ap = New-SPTrustedIdentityTokenIssuer -Name "Geneva" -Description "Geneva" -Realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map -SignInUrl "https://nicstu-test-2/FederationPassive/" -IdentifierClaim "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"

   

The realm is the parameter used by the trusted STS to identify a particular SharePoint farm, refer to Geneva Server documentation for more details.

 

Step 2 - Create a new SharePoint web application and configure it to use SAML sing-in

 

2.1 Create a new SharePoint web application and configure it to use the newly created authentication provider (Geneva STS)

In this step we will create and configure the web application, note that we are enabling SSL, the reason is that in SAML Sing-In and same as in forms based authentication, we use cookies as the single sign on ticket for the user. This allows us to give access to the SharePoint resources for the duration of the token without the need of re-authenticate the user. Without SSL these cookies can be easily high jacked by a malicious user and be used to impersonate the original user.

 

$wa = New-SPWebApplication -Name "SAML Sign-In" -SecureSocketsLayer -ApplicationPool "SAML Sign-In" -ApplicationPoolAccount "domain\admin" -Url "WebAppUrl" -Port 443 -AuthenticationProvider $ap

 

Note: You must replace the place holders "WebAppUrl" and "domain\admin" with the proper values

 

2.2 Create a SharePoint site and assign an owner

This step can be done via PowerShell or via central administration. Refer to SharePoint 2010 documentation in TechNet for details on how to create a site.

 

 

OPTION 2: Via sample script for PowerShell (Does not apply for Central Admin path)

  • Launch a the SharePoint 2010 beta Management Shell
  • Switch to the location where you copied the script files
  • Edit the script file and replace the place holders with the values based on your environment, for example: administrator accounts, url's, etc.
  • Open the SharePoint 2010 management shell (Start -> Microsoft SharePoint 2010 Products -> SharePoint 2010 Management Shell)
    • NOTE: Make sure you run the shell console as administrator
  • Execute the script with the appropriate parameters depending on the authentication type you want to configure:
    • Forms: claimswa.ps1 SAML
      • NOTE: This will create a web application with SSL enabled in port #443, to specify a different port, just add the port number after the "SAML" parameter
    • NOTE: If you run the script for a second time in order to create a new web application, you must specify the port number. This parameter is only optional the first time the script is used.

 

 

 

You should be able to browse to the newly created web application and get redirected to the Geneva Sign-In page in order to authenticate.

 

Don't forget to send your feedback, and stay tuned for the upcoming posts of this guide with the steps to configure other authentication scenarios.

 

More information can be found on TechNet: Authentication planning

 

Additional TechNet resources can be here: https://technet.microsoft.com/en-us/library/ee806881(office.14).aspx