This document describes how to configure OpenAM and SharePoint 2010 or 2013 so that OpenAM can issue user identity tokens to SharePoint.
You should have base knowledge of federated authentication principles and OpenAM and SharePoint administration before attempting to do this. This is essentially important in case something doesn't work as it can take significant amount of time and effort to troubleshoot the setup.
It is assumed that both OpenAM and SharePoint are already configured and working. This document describes only the configuration needed to connect the two systems.
This document has been written with OpenAM 9.5.3 build 934 and SharePoint 2010 version 14.0.6029.1000. Other versions may behave differently.
The Sharepoint site being configured is the root site (https://<sharepoint_server_fqdn>:<port>/). If configuring a different site you need to adjust the token service URL accordingly. The root site web application should be created with claims based authentication, sites with classic mode authentication cannot use federated accounts.
The setup described here is the bare minimum to get things working. The configuration can be extended and/or changed as needed.
Note that I haven't seen any documentation about what the Sharepoint security token service expects to see in the incoming token so this document is written complely based on observations with test systems.
On the OpenAM side of the configuration you need to set up a Circle Of Trust, a local WS-Fed IdP and a remote WS-Fed SP. The configuration can be done on the admin UI Federation section and using ssoadm.jsp.
Setting up a WS-Fed IdP
Go to the federation entity provider list and click "New". Select WS-Fed as the protocol.
Enter these settings:
* Realm: /
* Entity Identifier: https://<openam_server_fqdn>:<port>/opensso/openam-wsfed-idp
* Meta Alias: /openam-wsfed-idp
* Signing Certificate Alias: <use existing certificate alias>
Click on the "Create" button to create the IdP. Then go to the IDP tab of the newly created IdP properties and change the following settings:
* Add an attribute map "EmailAddress=mail" to the attribute map.
* Change the Assertion Effective time to 3600.
Click "Save" to save the IdP properties and you are done.
The "EmailAddress=mail" mapping is the actual identity assertion that Sharepoint will use. The NameID settings have no effect.
Sharepoint treats the SAML assertion timeout as a session timeout and will force a reauthentication to the IdP after the assertion has expired. By default any assertions with timeout set to 10 minutes or less will not work, they will just be expired immediately.
Setting up a WS-Fed SP
The admin UI does not allow creating a remote entity manually and SharePoint does not export federation metadata for importing so the remote SP needs to be created using ssoadm.jsp.
First use the create-metadata-templ option to create a metadata template with the following options:
Entity ID: https://<sharepoint_server_fqdn>:<port>/
File name for standard metadata: Check
File name for extended metadata: Check
Hosted Service Provider metaAlias: /sharepoint-sp
Metadata specification: wsfed
Copy the generated standard metadata into an editor and change the TokenIssuerEndpoint and SingleSignOutNotificationEndpoint addresses to point to the Sharepoint token service URL:
Copy the generated extended metadata into an editor and change the following:
* Set the hosted attribute of FederationConfig to "false"
Then import the edited metadata using ssoadm.jsp import-entity with following settings:
Standard metadata: <paste the edited standard metadata>
Extended metadata: <paste the edited extended metadata>
Circle of Trust: <leave blank>
Metadata specification: wsfed
Click on Submit and ssoadm.jsp will create the remote SP.
Setting up a Circle of Trust
Go to admin UI Federation section and click on "New" in the Circle of Trust list. Name the new CoT "sharepointcot" and add the previously created IdP and SP to the list of selected entity providers. Click OK to create the CoT.
Export the IdP certificate
The IdP signing certificate needs to be exported and copied to the SharePoint server. There are many ways for doing this but one of the most straightforward ones is to export the IdP metadata using ssoadm.jsp and then copy the certificate data from the metadata.
Run the ssoadm export-entity command with the following options:
Entity ID: https://<openam_server_fqdn>:<port>/opensso/openam-wsfed-idp
Metadata Specification: wsfed
Copy the <ns2:X509Certificate>...Base64Data...</ns2:X509Certificate> section from the metadata and paste into a text editor. Edit the file to remove the <ns2:X509Certificate> and </ns2:X509Certificate> tags and add the certificate file header and footer. The resulting file should look like this:
Save the file as "openam.cer" and copy to the Sharepoint server.
Most of the configuration on the Sharepoint server needs to be done with Powershell commands. The configuration outlined here assumes that the sharepoint web application and site already exist.
Open the "SharePoint 2010 Management Shell" with the "Run As Administrator" option. Enter the following commands:
$cert = New-Object system.security.cryptography.x509certificates.x509certificate2("C:\openam.cer")
(This creates a powershell certificate object from the certificate file that was exported from OpenAM)
$map = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/claims/EmailAddress"
(This creates a claim type mapping from ADFS 1.x email address to ADFS 2.0 email address)
$realm = "https://<sharepoint_server_fqdn>:<port>/"
(This is the realm/EntityID that SharePoint uses when communicating with the IdP)
$signinurl = "https://<openam_server_fqdn>:<port>/opensso/WSFederationServlet/metaAlias/openam-wsfed-idp"
(This is the URL that Sharepoint redirects the user for logging in to the IdP)
$idp = New-SPTrustedIdentityTokenIssuer -Name "OpenAM Federation" -Description "OpenAM 9.5.3"
-Realm $realm -SignInUrl $signinurl -ImportTrustCertificate $cert -ClaimsMappings $map
(This creates the trusted identity token issuer in Sharepoint)
New-SPTrustedRootAuthority -name "OpenAM" -Certificate $cert
(This adds the self-signed IdP certificate to the list of trusted root certificates in Sharepoint. Note that for this to work you have to use a self-signed certificate, otherwise you need to import the CA certificate here. The certificate also needs to be imported as a trusted root certificate in Windows.)
After doing the above you can go into Sharepoint 2010 Central Administration. Go into Application Management -> Manage Web Applications, select your claims based web application and click on "Authentication Providers" in the ribbon. Go to "Default" zone and scroll down on the list until you see "Trusted Identity provider" and "OpenAM Federation" under it. Check both "Trusted Identity provider" and "OpenAM Federation" and save the settings.
If your site allows access to any authenticated user you should now be able to login. Otherwise you will first need to add the users from the federated authentication to necessary groups in Sharepoint.
When logging in Sharepoint should now display a dialog box allowing selection between Windows authentication or OpenAM. Selecting OpenAM brings you to the OpenAM login page and after logging in you should be redirected back to the Sharepoint site.
There are many moving parts in this configuration and if any are not just right then it won't work.
The first thing in troubleshooting is to find out which part of the setup is failing. Tools like HttpFox on Firefox allow you to look at the various stages of the authentication process.
Here is what should happen:
* User goes to Sharepoint URL https://<sharepoint_server_fqdn>:<port>/ and Sharepoint redirects to /_login/default.aspx?ReturnUrl=%2f_layouts%2fAuthenticate.aspx%3fSource%3d%252F&Source=%2F. This is the IdP selection page.
* After selecting OpenAM the user gets redirected to OpenAM IdP URL https://<openam_server_fqdn>:<port>/opensso/WSFederationServlet/metaAlias/openam-wsfed-idp?wa=wsignin1.0&wtrealm=<realm>&wctx=<context>
* OpenAM redirects to its own login screen and the user now has to log in.
* After logging in OpenAM sends out a HTML page that will cause the browser to POST the WS-Fed/SAML token to Sharepoint. The form is posted to URL https://<sharepoint_server_fqdn>:<port>/_trust/
* The Sharepoint token service issues a FedAuth cookie and redirects the user to the site.
Configuration errors such as mismatched or untrusted certificates generally speaking cause errors to appear in Windows event viewer. Always check the event logs if you get errors instead of a succesful login.