Step 1: Provide Enable with EntityID and single sign-on URL
In order to configure single sign-on with AD FS, Enable’s system administrators will need to update DealTrack to point to the appropriate AD FS server. Please provide your Client Services team with both the ‘Identity provider EntityID’ and the ‘Identity provider single sign-on URL’ (see below). This will allow Enable to configure it appropriately for you.
It is important that you configure the relevant endpoints in AD FS management and verify that these values match exactly those you provide to Enable.
The following values are convention based, but if you are unsure you can check your FederationMetadata.xml file of your AD FS server. The FederationMetadata.xml file can be downloaded from your AD FS server by visiting https://<adfs-hostname>/FederationMetadata/2007-06/FederationMetadata.xml. This file contains an XML representation of the AD FS configuration for this server.
Identity provider EntityID
The EntityID is the identifier for the AD FS instance being configured. Assuming no custom configuration has been applied, this will usually end with ‘/adfs/services/trust’. Here is an example snippet from FederationMetadata.xml:
Identity provider single sign-on URL
The single sign-on URL is the URL that will receive the sign-on request. Assuming no custom configuration has been applied, this will usually end with ‘/adfs/ls’. Here is an example snippet from FederationMetadata.xml:
Step 2: Retrieve the identity provider public certificate
To retrieve the identity provider public certificate, you will first be required to access your AD FS server and open the AD FS Management console. Within the ‘Certificates’ area, simply locate the AD FS token-signing certificate, download it and email the information to your Client Services team.
Please note — you may need to zip this file to avoid emails being marked by spam filters.
This certificate is required by Enable’s system administrators when uploading the identity provider public certificate.
Step 3: Relying party trust configuration
Once the configuration has been setup within DealTrack, a member of the Client Services team will email the details required to set up the ‘Relying party trust’ within your AD FS management console. These details will consist of useful URLs and a public certificate. For example:
- DealTrack client service metadata · https://admin.deal-track.com/Client/ClientName/Sso/Saml2
- EntityID · https://admin.deal-track.com/
- URL for user initiated Single Sign-On · https://admin.deal-track.com/Client/ClientName/Sso/Saml2/SignIn
- URL the identity provider should send sign-on responses to · https://admin.deal-track.com/Client/ClientName/Sso/Saml2/Acs
- URL the identity provider should send logout requests to · https://admin.deal-track.com/Client/ClientName/Sso/Saml2/Logout
- Public certificate · Attached as ‘DealTrack-SAML2-Public-Certificate LIVE.cer’
You will now need to create a new Relying party trust. Within the AD FS Management console, navigate to Trust Relationships > Relying Party Trusts. Clicking the Add relying party trust wizard will then start up and guide you through the setup process.
Once you have reached the ‘Select data source’ step, you will be prompted to choose the way you want to enter the configuration regarding the relying party.
The simplest way of configuring this is by simply using the ‘DealTrack client service metadata URL’ mentioned above.
Alternatively, you can choose to import the DealTrack client service metadata file or enter the data manually (although the latter is not recommended). Finally, complete all remaining steps in the Add relying party trust wizard to create the new relying party trust.
Outgoing claims configuration
The final configuration step requires Outgoing claims to be configured. These ‘claims’ are required in order for DealTrack to determine which DealTrack user maps to which AD FS user. This is done by telling AD FS to include the AD FS ‘E-Mail-Address’ LDAP attribute in each successful authentication response.
Right-click on the newly created Relying party trust, click on Edit claim rules and then on Add rule. Within the Add transform claim rule wizard, select Send LDAP attributes as claims. The claim rule should then be configured as shown in the screenshot below.
Please note — the Claim rule name field can be left blank.
It is imperative that the ‘E-mail-addresses’ LDAP attribute gets mapped to the ‘Name ID’ outgoing claim type. DealTrack currently only supports an email address as the way of identifying a user.
It is also important that the field is populated with an actual email address for the AD FS users that are expected to authenticate with DealTrack. If an AD FS user does not have an email address set that matches a corresponding user in DealTrack then the authentication will fail.
AD FS offers the ability to perform a certificate revocation check on each Relying party trust. This check requires additional communication with the AD FS server to determine whether the Relying party trust's encryption certificate has been revoked. This check is not relevant in the context of DealTrack SSO and any communication issues while contacting the AD FS server as part of this process can cause authentication requests to fail.
If you have completed all of the above steps and you are still encountering issues while authenticating with AD FS, then it may be worthwhile to disable certificate revocation.
To disable the certificate revocation check, the following command needs to be ran from an elevated ("Run as administrator") PowerShell console:
Get-AdfsRelyingPartyTrust -Identifier 'https://admin.deal-track.com' | Set-AdfsRelyingPartyTrust -SigningCertificateRevocationCheck None -EncryptionCertificateRevocationCheck None