I have taken the customizations suggested in my blog over the past few months and combined them into an update set that can be applied to enhance the configuration capabilities of your SAML 2.0 plugin in ServiceNow.

The New Settings

Here is the breakdown on some of the new settings:

Send the SP Name Qualifier attribute with the NameID Policy in our SAML 2.0 requests.
This setting allows you tell ServiceNow not to set a SP Name Qualifier attribute on our NameID Policy in the AuthnRequest statement. It is optional by SAML specifications. ADFS and Shibboleth both do not accept the statement as it has been implemented by ServiceNow. You can typically set this to “False” and be better off. It defaults to true simply to be backward compatible for people already using the SAML 2.0 plugin.

Create an AuthnContextClass request in the AuthnRequest statement.
The AuthnContextClass attribute is typically sent by default in the original plugin. This attribute tells the IdP that ServiceNow requires that they use a specific type of authentication for a user. Shibboleth, and ADFS in some situations, don’t like to be told how they should present their authentication to the user on their own IdP. Usually it is an environmental situation with Kerberos, or Proxy servers. You can now choose not to require a specific type of authentication mechanism and just let the IdP decide this.

The AuthnContextClassRef method that we will request in our SAML 2.0 AutnReqeust to the Identity Provider
If you do want to tell the IdP what type of authentication to present the user, then you can also specific what that type is. By default we have always sent a PasswordProtectedTransport requirement which is essential a form-based authentication page. However, you can allow the IdP to use their Kerberos setup by specifying urn:federation:authentication:windows as the context class ref. This setting lets you specify that as a configuration setting rather than by modifying the SAML scripts.

Other Enhancements

Unique SAML ID
In the past, ServiceNow has been sending the browser Session ID as the SAML request ID. However, the SAML specification states that this ID field needs to be unique for EVERY request. This ID can then be used by the IdP to help prevent replay attacks. This update set makes that ID unique for every SAML request that is sent by the system.

Making the AuthnRequest function scriptable
Most users won’t need this, but I have some ideas for a future integration, but it requires some flexibility in changing the AuthnRequest parameters based on a situation rather than on an instance. I made some changes that will facilitate that in the future if we ever go down that route.

Hardcoded attributes can be set via properties
There are a number of hard coded properties in our SAML statements. They are hard coded for a good reason. However, if there are any situations where we need to deviate from the default to support a new IdP, it would be nice to be able to create a property that overrides the hard coded attribute. Where I could safely, I changed most hard coded attributes to be override-able via system properties if necessary.

Handle Null Prefixes in SAML Response
Site-Minder and potentially other IdP’s do not provide a namespace prefix on their SAMLResponse when it comes back to ServiceNow. In these cases, the authentication process would always fail with ServiceNow, even after the user authenticated against the IdP. I modified the SAML code to handle this situation gracefully so that we can support Site-Minder SAML out of the box.

The Update Set

I will be working with the ServiceNow development team to get these changes into the plugin so that this update set won’t be necessary in the future. However, I have several clients that need these settings today. If you need some of the settings explained above, feel free to download the update set and give it a try. Please note that if you do use the update set, you do so at your own risk as this is not part of the product and is not covered by technical support. However, if something does seem to break, slip me a pizza and I might offer personal support of my own.

Download

SAML 2.0 Additional Config Options

If 2011 was the year of ADFS SAML 2.0 implementations in ServiceNow, then 2012 looks like it will be the year of Kerberos Authentication with ADFS and ServiceNow.

Over the past few weeks I have had a number of customers contact me regarding better support of their Kerberos authentication when they are using ADFS and SAML to do Single Sign-on with ServiceNow.

Thanks to some help from Microsoft, and a lot of coordination from a client in Switzerland, we have been able to provide better support for users who are logging into ServiceNow via Kerberos authentication with Windows.

The idea behind Kerberos authentication is that when you authenticate to the Windows desktop, you are establishing a SAML session. If someone browses to ServiceNow and they don’t have an active ServiceNow session, the SAML should detect that they have a SAML session alive through Kerberos and automatically authenticate the user into ServiceNow without having to type ADFS credentials.

However, with the current setup, regardless of the user having a SAML session via Kerberos, ServiceNow would redirect to the IdP and the IdP would display the ADFS login screen. It wasn’t detecting the Kerberos session.

The reason behind this situation is that the ServiceNow SAML plugin supports PasswordProtectedTransport for it’s authentication context. This is also known as “forms-based authentication”. This tells the IdP that the user should be presented a form by the IdP where they should authenticate. However, with Kerberos, the SAML session is already active through an established Windows login, so the user shouldn’t have to be presented a form for authentication.

