External Authentication (Single Sign-On – SSO)
2 SSO Techniques
3 Enabling External Authentication
4 Typical Process Flow (diagram)
5 Forcing Login via SSO Only
When single sign-on is enabled, it is often desired that a user never sees the ServiceNow login page and is never able to login locally. In other words, if a user attempts to go to https://customerX.service-now.com. they wish for the internal company portal to be displayed instead of the default ServiceNow login page. Likewise, when a user logs out of the application, they wish for the browser to be redirected to a specific internal page as well. This can be accomplished by setting a few redirection properties within the ServiceNow system.
5.1 Redirection Properties
When a user logs out, or if there is a failed SSO attempt, you can define where the user will be taken next, such as a main portal page, a knowledge base article with SSO login information, etc. This is done through the following properties where you specify the URLs. If one of these properties does not exist in your instance, you can create the property. The related properties are as follows:
- glide.authenticate.failed_requirement_redirect – 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 (ex. http://portal.companya.com/ ).
- glide.authenticate.failed_redirect – URL to redirect users after a failed SSO attempt. You can even redirect to a public knowledge article that describes the error and has helpful links (ex. http://portal.companya.com/error ).
- glide.authenticate.external.logout_redirect – URL to redirect users after logout, typically back to the portal that enabled the SSO.(ex. http://portal.companya.com/logout )
- glide.authentication.external.disable_local_login – When set to true requires SSO credentials even for the main ServiceNow login page. Defaults to false. This property needs to be used in conjunction with the ‘glide.authenticate.failed_requirement_redirect’ property.
The following table shows the relationship between the Installation Exit return values, the properties, and the expected behavior.
When this value is returned, it indicates that the required SSO credentials are not present in the session. Login fails and the session is redirected to the URL specified by the property. This is usually the URL for the SSO provider where login is challenged and credentials are collected.
When this value is returned, it indicates that the supplied SSO credentials failed authentication, the user does not exist, or the user is locked out. Login fails and the session is redirected to the URL specified by the property. This is usually the URL for the SSO provider where login is challenged and credentials are collected.
Login authorized for the user specified by user_id . This value matches with the field name defined in the SSO property glide.authenticate.header.value (“ServiceNow field name to match against the incoming header”)
5.2 Restricting Local Login
As a security precaution, it is advisable to do more than to simply rely on the redirection properties to prohibit logging in locally. If a user should never log in locally and will always be authenticated by your internal SSO, then a random password should be assigned to each user that is imported into the ServiceNow instance. The random password is most easily set at the time of the user import. If the user data is imported into your system through an import set, then a simple piece of code can be added to accomplish this goal. Create an onBefore transform script using the following code (of course, this may be tweaked to fit your needs):
6 Email Links with SSO
When using External Authentication (or SSO) that requires URL parameter additions, you will need to establish how you want links in email notifications to be handled. The out-of-box links simply contain a URL that directs you to a specific location in the instance, like an Incident or Change Request, without incorporating SSO credentials. Below are examples for directing the user to the location in the instance without them having to login on the instance login page.
- For the unencrypted HTTP technique, the following is an example URL to simply connect to the /demo instance (it does NOT navigate to specific record):
- The link (in an email notification) back to a specific ServiceNow record should appear as follows, so that the user first goes to the company’s own login portal:
To set this up you will need to set the “glide.email.override.url” property in your instance to contain the URL of the company portal page. If this property does not exist, you can create it.
- The company portal must then take that URL and construct the redirect URL to ServiceNow as follows, preserving the segment necessary to access the specific record, and adding the SSO credentials to the end of the URL:
7 Supplying Referring URL information to SSO Provider
During a login challenge resulting from a URL link into the instance that requires an SSO session, often times, the referring URL needs to be supplied to the SSO provider so that after authentication, it can be passed back to our instance and linked to the correct resource.
Installation exit return values have been enhanced to pass a URL instead of, or in addition to the URL defined by the properties (see Redirection Properties ). Usually, you would return a username or a predefined string value to control authorize or challenge the SSO session. The following examples show the extended behavior of passing a URL.
The example above passes the URL to the SSO provider in the form of a URL parameter named TARGET.
Note:It is assumed that the SSO provider will use that information in the TARGET parameter to redirect back to ServiceNow when the user credentials have been collected and authentication passed.
Notice the usage of : to demarcate the two return values, and the usage of an encoded (%26amp;) to conacatenate the URL defined in the property glide.authenticate.failed_missing_requirement and the TARGET parameter.
8 Monitoring the Event Queue for Login Failures
Every single sign-on integration creates the following events for login activities. You can use these events to monitor for login failures and determine if there are any security concerns to address.
9.1 Unencrypted HTTP example using ASP in IIS
The following article is an example using ASP running in IIS to redirect to a ServiceNow instance, supplying URL parameters for SSO:
9.2 Unencrypted cookie example using ASP .NET with C#
The following article is an example using ASP .NET with C# to redirect to a instance while supplying the necessary credentials for External Authentication in a cookie:
9.3 Digest encryption example
The following article shows a sample Java program using the Digest algorithm to encrypt a user name:
9.4 Visual Studio 2005 SSO solution
Download the following .zip file, extract to your hard drive, and you will get a folder containing a Visual Studio 2005 solution project. You can use this to help you develop your own Single Sign-on portal locally.