Integrating with ADFS

ADFS is an implementation of a Security Token Service. The basic integration principles are explained in Integrating with Security Token Service. This article explains how to use the module's cmdlets to integrate with ADFS.

Acknowledgements

The following values assume an ADFS at adfs.example.com:

#Issuer name
$issuerName="Example ADFS (20160101)"
#WS Federation endpoint
$wsFederationUri="https://adfs.example.com/adfs/ls/"
#WS Trust endpoint
$wsTrustUri="https://adfs.example.com/adfs/services/trust/13/windowsmixed"
#WS Trust metadata exchange endpoint
$wsTrustMexUri="https://adfs.example.com/adfs/services/trust/mex"
#The authentication type
$bindingType="WindowsMixed"
#Token signing thumbprint
$tokenSigningCertificateThumbprint="2509fb22f7671aea2d0a28ae80516f390de0ca21"

Implementing the integration on Content Manager

There are two kinds of integration:

  1. Only the clients not in the server zone use the STS at adfs.example.com to authenticate. All clients within the server zone continue using the internal ISHSTS.
  2. All clients in the user and server zone use the STS at adfs.example.com to authenticate. We don't need to define the Actor credentials because the authentication type is Windows.

User zone integration

Set the deploymentName variable

First set the deploymentName variable:

$deploymentName="InfoShare"

Then:

# Set WS Federation integration
Set-ISHIntegrationSTSWSFederation -ISHDeployment $deploymentName -Endpoint $wsFederationUri
# Set WS Trust integration
Set-ISHIntegrationSTSWSTrust -ISHDeployment $deploymentName -Endpoint $wsTrustUri -MexEndpoint $wsTrustMexUri -BindingType $bindingType
# Set Token signing certificate
Set-ISHIntegrationSTSCertificate -ISHDeployment $deploymentName -Issuer $issuerName -Thumbprint $tokenSigningCertificateThumbprint

All zone integration

Set the deploymentName variable

First set the deploymentName variable.

$deploymentName="InfoShare"

Here is an example for a windows authentication:

# Set WS Federation integration
Set-ISHIntegrationSTSWSFederation -ISHDeployment $deploymentName -Endpoint $wsFederationUri
# Set WS Trust integration
Set-ISHIntegrationSTSWSTrust -ISHDeployment $deploymentName -Endpoint $wsTrustUri -MexEndpoint $wsTrustMexUri -BindingType $bindingType -IncludeInternalClients
# Set Token signing certificate
Set-ISHIntegrationSTSCertificate -ISHDeployment $deploymentName -Issuer $issuerName -Thumbprint $tokenSigningCertificateThumbprint

Implement the integration on ADFS

The Save-ISHIntegrationSTSConfigurationPackage cmdlet supports an -ADFS parameter. Using the parameter generates an extra script that configures the ADFS server remotely:

$filename="$(Get-Date -Format "yyyyMMdd").ADFSIntegrationISH.zip"
Save-ISHIntegrationSTSConfigurationPackage -ISHDeployment $deploymentName -FileName $filename -ADFS

Inside the zip file you will find the following files:

  • CM Security Token Service Requirements.md, that is a markdown file with the specific deployment information.
  • Invoke-ADFSIntegrationISH.ps1, that can set or remove the necessary relying party entries on a target ADFS.
  • ishws.cer, that is the public key of the ISHWS service certificate. This is processed by the script.

To set the relying parties, execute this (where ADFS01 is the computer name for the ADFS server):

& .\Invoke-ADFSIntegrationISH.ps1 -Computer ADFS01 -Action Set

To remove the relying parties, execute this:

& .\Invoke-ADFSIntegrationISH.ps1 -Computer ADFS01 -Action Remove

Updating the encryption certificate on ADFS

Using Invoke-ADFSIntegrationISH.ps1 with -Action Set will first search for existing relying parties. When found, it will update them with the encryption certificate.

To keep the relying parties updated:

  1. Use Save-ISHIntegrationSTSConfigurationPackage to get the latest integration script.
  2. Execute Invoke-ADFSIntegrationISH.ps1 with -Action Set.

Enable authentication with Content Manager internal users

While the deployment is integrated with an ADFS, it could be requested that the system allows access for internal users without modifying the integration. An internal user is one that has a username and a password in the Content Manager database, and the credentials are validated by ISHSTS.

# Just Content Manager (ISH)
Enable-ISHIntegrationSTSInternalAuthentication -ISHDeployment $deploymentName

If the deployment is integrated with Collaborative Review, provide the necessary values like this:

# When the deployment is integrated with Collaborative Review (LC)
Enable-ISHIntegrationSTSInternalAuthentication -ISHDeployment $deployment -LCHost "lc.example.com" -LCWebAppName "ContentDelivery"

Enable-ISHIntegrationSTSInternalAuthentication will enable a special URL at https://ish.example.com/ISHWS/Internal/. Provide this URL to any user that wishes to login with internal users.

To disable this mode use Disable-ISHIntegrationSTSInternalAuthentication.

Disable-ISHIntegrationSTSInternalAuthentication -ISHDeployment $deploymentName