The bad news here is that ServiceNow SAML 2.0 does not support Windows authentication out of the box. The good news, however, is that it is an easy customization.

The Theory

SAML has an attribute that tells the IdP what type of authentication we are expecting them to perform in order to qualify a user. This attribute is the AuthnContextClassRef. This element takes a URN string that identifies that method.

As mentioned previously, the PasswordProtectedTransport method indicates that we require form-based authentication. The string used to identify that is:

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

The Windows authentication methodology is specified by using this string:

urn:federation:authentication:windows

This tells the ADFS IdP that we are expecting that they try their Windows login in order to validate the authentication of a given user.

The Solution

New Update: If you download the update set that provides Additional SAML 2.0 Configuration Options then you will not need to modify the SAML scripts as outlined below.

In order to enjoy the full benefits of a Kerberos authentication setup with ADFS, perform the following steps:

1) Perform the steps outlined in my blog post: AD FS 2.0 working with ServiceNow SAML 2.0

2) Apply the fix outlined in Fixing SP Initiated Login with ADFS 2.0 and ServiceNow SAML

3) Modify the SAML “Script Object” according to these instructions:

Browse to the SAML application in ServiceNow and click on the “Script Object” module.

In the script that comes up, find the following line:

Comment out that line and add a new line as seen below:

Then, save the script.

Disclaimer

As this is not out of the box code for the ServiceNow SAML 2.0 plugin, it has not been thoroughly tested by a large number of users. Please use at your own risk.

Please also understand that by modifying an out-of-the-box script such as this, you will not automatically get future updates applied to this script.

Over the past few months I have had a few ServiceNow customers contact me with errors that they were seeing when using SiteMinder as their SAML federation service.

THE ISSUE

When their users would perform an Identity Provider (IdP) initiated login, their ServiceNow instance would throw the following error in the system log:

java.lang.IllegalArgumentException: prefix cannot be “null” when creating a QName
Caused by error in Script Include: ‘SAML2′ at line 41

38: document.normalizeDocument();
39: var metadataRoot = document.getDocumentElement();
40:
==> 41: var qName = new QName(metadataRoot.getNamespaceURI(), metadataRoot.getLocalName(), metadataRoot.getPrefix());
42:

The customers observed that SiteMinder creates a SAML2 Response without any namespace prefix:

When we are typically looking for something like this:

According to the JavaDoc on a Node object, if there is no prefix in an XML document, it will return null. However, this will conflict with the QName constructor. According to the QName JavaDoc, if there is no prefix, we need to use a different constructor that omits the prefix altogether.

PROPOSED SOLUTION

New Update: If you download the update set that provides Additional SAML 2.0 Configuration Options then you will not need to modify the SAML scripts as outlined below.

Change SAML2 script include (line 41) from:

to be:

This will first detect if there is a prefix on the SAML Response. If there is not, then it will call the appropriate QName constructor.

Many ServiceNow/ADFS clients have been having issues with their SAML SingleLogout from their ServiceNow instance to their ADFS Identity Provider (IdP).

I recently worked with a talented systems engineer, J Stephen Kowski, who was able to get SingleLogout to work for his company.

Here is a quick summary of what changes he did to get this to work.

Customize the SingleLogout URL in ServiceNow

In the SingleLogout URL property of ServiceNow, change the URL to something like:

https://s.myIdP.com/adfs/ls/?wa=wsignout1.0&wreply=https://s.myIdP.com/adfs/ls/?wa=wsignoutcleanup1.0

Customize the AD FS error script

Modify the file located in your “adfs/ls/” directory on your IdP web server. The file is: “error.aspx.cs”.

At the bottom of the file add the following code:

The above code should handle a common error that has been known to occur between service providers and ADFS.

Credits

As mentioned above, the credit for this solution goes to J Stephen Kowski. your results may vary according to your set up and environment, but let me know if it helps.

A few months ago I worked with a client to get AD FS 2.0 working with SAML 2.0 in a situation where ServiceNow is the Service Provider. However, at the time, we were unable to get an SP-initiated authentication scenario to work between SeviceNow and AD FS.

I recently came across some articles which keyed me into a probable cause of the SP-Initiated Authentication failures.

