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)

From Wiki Archive
Jump to: navigation, search
Note
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
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.


Overview

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.


Image:SSO_Flow1.png


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.

SSO Techniques

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:

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:

  1. Navigate to System Definition > Installation Exits.
  2. Activate the ExternalAuthentication installation exit.
    Note: If you are using the Digest authentication method, you must also enable the DigestSingleSignOn installation exit.
  3. Navigate to System Properties > Single Sign-on.
  4. Select Enable external authentication.
  5. Click Save.
Enable external authentication

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.

http://<your-instance>.service-now.com/side_door.do

Note
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)


Image:SSO_Standard.png

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.

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.


Return value Property 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

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): <source lang="javascript"> var r = new Packages.java.util.Random();

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):
https://<instance name>.service-now.com/?SM_USER=user_name&DE_USER=lQjIVp7aRJtyPx5+2O/vgU24tbE=
  • 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:
https://login.company_portal_page.com/nav_to.do?uri=incident.do?sys_id=009f8eda0a0a0b2b01ab4eb094223466%26sysparm_stack=incident_list.do%3Fsysparm_query=active=true

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:
https://<instance name>.service-now.com/nav_to.do?uri=incident.do?sys_id=009f8eda0a0a0b2b01ab4eb094223466%26sysparm_stack=incident_list.do%3Fsysparm_query=active=true&SM_USER=user_name&DE_USER=lQjIVp7aRJtyPx5+2O/vgU24tbE=

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.


Image:SSO_Target_Redirect.png


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=12345
to the SSO provider in the form of a URL parameter named TARGET.
Note
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."

Examples

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:

Sample ASP Script for Unencrypted Single Sign-OnSample ASP Script For Unencrypted SSO

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:

Sample ASP.NET with C Sharp Redirect with Cookies

Digest encryption example

The following article shows a sample Java program using the Digest algorithm to encrypt a user name:

Sample Java Digest Algorithm for Encryption

Sample C

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.

Visual Studio 2005 SSO solution