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:
- 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. - 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:
- Use
Save-ISHIntegrationSTSConfigurationPackage
to get the latest integration script. - 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