Use Cases

Configuring federation with SharePoint server

Create a WS-Federation connection, export the signing certificate, add a trusted identity provider to the SharePoint server, and assign the identity provider to the web application.

This document describes how to configure a WS-Federation connection on the PingFederate server to integrate with SharePoint Server 2013 or SharePoint Server 2016.

Component

PingFederate 9.3

Creating WS-Federation connection on the PingFederate server

Set up a WS-Federation connection with PingFederate to establish federation with the SharePoint server.

Before you begin

  • Have a fully created and functional Web Application with federated authentication.

Steps

  1. Open the PingFederate Admin console.

  2. Go to System → Server → Protocol Settings.

  3. On the Roles & Protocols tab, select the Enable Service Provider (SP) Role and Support the Followingcheck box, and then select the WS-Federation check box below. Click Save.

  4. Go to Identity Provider → SP Connections. Click Create New.

  5. On the Connection Template tab, click Do Not Use a Template for This Connection. Click Next.

  6. On the Connection Type tab, select the Browser SSO Profiles check box.

    1. From the Protocol list, select WS-Federation.

    2. From the WS-Federation Token Type list, select SAML 1.1. Click Next.

      The Connection Type tab of the admin console. The connection template enables browser SSO profiles, WS-Federation protocol, and SAML 1.1 token type.

  7. On the Connection Options tab, keep the default settings. Click Next.

  8. Complete the General Info tab.

    The General Info tab of the admin console SP connection configuration. Information filled in for the Connection ID and Connection Name fields.

    1. In the Partner’s Realm (Connection ID) field, enter the partner’s unique connection identifier.

    2. In the Connection Name field, enter a name for the connection. Click Next.

      The Partner’s Realm can be an arbitrary value.

  9. On the Browser SSO tab, click Configure Browser SSO.

  10. Complete the Assertion Lifetime tab.

    1. In the Minutes Before field, enter 15.

    2. In the Minutes After field, enter 15. Click Next.

  11. On the Assertion Creation tab, click Configure Assertion Creation.

  12. On the Identity Mapping tab, click User Principal Name. Click Next.

    Configure the identity claim type on the SharePoint server for different attributes like email address, UPN or common name.

  13. Complete the Attribute Contract tab.

    1. In the Extend the Contract field, enter upn.

    2. From the Attribute Name Format list, select http://schemas.xmlsoap.org/ws/2005/05/identity/claims.

    3. Click Add, and then click Next.

      The attribute names are case-sensitive. They should match the claim type names configured for the Trusted Identity Provider on the SharePoint server.

  14. On the Authentication Source Mapping tab, add a mapping of your choice. Choose one of the following options.

    Choose from:

    • Map New Adapter Instance

    • Map New Authentication Policy

  15. Depending on your choice, from the Authentication Policy Contract list select an authentication policy contract, or from the Adapter Instance list select the adapter instance. Click Next.

    If you do not have an Authentication Policy Contract or an Adapter Instance created, click Manage Authentication Policy Contracts or Manage Adapter Instance and configure the authentication source mapping as needed.

    For more information, see Policy contracts and Manage IdP Adapters in the PingFederate documentation.

  16. On the Mapping Method tab, select Retrieve Additional Attributes From Multiple Data Stores Using One Mapping.

    Result:

    This selection retrieves the UPN value from an LDAP Data Store.

  17. On the Attribute Sources & User Lookup tab, click Add Attribute Store and select an existing data store under Active Data Store or create a new one.

    For more information, see Data Stores in the PingFederate documentation.

  18. On the LDAP Directory Search tab, enter the base DN details in the Base DN field.

  19. In the attribute list, add userPrincipalName to the list of attributes returned from search. Click Next.

  20. In the Filterfield, enter a name for the filter. Click Next.

  21. Click Done.

  22. On the Attribute Contract Fulfillment tab, select the attribute contract source from the Source list, and the value from the Value list for each attribute contract. Click Next.

    The Attribute Contract Fulfillment tab of the admin console, from configuring the SP connection.

  23. If necessary, complete the Issuance Criteria tab. Click Next.

    The Issuance Criteria tab is not required to continue.

  24. On the Summary tab, review the information and click Done.

  25. On the Authentication Source Mapping tab, click Next.

  26. On the Summary tab, click Done.

  27. On the Assertion Creation tab, click Next.

  28. On the Protocol Settings tab, click Configure Protocol Settings.

  29. On the Service URL tab, in the Endpoint URL field enter the Endpoint URL. Click Next.

    The SP connection configuration protocol settings summary.

    Construct the Endpoint URL by adding /_trust/ at the end of the SharePoint Web Application URL. In order to support multiple web applications on the same connection, see Additional configuration options.

  30. On the Summary tab, click Done.

  31. On the Protocol Settings tab, click Next.

  32. On the Summary tab, click Done.

  33. On the Browser SSO tab, click Next.

  34. On the Credentials tab, click Configure Credentials.

    The admin console Summary tab for configuring the SP connection.

  35. On the Digital Signature Settings tab, from the Signing Certificatelist, select your signing certificate.

  36. From the Signing Algorithm list, select the Signing Algorithm. Click Next.

  37. On the Summary tab, click Done.

  38. On the Credentials tab, click Next.

  39. On the Activation & Summary tab, review the connection settings and set the Connection Status to Active. Click Save.

