Active Directory Federation Services with ServiceNow SAML 2.0

I have had a number of customers within ServiceNow ask me about active directory Federation services (ADFS 2.0). While ADFS reports it is able to do SAML 2.0 authentication, the terminology and setup has made it a bit complicated for people to connect via SAML 2.0 in ServiceNow.

The other day, I worked with John Gubatayao from Navigis (a ServiceNow partner) and David Pesano (a customer) to get authentication to take place between ServiceNow and the ADFS 2.0 service.

During our efforts, we found some documentation that says the ADFS does not support service provider initiated login. Thus, our examples use an identity provider initiated authentication model.

PLEASE NOTE: At the time of this effort, there was documentation stating that ADFS did not support SP initiated authentication in some circumstances. Current documentation specifies that it is supported. However, this example only covers IdP-Initiated authentication.

For information on how to set up an SP-Initiated Authentication between ServiceNow and AD FS, see my post on Fixing SP Initiated Login with ADFS 2.0 and ServiceNow SAML after following the instructions on this blog to get things set up.

David did a tremendous job documenting every step he took to get the ADFS to communicate with ServiceNow. While I have submitted his documentation to the ServiceNow documentation team for their approval and edits, I would like to place the raw documentation here so that those people that need it quickly and get it today.

General AD FS Setup

Log into your ADFS 2.0 server and open the management console. This document will use samportal.example.com as the ADFS 2.0 website. Replace this with your ADFS 2.0 website address.

Right click on Service and choose Edit Federation Service Properties…

Active Directory Federation Services - Setup Step 1

Confirm that the General settings match your DNS entries and certificate names. Take note of the Federation Service Identifier as that will be used to enter into the Service-Now SAML 2.0 configuration settings.

ADFS 2.0 - General Settings

 

Browse to the certificates and export the “Token-Signing” certificate;

  • Right click the certificate and select “View Certificate”.
  • Click on the “Details” tab.
  • Click on “Copy to File…” The Certificate Export Wizard will launch.
  • Select “Next >”.
  • Ensure “No, do not export the private key” is select and press “Next >”.
  • Select “DER encoded binary X.509 (.cer)” and press “Next >”.
  • Select where you want to save the file and give it a name and press “Next >”.
  • Finally, select “Finish”

Service-now requires that this certificate be in PEM format. You can convert this certificate using client tools or even online tools such as: SSL Shopper. Use the DER/Binary certificate we just created and export it to “Standard PEM” format.

 

ServiceNow SAML 2.0 Settings

Log into Service-Now as an administrator and browse to “SAML 2 Single Sign On” and select Properties. If SAML 2 is not listed, you will need to contact Service-Now to have it enabled.

The correct settings for this example would look something like the following (except for the fact that External Authentication is turned off):

ServiceNow SAML 2.0 settings for AD FS 2.0

After entering in the correct information, select SAVE and then browse to the “Certificate” page. At the top right corner, select the paper clip and attach the PEM certificate we created earlier. Sometimes the certificate’s fields such as Issue and Subject do not populate after selecting save and there may be an error on the top of the page. If this is the case, open the saves PEM formatted certificate in notepad and copy and paste the certificate in the “PEM Certificate:” field followed by clicking on “Update”. This page should have all the areas filled out.

 

AD FS Relying Party Configuration

At this point you could take the Service-Now Metadata and import it into your ADFS server. However, manual configuration of the Relying partner appears to be easier to implement.

Open the ADFS 2.0 Management console and select “Relying Party Trusts”.

  • Select “add Relaying party Trust…” from the top right corner of the window. The add wizard will appear. Click on “Start” to begin.
  • Select “Enter data about the relying party manually” and select “Next >”.
  • Give it a display name such as “Service-Now” and enter any notes you wish finished by selecting “Next >”.
  • Select AD FS 2.0 Profile and click “Next >”.
  • Do not select a token encryption certificate and click on “Next >”. It will use the certificate that is defined on the service that has already been exported. Defining a certificate here will prevent proper communication with Service-Now.
  • Do not enable any settings on the “Configure URL” and press “Next >”.
  • Enter the Service-Now website you connect to as the Relying Party trust identifier. In this case use ‘https://company.service-now.com and click on “Add” and then click “Next >”.
  • Permit all users to access this relying party and select “Next >”.
  • Click “Next >” on the Ready to add page and uncheck “Open the Claims when this finishes” then close. You should now know see the Relying Party in the window.
  • Right click on the Relying Party trust and select “Properties”.
  • Browse to the “Endpoints tab” and add a “SAML Assertion Consumer” with a “Post” binding and a URL of https://company.service-now.com/navpage.do.

AD FS Relying Party Claim Rules

Now is the time to edit the Claim rules in order to enable proper communication with Service-Now.

  • Right click on the Relying Party and select “Edit Claim Rules…”
  • On the Issuance Transform Rules tab select “Add Rules…”
  • Select “Send LDAP Attribute as Claims” as the claim rule template to use and select “Next >”.
  • Give the Claim a name such as “Get LDAP Attributes”. Attribute Store should be set to “Active Directory” and LDAP Attribute should be “E-Mail-Addresses” and the Outgoing Claim Type should be E-mail Address.

ADFS 2.0 Relying Party Claim Rules - Configuration Step 1

  • Select “Finish”.
  • Select “Add Rule…”
  • Select “Transform an Incoming Claim” as the claim rule template to use and select “Next >”.
  • Give it a name such as “Email to Name ID”. Incoming claim type should be “E-mail Address” (it must match the “Outgoing Claim Type in rule #1”. Outgoing claim type is “Name ID” (this is requested in Service-Now policy “urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress”) and Outgoing name ID format is “Email”. Pass through all claim values and click on “Finish”.AD FS Relying Party Claim Rules - Setup Step 2

 

  • If you edit the existing rule and click on “View Rule Language…” they should match the following:

Rule #1:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory",
types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"),
query = ";mail;{0}", param = c.Value);

Rule #2:

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType,
Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"]
= "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

Open internet explorer and browse to https://samportal.example.com/adfs/ls/idpinitiatedsignon.aspx and you will be at a generic page with a drop down list of all Relying Party Trusts configured. Select one you wish to log into and click on “Continue to Sign In”. Of course, it will only work if you have enables SSO on the Service-Now web page. If it is configured properly, then you should now be logged in. You can also create a direct link so users do not need to select from a drop down by browsing to https://samportal.example.com/adfs/ls/idpinitiatedsignon.aspx?logintoRP=https://company.service-now.com.

 

Now you should have an IdP initiated authenication method between ADFS 2.0 and ServiceNow SAML 2.0.

Again, many thanks to the research and documentation provided by John Gubatayao and David Pesano on this mini-project!

 

Post Project Notes

SP-Initiated Authentication

This blog did not cover getting SP-Initiated Authentication to work with ServiceNow and ADFS. For information on how to do this, see: Fixing SP Initiated Login with ADFS 2.0 and ServiceNow SAML