SAML: Setting up Single Sign-on
Working with Multi-Provider SSO plugin
ServiceNow versions this applies to: London (and all prior versions)
It is very likely that you have been tasked with setting up Single Sign on but are not sure of how to approach an integration. Congratulations - if so, this is the article for you. Please follow the guided steps below.
Please keep in mind the below guide is for setting up a SAML connection specifically with SSO.
Overview
First thing you might be wondering... what is Single Sign on, exactly? Single Sign-On (herein called SSO) is a process by which a user on a company network can log into ServiceNow using their already established network account. This saves the user the hassle of having to keep track of several accounts (and their administrators from having to administer them!) As you might imagine, this is very appealing.
More often than not, SSO is used in conjunction with LDAP in ServiceNow - an important facet of SSO is having your SSO configuration line up with an account in the system, based on the unique identifier (often samaccountname). It is assumed for the purposes of this walkthrough that you are using LDAP or plan to use LDAP.
The general process flow between you (The Service Provider - SP) and the client (The Identity Provider - IDP) for "getting what you need" should flow as the below:
1) You provide them what is known as a Consumer URL and an Entity ID to the client (otherwise known as the IDP).
2) The client returns to you a metadata file with which you can import.
3) You identify whether the client would like authentication requests signed and encrypted assertions
4) You make the modifications on the ServiceNow side as the SP and Generate Metadata to return to the IDP.
5) The IDP tests the configuration to ensure it is working.
These steps need to be repeated for each instance - it is not recommended that you create an update set for SSO and promote up. You can follow the below steps to get started in greater detail. ServiceNow has a guide for SAML here, as well: https://docs.servicenow.com/bundle/geneva-servicenow-platform/page/integrate/saml/concept/c_SAML2.0WebBrowserSSOProfile.html
Futhermore, you can find the process flow for how SAML authenticates here: https://docs.servicenow.com/bundle/geneva-servicenow-platform/page/integrate/single_sign_on/concept/c_TypicalProcessFlowDiagram.html
Step 1 - Enable the Multi-provider SSO plugin
Before you begin, there is a plugin that must be enabled. Please navigate to "System Definition -> Plugins" and enable the plugin called Integration - Multiple Provider Single Sign-On Installer. This is needed for anything regarding SSO to begin.
Step 2 - Generate SP MetaData
In a hilarious catch 22, the IDP will often ask you for metadata before you even have any metadata to generate. This leads to a lot of confusion but the truth is that the two key pieces the IDP needs from you to get started, namely the Consumer URL and Entity ID, are things you already know without realizing it.
Your Entity ID is actually just the URL of your instance.
Your Consumer URL is https://MYINSTANCE.service-now.com/consumer.do
You should send these two pieces of information off to the technician configuring the SSO on the IDP side (client side), and ask them whether they need Assertions encrypted or if they need Signed Authentication Requests. They will need this to begin configuring SSO.
Step 3 - Import Client MetaData
Eventually after sending the client the above, you should receive a file of metaData you can import. This is usually a text file marked up as an XML. The great news is that this will alleviate a lot of the configuration concerns for you.
It is now time to start configuring the Identity Provider record in ServiceNow, which acts as the "main record" for your SSO configuration. Navigate to "Multi-Provider SSO -> Identity Providers". Click "New".
Click "SAML" to answer the interceptor "What kind of SSO are you trying to create?"
Now comes the easy part. Click the "XML" radio button and paste in the XML text that the IDP provided to you, and then click import. Just like that, you've imported almost everything relevant, including your x509 certificate issued from the IDP which is required. There are just a few extra parts you need to take care of.
If the client you are dealing with indicated they would like encrypted assertions or signed authentication requests, please proceed to step 3.5. If they did not indicate they need this, you can proceed to Step 4.
Step 3.5 - Configure Encryption
So, your IDP has indicated they would like assertions encrypted and authentication requests signed. While this sounds scary, it is in essence very easy. ServiceNow has something automatically configured called a default keystore which can be used to generate a 509 cert that the IDP can use to bind to, and in essence ensure that the SSO request they receive from your instance is, in fact, from your instance as it asserts.
Using the default keystore, there is very little you need to do to configure this. First, go to your Identity Provider record ("Multi-Provider SSO -> Identity Providers"). Make sure you click the one you are configuring in the step above.
You will see three tabs, the first tab being "Encryption and Signing". This is the one you want. First, we will need to use the keystore's Key Alias and Key Password. The Key alias and password for ServiceNow's default keystore is below:
Key Alias: saml2sp
Key Pass: saml2sp
Now, click the checkbox for "Encrypt Assertion" and "Sign AuthnRequest". Now, your instance will use the keystore to generate a 509 cert for the IDP to use. You're good to go for this step!
Step 4 - Test Connection and Save Identity Provider Record
Now that we've finished configuring our Identity Provider record, we must Test the Connection before we are allowed to activate it and set it as the Default IDP record. Please note the following as it is of utmost importance:
If you are on Jakarta or do not have access to the IDP from outside the client network, you will need to create a new property to circumvent having to test the connection successfully in order to active it. Go to sys_properties.list and add a new true/false property called "glide.authenticate.multisso.test.connection.mandatory" (without quotes). Set the value of this property to false. Return to your IDP record and the "Activate" UI action.
If you are running on a version other than Jakarta and have access to view the SSO solution from outside the client's network, click the "Test Connection" UI action. If you successfully connect, you make activate the IDP record. If this is to be the default identity provider, make sure you click the checkbox for "Default" and then save the record. Finally, there is a good chance you want users to auto-redirect to the SSO page here if they hit the instance. Go down to "related links" and click "set auto redirect IDP" to enable this functionality.
Step 5 - System Properties/Final Checks and MetaData Generation
As nice as it would be, not every configuration option is present on this Identity Provider page and some still need our manual configuration. Please ensure the following system properties are set (and they may already be set for you):
glide.authenticate.sso.redirect.idp - This should be set to the sys_id of the Identity Provider record you are working with.
glide.authenticate.sso.saml2.idp_authnrequest_url - This should be set to the base URL of the IDP's environment. You can take this straight from the imported metadata if needed.
glide.authenticate.sso.saml2.idp_logout_url - If you are using a specific logout URL, it should be here. Keep in mind this is completely optional and can be empty.
Some final checks before we generate the metadata - You may need to manually type in the "External logout redirect" field as it is not always automatically filled out by the imported metadata. Confirm what this should be in this case with the IDP.
Under the "Advanced" tab, ensure that the "User Field" record corresponds to the field you are matching on. If the IDP has their SSO configured properly, it should be "user_name". Last but not least, ensure that a "Single Sign-On Script" is present (If it is not, use the default "MultiSSO_SAML2_Update1").
Now that we have done all our final checks, head to "Administration -> Properties". Click the checkbox to "Enable multiple provider SSO" and click the checkbox to "Enable debug logging for the multiple provider SSO integration". The latter option will help you troubleshoot SSO issues during the testing phase. You can turn this off once your release/implementation is live.
Now return to your Identity Provider Record, and click the "Generate MetaData" button. Copy the contents, throw it into a text file, and send it off to the IDP. This is the last piece they need to configure items on their end.
Congratulations! If you followed the above steps correctly and the IDP has configured everything on their end correctly, your SSO implementation should be ready to go.
FAQ
Q: I was unable to generate metadata! Nothing happened.
Make sure you have popups for the instance enabled. Chrome will block the "Generate MetaData" button from doing anything because it considers it a popup. Just enable popups instance wide. If you are encrypting your assertions, ensure that you used the correct key alias and key password for the keystore! If you did not, the metadata will generate and appear blank. Double check that both the alias and password are just saml2sp
Q: I am getting the message "idp_metadata_url" in my log statements. Is this preventing my SSO from working correctly?
Simply put, No. This doesn't mean anything and I have implemented a few SSO configurations where this error is present but the config works fine. I believe this message has to do with the method used to initially import the metadata (either through XML or via URL). It is of no importance as far as I know.
Q: When the client tests the SSO configuration, they are getting a "No user found" issue.
This occurs when the SSO config can't match the SAM account name to anything meaningful in the system. If you have previously implemented an LDAP config, this error will definitely not happen. If your user table is empty, you should ensure you are doing the LDAP config before starting SSO. Otherwise, double check that the "User Field" on your Identity Provider record is correct and the proper field to match on (This same field is also present under the "Properties" page too). Under the "Advanced" tab, it may be necessary to specify a "NameID Attribute" in the event the client is using a non-standard naming format/convention.
Q: The IDP claims that the SSO config logs them out automatically before they have a chance to do anything.
Make sure that "External logout redirect" field on your Identity Provider record is set. This field does not always get properly imported via the metadata XML. Keep in mind you actually do not need to set a logout redirect at all if you so choose! It is entirely optional.
Q: LDAP isn't in scope or isn't a part of this effort, but the client still wants to implement SSO.
Take a look at the "User Provisioning" tab under your Identity Provider record. This provides a nice alternative if you cannot use LDAP for any reason. Click the option "Auto Provisioning User" to enable this functionality.
Q: The "Test Connection" button doesn't work!
If you are in version Jakarta this button is broken - it is a known issue that you can view in hi. You will need to create a new property called "glide.authenticate.multisso.test.connection.mandatory" (minus the quotes), with type as "true/false" and set the value to False.
Alternatively, if you are not on Jakarta and this button doesn't work, you may not have access to the view the IDP and IDP solution from outside the client's network. You will need someone from their side to help you verify that the SSO configuration is working.
Q: What do I do when the x.509 certificate that was imported via the metadata url from the IDP expires?
Nothing. It will poll the certificate authority for an update when it is nearing expiration and replace itself. In the event that, for some reason, it is unable to do this it will notify the user configured in the "Notify on expiration" glidelist field (Likely you) when it is 20 days from expiration by default.
Q: I tried everything and nothing is working
No you didn't - enable logging and check your logs! Most of, if not all of my issues were solved by identifying "Error" logs and resolving them. Don't forget to consider that the IDP you are working with may have misconfigured something.