When someone tries to get to their ServiceNow instance in an unauthenticated state by going to their instance url (eg. https://myinstance.service-now.com), they would be redirected to the IdP login page. During that redirection, ServiceNow sends a SAML AuthnRequest so that the IdP will know how to process the login.

In the request, ServiceNow was sending the following NameID format element:

AD FS, however was responding that ServiceNow was sending an invalid NameIDPolicy.

After reading the SAML 2.0 Assertion Specification document, I came across the following text on lines 424-432:

NameQualifier [Optional]
The security or administrative domain that qualifies the identifier. This attribute provides a means to federate identifiers from disparate user stores without collision.
SPNameQualifier [Optional]
Further qualifies an identifier with the name of a service provider or affiliation of providers. This attribute provides an additional means to federate identifiers on the basis of the relying party or parties.

The NameQualifier and SPNameQualifier attributes SHOULD be omitted unless the identifier’s type definition explicitly defines their use and semantics.

This led me to believe that maybe the SPNameQualifier attribute could be causing errors with AD FS since we are not explicitly defining the use and semantics.

The Solution

New Update: If you download the update set that provides Additional SAML 2.0 Configuration Options then you will not need to modify the SAML scripts as outlined below. You only need to change the properties on the SAML Properties page.

To fix this issue, I visited the “SAML2″ Script Include and commented out two lines of code where we set the SPNameQualifier in the SAMLRequest.

In the “createNameID” function I commented out the following line:

//nid.setSPNameQualifier(serviceURL);

In the “createNameIDPolicy” function I commented out the following:

//nameIdPolicy.setSPNameQualifier(serviceURLStr);

Once I had saved this library I was able to perform an SP-initiated SAML authentication between ServiceNow and AD FS 2.0.

Some of my clients have come across an issue with ServiceNow and SAML 2.0. If they perform a successful SingleLogout in SAML, or they cancel out of their SAML login process, they are often returned to the main ServiceNow local login page with an error displayed in red at the top of the page saying:

Could not extract //Subject/NameID from SAMLResponse

I believe this is related to some changes that happened in the June 2011 release with regard to public pages in ServiceNow. The good news is that with a few configuration steps, you can have the browser redirect the user to a specific URL in these events so as to avoid this page and the display of the associated error.

Follow these simple instructions…

In your instance, go to the “Single Sign-on” module under the “System Properties” application.

Set the following fields:

• When a user attempts to access a page that is private (to view an incident, etc) and SSO credentials are not present, they will be redirected to the URL specified in this property. This is typically set to a customer’s login portal (e.g. http://portal.companya.com):
• When set to true requires SSO credentials even for the main Service-now login page. Defaults to false. This property needs to be used in conjunction with the ‘glide.authenticate.failed_requirement_redirect’ property.

They will be displayed something like this:

1. In the first field, put the URL where you would like to redirect the user after they click Cancel.
2. In the bottom property, make sure you type “true” and that will force the page to go to that URL when we come across and error such as the cancel.

Give is a few test runs to make sure everything works as you would expect and then you are good to go!

If you implement these settings, let me know how it works for you. I haven’t been able to test it in many scenarios, so I would like to know if there are any gotchas associated with it.

Because ServiceNow is a framed application, I often get asked by customers how to deal with any potential nested frame issues.

There are many ways to handle this, but often times it boils down to just inserting frame-busting javascript code in the right place.

An HTML document with the following javascript code snippet will detect if it is being displayed within a frame as it loads. If it is, it will break out of the frame and show that page as the main document in the browser.

Here is the code:

This code snippet is designed to go within the BODY of the HTML document.

Recently, ServiceNow added inbound WS-Security profiles as a SOAP interface option into the system. I have had several customers ask how this works, so I have created the following tutorial.

This article will demonstrate how to set up a self-signed certificate, generate a SOAP client that utilizes the certificate, and configure a ServiceNow instance to accept SOAP communication using the x509 Certificate WS-Security profile.

Create a self-signed certificate

The idea behind the x509 WS-Security profile is that you can sign your SOAP request and provide a key that a service can use to verify that the data in the SOAP request has not been tampered with. Typically, you would go through a certificate company to sign your certificates for third party consumption, but for testing, it is perfectly valid to generate your own certificate and sign it yourself.

Since many of my clients use Windows, we will create our self-signed certificate from a windows box. To do this, you need to make sure you have Java installed somewhere on your machine, and that the Java “bin” directory is in your PATH.

In a command shell, you can create and sign a certificate in one fail swoop by issuing the following command:

When you execute this command, the system will ask you some questions which you just fill in with arbitrary values. This is what it looked like for me:

This created a keystore file named: keystore.jks. It is a Java keystore that contains my new certificate and the public and private keys.

Down the road, I am going to need to store that certificate into ServiceNow in PEM format. So, right now I can make another “keytool” call to extract the certificate from the keystore and save it in PEM format:

This will create a file with a .pem extension that contains your certificate in PEM format. Here is what it looked like for me:

Set up SOAP-UI

For this tutorial, our SOAP client will be the free SOAP utility: SOAP-UI.

I first loaded my “incident” WSDL into SOAP-UI to create a new project.

Once the project is created, you want to double click on the project itself to view the properties.

On the project properties dialog, you will click the WS-Security Configurations tab, and then click on the “Keystores/Certificates” subtab. In the sub-panel that appears, you will want to click the “Add” icon to add the keystore that we created earlier.

Browse to the keystore file that we created and select it and click the “Open” button.

When SOAP-UI attempts to open your file, you will need to enter in the keystore password. Use the password that you entered earlier for the keystore.

Once you have completed this, your keystore should be listed in the Keystores/Certificates list. Make sure that your “Status” field is “OK”. If there was a problem loading your keystore, you will see an error there.

Now that we have loaded our keystore, we need to create an “Ountgoing WS-Security Configuration” profile that will leverage our keystore.

To do this, click on the “Outgoing WS-Security Configurations” subtab on the project properties dialog, and then click the “Add” icon. You will be prompted to provide a name for your configuration. You can name it anything as long as it is unique to the project.

Once you have created your configuration, you will need to click the “Add” icon in the lower pane to add the types of security your request will employ. You will want to select “Signature” since we will be signing our SOAP Request.

Now you should see the settings for signing a SOAP request. Select your keystore file name, the alias that contains your certificate & keys, and your keystore password. Make the Key Identifier type be: x509 Certificate. Use the RSA-SHA1 signing algorithm with the xml-exc-c14n canonicalization. Also, select the SHA1 digest algorithm.

Configure ServiceNow Instance

Now that our client is setup with our keystore, we need to configure ServiceNow to accept SOAP requests using the x509 WS-Security profile.

First we need to load the certificate that will be used by SOAP-UI to sign the request. If you recall, we created a PEM version of the certificate just after we created the keystore file. You will want to copy the contents (PEM String) from that file and copy it into a new Certificate record in ServiceNow. Then click the “Submit” button.

Once you have done this, your certificate record should be listed with any other certificates you may have loaded into your instance.

Now we need to set up a WS-Security profile in ServiceNow to accept and validate x509 signed SOAP requests.

Browse to the “WS Security Profiles” module inside of the “System Web Services” application. Once you are there, create a New profile by clicking on the new button.

From here you select the x509 profile and select the user you would like this profile to execute as with the SOAP action. You will also need to select the Certificate record we just created so that we can validate the signature.

You may wish to restrict all SOAP requests to use WS-Security when they come into your instance. If you choose to do so, you will need to select the setting found in the “Properties” module of the “System Web Services” application that enforces WS Security for inbound SOAP requests.

Your instance is now configured to accept signed SOAP requests with an x509 token.

Test your setup

In order to test this, we go back to our SOAP UI project and create a Request on the “getRecords” web service function.

We are going to request three active incident records using the following XML:

We will paste that XML into the request window. Then click on the “Aut” button at the bottom of the request dialog box in SOAP-UI. There you will need to enter your basic authentication credentials. (At this point in time ServiceNow requires that you use BasicAuth in conjunction with a WS-Security profile). Finally, select the Outbound WS Security configuration that we created earlier.

Once you submit your request through SOAP-UI, you should successfully connect, authenticate, and receive the response you requested:

I recently worked with a colleague on an issue that he was seeing when trying to connect into a ServiceNow instance via SOAP.

He would import the WSDL file into SOAP-UI or any other SOAP client using a WSDL URL similar to:

https://myinstance.service-now.com/mytable.do?WSDL

The WSDL would import properly and load up all of the available SOAP functions. However, when he would try to execute one of the functions, he would get the following response (trimmed down a bit for this article):

The user was including the proper authentication credentials and we were able to verify that those credentials had the necessary roles. However, something was still amiss.

After careful observation, we noticed that the WSDL was stating that the SOAP Endpoint was available via “HTTP” instead of “HTTPS”. This was due to a misconfiguration one a switch in one of the data centers.

There were two ways the customer could immediately fix this issue so that they could move on with their integration without having to wait for support to manage the issue.

1) They could manually change the endpoint in their SOAP client to be HTTPS instead of HTTP. However, they would need to do this for every SOAP client that was connecting into their instance. Not necessarily the best route to take if they have many integrations.

2) They could create (or set) the following property with their base url as instructed by the wiki:

com.glide.soap_address_base_url

Once either of these solutions were implemented, the customer was once again up and running.

I have had a lot of people come to me with questions on where to get started with their SAML 2.0 Single Sign-on plugin.

In order to help people out a little quicker, I have created a video that demonstrates the steps that are required to take in order to set up the SAML 2.0 plugin in ServiceNow with SSOCircle.com, a free, public Identity Provider (IdP).

While companies will not typically use SSOCircle.com as their identity provider, it allows me to demonstrate the basic steps that an individual would need to take in order to set up their ServiceNow instance with their own IdP.