Connect a SharePoint 2019 site

With just a few steps, you can connect your SharePoint 2019 to The Identity Hub using WS-Federation.

A. Download and install "TIHCP - Claims provider for The Identity Hub"

The Identity Hub provides a custom claim provider for SharePoint 2019. The claim provider provides the following features:

  • Enriches the claim principal in SharePoint with additional claims from The Identity Hub (e.g. Display name, Given name, Surname, Email).
  • Support for multiple connections to The Identity Hub, i.e. multiple tenants or multiple app registrations within a tenant.
  • SharePoint People Picker support allowing you to find and resolve users and roles from The Identity Hub.
  • The User Profile Service is updated with the claims from the users and is automatically synced to the SharePoint sites.
Note

The claim provider only needs to be added once to your SharePoint Farm and can then be used to support multiple connections to The Identity Hub.

  1. Download the SharePoint solution package from downloads.
  2. Open the SharePoint 2019 Management Shell.
  3. At the Windows Powershell command prompt, type the following command:
Add-SPSolution -LiteralPath [path to the The Identity Hub SharePoint solution package]
  1. Open Central Administration and navigate to System Settings > Manage farm solutions.
  2. Deploy the solution identityhub.claimprovider.wsp.
  3. After deployment has completed, navigate to Security in Central Administration and validate that the section TIHCP - Claims Provider for The Identity Hub is now available.

B. Create and configure an App in The Identity Hub

  1. Create an App for your application. See Create an App for details.
  2. For WS-Federation Reply URL's: set the URI of your sharepoint site (e.g. https://sharepoint.contoso.com/) including the port number if it is different from the default 443.
  3. Type the realm for sharepoint to identify itself in Relying Party Realm.
  4. Supply a Token Signing Certificate
    It is recommended that you acquire and use a specific certificate, only used for this purpose.
Note

Relying Party Certificate is not supported by SharePoint.

Note

As of version 1.72 it is necessary to create a scope 'tih_searchusers' and link and assign it automatically to this app.

C. Add a trusted login provider to SharePoint

  1. Download the PowerShell Module from downloads.
  2. Open the SharePoint 2019 Management Shell.
  3. At the Windows Powershell command prompt, type the following command:
Import-Module [path to the downloaded module file]
  1. Once the module is imported, use the following command:
Add-TihTrustedLoginProvider -Realm [Realm] -FedMetadataUrl [FederationMetaDataUrl] -Name [Name] -UseEmailAddressAsUniqueKey [UseEmailAddressAsUniqueKey]

With the following parameters:

Parameter Description
Realm The Relying Party Realm you entered in the app registration in The Identity Hub. (REQUIRED)
FederationMetaDataUrl The online url to the Federation Metadata of your app in The Identity Hub. This url can be retrieved from the App detail page, under WS-Federation Web Applications and Relying Parties > Metadata document. (OPTIONAL)
If omitted, it will look for the Federation Metadata in a file called FederationMetadata.xml in the current folder.
Name A readable name for the Trusted Login Provider in SharePoint. (OPTIONAL)
When omitted, it defaults to The Identity Hub [TENANT] where [TENANT] is the name of the tenant in The Identity Hub you are setting up a trust with.
UseEmailAddressAsUniqueKey A flag that indicates whether the trusted login provider should use the email claim as unique identifier. Only set this flag to $true if the tenant in The Identity Hub indicates that email addresses are unique (see Tenant Configuration Options). (OPTIONAL)
Default value is $false.

D. Connect the trusted login provider to the Web Application Zone

  1. Open Central Administration and navigate to Application Management > Manage web applications.
  2. Select the web application you would like to link the newly created trusted login provider to.
  3. Click "Authentication Providers" in the ribbon and click on the link with the correct zone.
  4. Scroll to the Trusted Identity Provider section and check the identity provider you've created previously.
  5. Click Save.

E. Connect the custom claim provider to the trusted login provider

  1. Open Central Administration and navigate to Security > TIHCP - Claims Provider for The Identity Hub > Configuration.
  2. Add a new connection for the trusted login provider, providing the following information.
Parameter Description
Trusted Provider Select the trusted provider you would like to connect.
Base Url The base url of your The Identity Hub (e.g. https://www.theidentityhub.com)
Tenant The tenant's url segment of the tenant on which you created the app registration (e.g. contoso)
Client ID The Client ID of the app registration in The Identity Hub (see OAuth area on app details)
Client Secret The Client Secret of the app registration in The Identity Hub (see OAuth area on app details)

F. Allow users to access SharePoint sites

You are now completely setup to grant access to users from The Identity Hub to access your sites. Use your preferred way to manage user access in SharePoint to add groups (roles) and users from The Identity Hub to SharePoint.

Upgrading existing connections prior to version 1.72

In the case your SharePoint farm was connected with TIH using the approach prior to version 1.72 (see Connect a SharePoint site), you can upgrade to the new approach. Upgrading is not required, but you will not be able to benefit from the features introduced in version 1.72 and onwards.

  1. Make sure you've created the scope 'tih_searchusers' and linked and assigned it automatically to the app registration in The Identity Hub.
  2. Follow the steps in Download and install "TIHCP - Claims provider for The Identity Hub".
  3. Open the SharePoint 2019 Management Shell.
  4. We need to link the existing trusted identity provider to the new claim provider. At the Windows Powershell command prompt, type the following command, replacing [TENANT] with the tenant's url segment from The Identity Hub:
$spti = Get-SPTrustedIdentityTokenIssuer -Identity 'The Identity Hub [TENANT]'
$spti.ClaimProviderName = 'TIHCP'
$spti.Update()
  1. We now need to disable the old claim provider, to make sure it is no longer being used. At the Windows Powershell command prompt, type the following command:
$spcpm = Get-SPClaimProviderManager  
$spcp = $spcpm.ClaimProviders  | ? { $_.DisplayName -eq 'TheIdentityHubTrustedClaimProvider' }
$spcp.IsUsedByDefault = $false
$spcp.IsEnabled = $false
$spcpm.Update()
  1. Setup a connection in Central Administration as described in Connect the custom claim provider to the trusted login provider

Your existing trusted login provider is now using the new claim provider.

Troubleshooting

General Information

Information about the SharePoint Solution

  • Solution Id: 3ec9dda9-1573-4dfb-9f62-418ab11f2368
  • Solution Name: IdentityHub.ClaimProvider

Information about the SharePoint Features

  • The Identity Hub Claims Provider - Central Administration Pages
    • Feature Id: e76e38ae-4b3c-41de-adc8-7d288dcdfc36
    • Path: TIHCP.Administration
    • Scope: Web (Central Administration)
  • The Identity Hub Claims Provider
    • Feature Id: 0235755e-5b20-4e4f-86db-1fc9782fea4b
    • Path: TIHCP
    • Scope: Farm

Diagnostics

The SharePoint Solution has diagnostic logging for configuration and operational steps.

  • Logging Area: TIHCP
  • Logging Categories:
    • Configuration: Everything related to configurational setup (features, central administration configuration)
    • The Identity Hub Trusted ClaimProvider: Everything related to the execution of the Custom Claim Provider