Please use docs.servicenow.com for the latest documentation.
This site is for reference purposes only and may not be accurate for the latest ServiceNow version
External Authentication (Single Sign-On - SSO)
| Note: This article applies to Fuji and earlier releases. For more current information, see Authentication at http://docs.servicenow.com
The ServiceNow Wiki is no longer being updated. Visit http://docs.servicenow.com for the latest product documentation.
|Note: Functionality described in this integration is not available by default. This integration involves post-deployment customization performed by an experienced administrator or by ServiceNow's professional services consultants.|
- 1 Overview
- 2 SSO Techniques
- 3 Enabling External Authentication
- 4 Typical Process Flow (diagram)
- 5 Forcing Login via SSO Only
- 6 Email Links with SSO
- 7 Supplying Referring URL information to SSO Provider
- 8 Monitoring the Event Queue for Login Failures
- 9 Examples
External Authentication, also referred to as SSO (Single Sign-on), is a method of access control that enables a user to log in once and gain access to the resources of multiple software systems without being prompted to log in again. It lets end users login to their company portal page and be directed to their ServiceNow instance pre-authenticated, without having to enter a user name and password again. This is very beneficial in large corporate environments where managing multiple user databases is prohibitive.
In the following sections we describe best-practice methods for Single Sign-On that are standards-based and provide a great deal of flexibility for implementing various SSO schemes and integration with major SSO products.
Before you enable External Authentication in your instance, you must decide how you want to pass authentication information to the ServiceNow system. It does not matter which SSO product you use, or whether your organization has written their own SSO solution. The ServiceNow system can integrate with any solution that uses one of the following techniques:
- Unencrypted HTTP Header
- Digest Token Authentication
- SAML 1.1 Browser POST Profile
- SAML 2.0 Web Browser SSO Profile
- Stateless Open ID with signature verification
- Multiple Provider Single Sign-On
Customers are successfully using SiteMinder, WebLogic, and their own internal solutions to integrate to the ServiceNow system using single sign-on.
Enabling External Authentication
To start using External Authentication you will need to:
- Navigate to System Definition > Installation Exits.
- Activate the ExternalAuthentication installation exit.
- Note: If you are using the Digest authentication method, you must also enable the DigestSingleSignOn installation exit.
- Navigate to System Properties > Single Sign-on.
- Select Enable external authentication.
- Click Save.
Bypassing External Authentication
Administrators may need to bypass external authentication when testing an SSO integration. Administrators can use the following URL to bypass external authentication and log in with a local ServiceNow user. Note that a logged-in user cannot access this page. Attempting to access this page while logged in produces a page not found error.
|Note: You can still log in as an inactive user if the user is not locked out. See Making a User Inactive for more information.|
Typical Process Flow (diagram)
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.
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.
|failed_missing_requirement||glide.authenticate.failed_requirement_redirect||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.|
|failed_authentication||glide.authenticate.failed_redirect||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.|
|<user_id>||N/A||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")|
Restricting Local Login
var str1 = Packages.java.lang.Long.toString(Packages.java.lang.Math.abs(r.nextLong()), 36); var str2 = Packages.java.lang.Long.toString(Packages.java.lang.Math.abs(r.nextLong()), 36);
var newPass = str1 + str2;
source.user_password = newPass;
//password now set to a random string like this: qvm81zdrn7cwwylpvw94eebk </source>
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:
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.
return "failed_missing_requirement:%26amp;TARGET=https://instance.service-now.com/nav_to.do?uri=incident.do?sys_id=12345";The example above passes the URL
https://instance.service-now.com/nav_to.do?uri=incident.do?sys_id=12345to 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.
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.
|Event Name||Description||Record||Parameter 1||Parameter 2|
|external.authentication.succeeded||External authentication succeeded and the user accessed the instance URL.||Session ID||User ID of user who successfully logged in||The URL the user accessed (which may be a deep link)|
|external.authentication.failed||The single sign-on requirements are not present or are missing.||Session ID||The missing authentication requirements|
|external.authentication.failed||The user does not exist in the User [sys_user] table||User ID||The string, "User does not exist"|
|external.authentication.failed||The user is locked out.||User ID||The string, "User locked out."|
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:
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:
Digest encryption example
The following article shows a sample Java program using the Digest algorithm to encrypt a user name:
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.