Exporting the signing certificate

Find and export the signing certificate created for the WS-Federation connection on the PingFederate server.

Steps

  1. In the PingFederate Admin Console, go to Security → Certificate & Key Management → Signing & Decryption Keys & Certificates.

  2. In the row with the previously-created signing certificate for the WS-Federation connection, click Select Action.

  3. Click Export.

  4. On the Export Certificate tab, click Certificate Only. Click Next.

  5. Verify the certificate is correct, and then click Export.

    A .crt file will be saved in the Downloads folder configured for your browser.

Adding a trusted identity provider to the SharePoint server

Run the following commands in the SharePoint Management Shell to add an identity provider.

Steps

  1. Open SharePoint Management Shell.

  2. Update the following commands according to your environment and run them one by one. To run the commands as a PowerShell script, add them to a .psl file.

    #Path to the Signing Certificate exported from the PingFederate server.

$certpath = "c:\<pf-cert-name>.crt"


 #Name the PingFederate will be represented within SharePoint as a Trusted Identity Provider (PingFederateSTS was used in this example).

$stsname = "<PingFederate_Trusted_Identity_Provider_name>"

#Description for PingFederate STS within SharePoint.

$stsdesc = "PingFederate Claims Provider"


#Entity ID of the SharePoint realm (in our example it is ektd:sp02).

$stsrealm = "<SharePoint_Realm_Name>"


 #PingFederate WS-Federation Endpoint.

$signinurl = "https://<PingFederate_host_name_or_FQDN>:<port_number>/idp/prp.wsf"


 #Importing PingFederate Certificate into SharePoint.

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("$certpath")

New-SPTrustedRootAuthority -Name "PingFederate Token Signing Cert" -Certificate $cert

# Defining incoming Claim Types.
# Note: It could be more than one incoming claim type specified here.

$m1 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" -IncomingClaimTypeDisplayName "UPN" -SameAsIncoming


# Creating Trusted Identity Provider

New-SPTrustedIdentityTokenIssuer -Name $stsname -Description $stsdesc -Realm $stsrealm -ImportTrustCertificate $cert -ClaimsMappings $m1 -SignInUrl $signinurl -IdentifierClaim $m1.InputClaimType

Assigning the created PingFederate trusted identity provider to the web application

Assign the web application’s authentication providers using the zone name, claims authentication types, and the sign in page redirect URL.

Steps

  1. Open SharePoint Central Administration console and go to Application Management → Manage Web Applications.

  2. Select the Web Application, and then click Authentication Providers.

  3. Click the desired Zone name.

  4. To enable the PingFederateSTS trusted identity provider, go to Claims Authentication Types, and then select PingFederateSTS.

    Edit Authentication window in the administrative console.

  5. Go to Sign In Page URL, and then click Custom Sign In Page.

  6. In the Custom Sign In Page field, enter /_trust/?trust=<PingFederate_Trusted_Identity_Provider_name>.

    Sign In Page URL step in the administrative console.

    To automatically redirect users to PingFederate for authentication when other authentication providers are configured, you must enter a destination for Sign In page redirection.

  7. Save changes.

Enabling additional configuration options

Use the same service endpoint connection to service all of the web applications hosted on SharePoint Server.

Steps

  1. Open the SharePoint Management Shell.

  2. To enable the wreply parameter for the Trusted Identity Provider, run the following commands.

    $tit = Get-SPTrustedIdentityTokenIssuer
 <PingFederate_Trusted_Identity_Provider_Name>
$tit.UseWReplyParameter = $true
$tit.Update()

  3. Configure Valid Domain Names.

    1. In the PingFederate Admin console, open the connection for your SharePoint server.

    2. Go to Protocol Settings → Service URL.

    3. In the Valid Domain Name field, enter the domain name.

      If you have several web applications with a common domain name, such assales.pingdemo.com or support.pingdemo.com, and if you require extra security, add them to the list. Otherwise, to cover these and future URLs with a similar format, add the domain name with a leading wildcard (*.pingdemo.com).

    4. Select the Require HTTPS and Allow Any Query/Fragment check boxes. Click Add.

    5. Click Save.