This information was last reviewed in June, 2018, by Scott Cantor.

Change Log:

This is not a replacement for the actual documentation and you cannot cut and paste your way to a working system. The examples are not usable without taking into consideration your local needs and requirements.

This is a page for documenting Shibboleth integration with Service-Now (abbreviated S-N in various places).

The official SAML documentation for the latest release is here at the time of authoring.

In the version being documented, the settings being documented are under "Multi-Provider SSO" and it is likely possible to restrict access to an administrator to just those settings.

When approaching this in a new instance of S-N, the first step is to proceed to the Plugins panel, find the Multi-Provider SSO plugin, and "activate" it, which can take a bit of time. It actually will attempt to migrate settings from the older SAML Single Sign-On plugin if they exist.

Identity Provider Metadata

Supposedly S-N has the ability to consume remote federation metadata (e.g., an aggregate from InCommon) and I believe this is tied into some discovery-like functionality that allows for multiple IdPs to be registered and used. I did not attempt to use this functionality and don't know if it works or how it works.

Independently of those features, the Multi-Provider SSO plugin has a set of IdPs that it can be directly configured with knowledge of, and it can populate each IdP's settings by uploading metadata to it. The list of IdPs is on a panel link called (naturally) Identity Providers, and creating a New entry will allow you to provide metadata that may work as is, or should eventually work with some editing. Eventually you'll get the settings to populate a form that provides direct access to edit various options, and most of the critical ones will be under that dialog:

Identity Provider URL (this is your entityID)
Identity Provider's AuthnRequest (this is your Single Sign-On Service Redirect binding endpoint)
Identity Provider's SingleLogoutRequest (this is your Single Logout Service Redirect binding endpoint)
ServiceNow Homepage (unclear why it doesn't know its own URL, but this appears to be the root of your S-N site)
Entity ID / Issuer (this is an arbitrary entityID for your S-N instance, so you set this yourself)
Audience URI (set this to the same value as above)
NameID Policy (if using the NameID to identify users, set this to the Format you want the IdP to provide)
External logout redirect (no idea, mine is external_logout_complete.do)
Failed Requirement Redirect (set this to a web page for handling login errors for this SP)

Your IdP's public signing key may be created via metadata import, or can be manually added at the bottom of the page, under X.509 Certificates.

Service Provider Metadata

S-N will produce SAML metadata that's not too horrible via a Generate Metadata button on the Identity Provider setup page (kind of backwards). It's not usually 100% correct or ideal but it's not awful and will at least fill in its entityID and endpoints. One thing about it that's useful is that you know if it's generating blank metadata the plugin isn't happy and won't work most likely, so that's a good warning.

Profile Requirements

Most of the basic settings are already dealt with up above in the Identity Provider setup section, and all of them are pretty much confined to that dialog.

I believe by default it is configured to send a <RequestedAuthnContext> in its requests. You probably don't want this, and need to uncheck the box on the Advanced tab.

Under Encryption and Signing, it's best to leave encryption off initially to get things working. You likely won't need to sign AuthnRequests, but do need to check the Sign LogoutRequest option to make logout work with a compliant IdP. Note that this algorithm is hardwired to SHA-1 and will not change based on the algorithm setting. This has been reported as a bug.

There are no particular special requirements to get things working on the Shibboleth side except if encryption is left off, and you can find examples of that in the documentation (and it should be temporary). If you want to skip that step, just continue.

To turn on encryption is a bit ugly. First, you need navigate to the x509 Certificate panel in the plugin and select the one named "SAML 2.0 SP Keystore", which has a file attached named saml2sp_keystore, a Java JKS keystore file. You will need to replace this attachment with a keystore you create yourself with the Java keytool utility. You should generatean RSA private key and assign it an alias and password of your choosing.

I did not have success using a keystore file with any name other than the "saml2sp_keystore" name it preloads by default, so I simply renamed my keystore to that name, removed the existing attachment, and replaced it with mine. You will provide the keystore password on that dialog, and save it.

Once that's done, you can return to the Encryption and Signing settings, and update it to set the key alias, the password, and check the Encrypt Assertion box. Once this is done, the Generate Metadata button should include the public key certificate in your keystore in its metadata, and the metadata should be updated on your IdP.

Example Shibboleth Configuration

Refer to the RelyingPartyConfiguration topic and be cognizant that creating overrides for every service is generally an inefficient use of the software. Consider identifying common requirements across services and create overrides tied to multiple services that share those requirements, or that reference profile configuration beans containing common settings.

Required Profile Configurations

SAML2.SSO

Optional Profile Configurations

SAML2.Logout

If you don't have the logout profile enabled, you would presumably have to clear out the relevant setting in the S-N Identity Provider dialog.

Account Provisioning

Apparently S-N supports just-in-time provisioning and update of the user records in some way, but I have no experience with those options.

NameID Requirements

S-N defaults to linking based on the NameID element, and has a field to set the Format to request from the IdP. It is unknown whether it actually cares what the Format is during a login, but it likely doesn't.

For example, if you wanted pass an employee ID in the element, use the standard name of the "employeeNumber" attribute as the Format to request, "urn:oid:2.16.840.1.113730.3.1.3".

The User Field box under Advanced sets the record field on the S-N side to link against.

Example Shibboleth Configuration

Refer to the NameIDGenerationConfiguration topic for a full treatment of NameID features.

Continuing with the example above, if you have an attribute definition named "employeeNumber" produced by your AttributeResolverConfiguration, release it to the S-N SP in your AttributeFilterConfiguration (example below).

Finally, to actually produce the necessary <NameID>, modify saml-nameid.xml as shown:

Example saml-nameid.xml changes

	<!-- SAML 2 NameID Generation -->
	<util:list id="shibboleth.SAML2NameIDGenerators">

		<ref bean="shibboleth.SAML2TransientGenerator" />

		<!--
		<ref bean="shibboleth.SAML2PersistentGenerator" />
		-->

		<!--
		Add custom support for employeeNumber-based NameID, assumes you've released
		the source attribute (employeeNumber) to any SPs expecting to get it.
		-->
		<bean parent="shibboleth.SAML2AttributeSourcedGenerator"
			p:format="urn:oid:2.16.840.1.113730.3.1.3"
			p:attributeSourceIds="#{ {'employeeNumber'} }" />

	</util:list>

Example attribute-filter.xml changes

	<AttributeFilterPolicy id="ServiceNow">
		<PolicyRequirementRule xsi:type="Requester" value="http://example.service-now.com" />

		<AttributeRule attributeID="employeeNumber" permitAny="true" />
	</AttributeFilterPolicy>

Attribute Requirements

S-N appears to support use of a SAML Attribute as an alternative to using a NameID to link against, but I have not tested it. It is presumed that doing this would require an Attribute Name provided in the "NameID Attribute" box on the Advanced tab, despite the odd name of the field, but this is unclear.

Other Considerations

To actually use SSO, S-N requires that you Test the IdP configuration via a Test button that triggers a login round trip, including logout. If that completes, it allows you to enable the IdP, and if desired set it for Auto Redirect such that any access to the front page will trigger a login. I ran into a variety of issues getting this to work that related to our older settings and couldn't say for certain how reliable it is for a fresh install, but I found the debugging available to be non-existent, and getting their support assistance may be needed if you don't have experience debugging integrations.