Loading

SAML 2.0 Web Browser SSO Profile

From ServiceNow Wiki
Home > Integrate > Single Sign-On > SAML > SAML 2.0 Web Browser SSO Profile
Jump to: navigation, search
Single Signon (SSO)


Contents

1 SAML 2.0 Overview

The Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization data between security domains. SAML exchanges security information between an identity provider (a producer of assertions) and a service provider (a consumer of assertions). SAML is a product of the OASIS Security Services Technical Committee. When implemented correctly, SAML is one of the most secure methods of single sign-on available.

The SAML 2.0 integration enables single sign-on by exchanging XML tokens with an external Identity Provider (IdP). The identity provider authenticates the user and passes a NameID token to ServiceNow. If ServiceNow finds a user with a matching NameID token (for example, the email address), the instance logs in that user.

Note
Note: ServiceNow recommends customers using an existing SAML 2.0 integration upgrade to the latest SAML 2.0 integration update.


2 SAML 2.0 Integration Requirements

The SAML 2.0 single sign-on integration requires:

  • Activating the latest SAML 2.0 plugin
  • Access to a SAML 2.0 Identity Provider (IdP)
    • Must provide an authentication request service
    • Must provide a single logout service
    • Must have a valid certificate
    • Must accept Service Provider (SP) metadata
    • Must use the NameID element in the SAMLResponse

2.1 Upgrading from Previous Versions

The following table lists the actions to take if you are running a previous versions of SAML.

Previous SAML version Action required
SAML 1.1 Contact Customer Support to migrate your instance to SAML 2.0 Update 1.
SAML 2.0 Update to SAML 2.0 Update 1. See Upgrading an Existing SAML 2.0 Integration to SAML 2.0 Update 1.


3 SAML 2.0 Setup

Use the following steps to install a new integration of SAML 2.0.

Note
Note: ServiceNow recommends customers using an existing SAML 2.0 integration upgrade to the latest SAML 2.0 integration update.


  1. Request the latest SAML 2.0 plugin.
  2. Set Identity Provider (IdP) system properties.
    1. Set the IdP issuer URL system property.
    2. Set the AuthnRequest service URL system property.
    3. Set the SingleLogoutRequest service URL system property.
    4. (Optional) Enable signed logout requests
  3. Set Service Provider (SP) system properties.
    1. Set the instance URLs system properties.
    2. Set the audience URL system property.
    3. Set the NameID policy.
    4. (Optional) Enable providing an authentication context class.
    5. (Optional) Set Keystore properties for signing logout requests
  4. (Optional) Set advanced system properties.
  5. Install the IdP certificate.
  6. Generate ServiceNow Service Provider (SP) metadata.
  7. Test the integration.
Note
Note: View the SAML 2.0 video tutorial for a demonstration.


3.1 Step 1. Request the Latest SAML 2.0 Plugin

Contact customer support to request the most recent version of the SAML 2.0 Single Sign-On plugin.

The plugin installs a new application called SAML 2 Single Sign-on.

Saml2 app.png

3.2 Step 2. Set Identity Provider (IdP) System Properties

An IdP generally offers an XML document containing their authentication and logout metadata. For example, SSOCircle publishes their metadata online.

Browse the IdP metadata to find these entries:

  • The SingleSignOnService element with a Binding attribute that contains a value of HTTP-Redirect. The Location attribute lists the URL the integration requires for the AuthnRequest service.
  • The SingleLogoutService element with a Binding attribute that contains a value of HTTP-Redirect.The Location attribute lists the URL the integration requires for the SingleLogoutRequest service.
Note
Note: The SAML 2.0 integration only supports binding to IdP services by HTTP-Redirect.


For example:

<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
Location="https://idp.ssocircle.com:443/sso/SSORedirect/metaAlias/ssocircle"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
Location="https://idp.ssocircle.com:443/sso/IDPSloRedirect/metaAlias/ssocircle"
ResponseLocation="https://idp.ssocircle.com:443/sso/IDPSloRedirect/metaAlias/ssocircle"/>
Identity Provider (IdP) System Properties

3.2.1 Step 2a. Set the IdP Issuer URL

Provide the URL to the IdP's who will issue the security token. The integration verifies that each SAML response contains the same URL listed in this system property as the URL listed in the Issuer element. For example:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  Destination="https://demoi2.service-now.com/navpage.do"
  ID="s28da6774c88ae1eab292bf25fe625db81919d8e1e"
  InResponseTo="SNC841720c227c81948cfd68cadcad235c6"
  IssueInstant="2012-01-30T20:07:10Z"
  Version="2.0">
   <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://idp.ssocircle.com</saml:Issuer>
   ...
   <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
     ID="s2f347f973c063836cf70ea38302d94976f9c5b851"
     IssueInstant="2012-01-30T20:07:10Z"
     Version="2.0">
      <saml:Issuer>http://idp.ssocircle.com</saml:Issuer>
      ...
   </saml:Assertion>
</samlp:Response>
  1. Navigate to SAML 2 Single Sign-on > Properties.
  2. In the property The Identity Provider URL which will issue the SAML2 security token with user info., enter the URL to your IdP.
    By default, the integration contains the URL to SSOCircle http://idp.ssocircle.com.

3.2.2 Step 2b. Set the AuthnRequest Service URL

Using the IdP's metdata, set the request service URLs for the integration's IdP.

  1. In the property The base URL to the Identity Provider's AuthnRequest service. The AuthnRequest will be posted to this URL as the SAMLRequest parameter, enter the URL to the HTTP-Redirect binding obtained from the SingleSignOnService element.
  2. Select the check box next to Sign AuthnRequest to enable the Identity Provider's single-sign on service to receive a signed AuthnRequest.
  3. In the property When SAML 2.0 single sign-on fails because the session is not authenticated, or this is the first login, redirect to this URL. This is the base URL where the initial SAML 2.0 AuthnRequest is sent using the SAMLRequest parameter, enter the URL to the HTTP-Redirect binding obtained from the SingleSignOnService element.
    By default, the integration contains the URL to the SSOCircle service.

3.2.3 Step 2c. Set the SingleLogoutRequest Service URL

Using the IdP's metdata, set the request service URLs for the integration's IdP.

  1. In the property The base URL to the Identity Provider's SingleLogoutRequest service. The LogoRequest will be posted to this URL as the SAMLRequest parameter, enter the URL obtained from the SingleLogoutService element.
    By default, the integration contains the URL to the SSOCircle service.
  2. In the property URL to redirect users after logout, typically back to the portal that enabled the SSO (e.g. http://portal.companya.com/logout), enter the URL where you want to redirect users after they successfully logout. If your IdP uses form-based authentication, enter the URL to your IdP's login form. If your IdP uses a non-form-based authentication method such as Kerberos, you should set the URL to a static logout page. This way, users who log out do not get immediately get redirected to the IdP and login again.
    By default, the integration contains the URL to the static UI page external_logout_complete.do.

3.2.4 Step 2d. (Optional) Enable Signed Logout Requests

Some IdPs require the Service Provider to sign logout requests with a certificate. If your IdP requires signed logout requests, use the IdP's metdata to set the following system properties.

  1. From the property Sign LogoutRequest. Set this property to true if the Identity Provider's SingleLogoutRequest service requires signed LogoutRequest, select Yes to specify that your IdP requires a signed logout request, or select No to use unsigned logout requests.
  2. If you selected Yes to Sign LogoutRequest, then in The protocol binding for the Identity Provider's SingleLogoutRequest service. (Value can be either "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" or "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST".) property, enter the one of the supported values listed in Binding attribute from the SingleLogoutService element.
    By default, the integration uses an HTTP-Redirect binding.
  3. Click Update.
  4. Install a Service Provider (SP) key store.

3.3 Step 3. Set the Service Provider (SP) System Properties

These system properties define how ServiceNow interacts with the IdP as a Service Provider.

Service Provider (SP) System Properties

3.3.1 Step 3a. Set the Instance URL

Set the instance-specific URLs.

  1. In the property The URL to the Service-now instance (usually this instance), enter the URL (including login page) of the instance for which the IdP authenticates. For example: https://yourinstance.service-now.com/navpage.do
  2. In the property The entity identification, or the issuer, enter the base URL (excluding login page) of the instance for which the IdP authenticates. For example: https://yourinstance.service-now.com/

3.3.2 Step 3b. Set the Audience URL

The Audience system property allows your instance to verify that it is the intended recipient of a SAML response. The integration verifies that each SAML response contains the same URL listed in this system property as the URL listed in the Audience element. For example:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  ID="s2cdc74f37f923e26fe1aeec42b70a93d24230334f"
  InResponseTo="90AA6073F01567BFB0DF194F596314E2"
  Version="2.0"
  IssueInstant="2010-04-29T23:21:51Z"
  Destination="https://dloomac.service-now.com/navpage.do">
...
<saml:Conditions NotBefore="2012-01-30T19:57:10Z"
  NotOnOrAfter="2012-01-30T20:17:10Z">
   <saml:AudienceRestriction>
      <saml:Audience>https://demoi2.service-now.com</saml:Audience>
   </saml:AudienceRestriction>
</saml:Conditions>
...
</samlp:Response>
  1. Navigate to SAML 2 Single Sign-on > Properties.
  2. In the property The audience uri that accepts SAML2 token. (Normally, it is your instance URI. For example: https://<instance name>.service-now.com.), enter the URL of your instance. For example, https://demoi2.service-now.com. This URL must match the value of the Audience element in the SAML Response.
  3. Click Update.

3.3.3 Step 3c. Set Up NameID Policy

SAML 2.0 requires the IdP to exchange a NameID token with the service provider. For the SAML 2.0 integration the NameID token must map to a particular field in the User table. The integration uses the NameID token's value to determine what ServiceNow user the IdP authenticates.

  1. Browse the IdP metadata to find the NameIDFormat element that contains a value of emailAddress. The value of this element is the default format that the integration uses.
  2. Review other NameIDFormat elements to determine if there are formats that match other fields in the User table.

3.3.3.1 Determine What User Table Field Matches the NameID Token

Identity providers specify what format the NameID token has. Setting up SAML 2.0 requires selecting a field from the User table that matches the format of the NameID token. Typically, IdPs offer the option to use an email address as the NameID token. Since the User table contains an email field, this field is a logical choice for use as a NameID token. To use another field from the User table as the NameID token, first verify that the IdP offers a NameID format that matches the value of a User table field. This may require adding the field to the User table.

  1. Compare the available formats in the IdP's NameIDFormat element to fields in the User table.
  2. Select a NameID format where there is a matching value in the User table.
  3. In the The User table field to match with the Subject's NameID element in the SAMLResponse field, enter the name of the User table field to search for matching values in the NameID token.
    By default, the integration uses the email field.

3.3.3.2 Set the IdP NameID Policy

Specify what format the IdP uses for the NameID token. This format is listed as part of the IdP's metadata.

  1. In the property The NameID policy to use for returning the Subject's NameID in the SAMLResponse. Your SAML identity provider will have to support this by declaring the policy in its metadata. The NameID value is used to match with the specified field in the User table to lookup the user., enter the value of the NameIDFormat element the integration uses.
    By default, the integration uses the SSOCircle NameIDFormat for email addresses.
  2. Click Save.

3.3.3.3 Add Appropriate Values to the User Table Field

Ensure that the integration's User table field contains appropriate matching values. For example, if the integration uses the email field as the NameID token, ensure that ServiceNow lists the same email address as the IdP. The integration fails to authenticate any user who does not have a matching value for the NameID token.

3.3.4 Step 3d. (Optional) Enable Providing an Authentication Context Class

You can enable ServiceNow to send an authentication context class request to the IdP containing your instance's preferred authentication request format. If you enable creating an AuthContextClass message, then you must also specify an authentication context class reference format.

Note
Note: Some IdP's do not allow the Service Provider to set the authentication context class. Disabling this setting allows the IdP to choose the authentication context class.


  1. From the property Create an AuthnContextClass request in the AuthnRequest statement, select Yes to specify a particular context class such as Password Protected Transport, or select No to have the IdP select the most appropriate context class.
  2. If you selected Yes to Create an AuthnContextClass request in the AuthnRequest statement, then in The AuthnContextClassRef method that we will request in our SAML 2.0 AuthnRequest to the Identity Provider property, enter the URN of the context class you want to use for authentication.
    By default, the integration uses a Password Protected Transport authentication method.
  3. Click Update.

3.3.5 Step 3e. (Optional) Set Keystore Properties for Signing Logout Requests

The Keystore properties allow the integration to sign logout requests using your signed server and signed CA certificates.

  1. In the property The alias of key entry stored in SAML 2.0 SP Keystore used to sign SAML 2 requests, enter the alias name you created for the SAML 2.0 Keystore. By default, the integration looks for the alias saml2sp.
  2. in the property The password of key entry stored in SAML 2.0 SP Keystore used to sign SAML 2 requests, enter the password to your SAML 2.0 Keystore. By default, the password is the same as the default alias name.
  3. Click Update.
  4. Regenerate your SP metadata.

3.3.5.1 Installing a Service Provider Key Store for Signing SAML Requests

Use the following steps to remove the existing example key store and install your own Service Provider key store containing your public and private key pair.

  1. Create a Service Provider key store.
  2. Navigate to SAML 2 Single Sign-on > Certificate.
  3. Click SAML 2.0 SP Keystore.
  4. Click the Manage Attachments link.
  5. Select the Delete checkbox next to saml2sp_keystore.
  6. Click Remove.
  7. Click Choose Files and select the Keystore containing your signed certificates.
  8. Click Attach.
  9. Close the Attachments popup.
  10. In Key store password, enter the password to access the SAML 2 alias.
  11. Click Update.

3.3.5.2 Creating a Service Provider Key Store

In order for your instance to sign logout requests, you must create a Java Key store containing the following items:

  • Signed server certificate for the ServiceNow instance
  • Signed CA certificate
  • Public and private key pair

You may create your own signed certificate with a private certificate authority or purchase one from a public certificate authority.

The following steps illustrate how to generate a new Java Keytool keystore file, create a certificate signing request (CSR), and import certificates. Any root or intermediate certificates need to be imported before importing the primary certificate for your domain. Type these commands in a command line interface.

Note
Note: These instructions are not specific to ServiceNow and require technical knowledge of security certificates to complete. Technical Support cannot assist in creating the certificates.


  1. Generate a Java keystore and key pair.
    keytool -genkey -alias mydomain -keyalg RSA -keystore my.keystore
  2. Generate a CSR for an existing Java keystore.
    keytool -certreq -alias mydomain -keystore my.keystore -file mydomain.csr
  3. Import a root or intermediate certificate authority CA certificate to an existing Java keystore.
    keytool -import -trustcacerts -alias root -file Thawte.crt -keystore my.keystore
  4. Import a signed primary certificate to an existing Java keystore.
    keytool -import -trustcacerts -alias mydomain -file mydomain.crt -keystore my.keystore

3.4 Step 4. (Optional) Set Advanced System Properties

The following advanced settings allow you to further increase security and debug the integration.

Advanced SAML 2.0 system properties

Property Description
The number of seconds "notBefore" constraint, or after "notOnOrAfter" constraint, to consider still valid Enter the number of seconds to add to the NotBefore and NotOnOrAfter constraints to account for time differences between the IdP clock and SP clock. These constraints prevent against replay attacks by denying requests that are not made within the specified time frame. If the IdP clock and SP clock are significantly different, network latency may result in the SAML request being unauthorized. This property adds a grace period during which SAML requests and responses are still considered valid.
Turn on debug logging for SAML 2.0 Authentication Select Yes to enable additional logging information for SAML 2.0 events.

3.5 Step 5. Install the IdP Certificate

Identity providers use a certificate to verify communications with the service provider. Locate the IdP's certificate within the IdP's metadata. You must install the same certificate on both the IdP and the ServiceNow instance.

To install the certificate on the ServiceNow instance:

  1. Browse the IdP metadata to find the ds:X509Certificate element. The value of this element contains the IdP's certificate.
  2. In ServiceNow, navigate to SAML 2 Single Sign-on > Certificate.
  3. Do not change the Name entry. The name of the X.509 certificate must be SAML 2.0 in order for the integration to use it.
  4. In the PEM Certificate field, enter the value of the ds:X509Certificate element.
  5. Click Save.

Saml2 cert.png

Note
Note: The integration does not currently sign the certificate when sending authentication requests to the IdP, however there is an option to sign logout requests.


3.5.1 Replacing a Missing Certificate

If the ServiceNow SAML 2 Single Sign-on > Certificate module displays a blank page, someone has deleted the SAML 2.0 certificate record.

To fix the missing certificate:

  1. Navigate to System Definition > Certificates.
  2. Create a new record called SAML 2.0.
  3. Click SAML 2 Single Sign-on > Certificate.
  4. In the PEM Certificate field, enter the value of the ds:X509Certificate element from your IdP's metadata.
  5. Click Save.

3.6 Step 6. Generate ServiceNow Service Provider (SP) Metadata

After setting all the integration properties, generate the instance SP metadata. The IdP needs the instance SP metadata to authenticate and forward requests.

  1. Navigate to SAML 2 Single Sign-on > Metadata. The integration automatically generates the instance's SP metadata from the system property settings.
  2. Copy the SP metadata in the text box. For example:
    <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
      entityID="https://demoi2.service-now.com">
      <SPSSODescriptor AuthnRequestsSigned="false" 
        WantAssertionsSigned="false" 
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
          Location="https://demoi2.service-now.com/navpage.do" />
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <AssertionConsumerService isDefault="true" 
           index="0" 
           Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
           Location="https://demoi2.service-now.com/navpage.do"/>
      </SPSSODescriptor>
    </EntityDescriptor>
  3. Provide the instance SP metadata to the IdP. For example, SSOCircle allows a user to provide the SP metadata online.

3.7 Step 7. Test the Integration

After completing all other setup tasks, test the integration.

  1. Log in to the instance as a user with the admin role.
  2. Navigate to SAML 2 Single Sign-on > Properties.
  3. In the property Enable external authentication, select Yes.
    Note
    Note: Enabling external authentication requires all users to use SAML 2.0 single sign-on. Thus, if anyone tries to access ServiceNow in an unauthenticated state, the instance automatically sends an authentication request to the (IdP) and redirects the user to the SAML IdP Authentication page.
  4. Click Save.
  5. Log out of the instance.
  6. Browse to the instance URL. If the integration is functioning properly, the IdP should ask for the users credentials.
  7. Provide the IdP user credentials. If the integration is functioning properly, the IdP should forward the user to the instance as the appropriate user.

3.7.1 Troubleshooting Login Errors

Here is a list of common login errors and their solutions.

Error or Symptom Solution
Authentication fails and the login request generates an infinite loop between ServiceNow and the IdP. Set (or create) the system property glide.authenticate.failed_redirect to redirect failed authentication requests to this URL. Typically the URL endpoint is an error page or logout page.
Login requests generate an infinite loop between ServiceNow and the IdP when High Security is active. The High Security plugin's rotating session feature can cause problems with the SAML 2.0 authentication process. Disable the rotating session feature when using SAML 2.0 for authentication. SAML 2.0 needs to redirect URLs to an IdP. When rotating sessions are enabled, any redirection causes the session to rotate and forces the instance to query the IdP again. This causes an endless loop of new sessions between the instance and the IdP.

For additional troubleshooting help, see SAML 2.0 Troubleshooting.

3.8 Examples of Third-Party SAML Identity Providers Configurations

While ServiceNow does not typically provide instructions for configuring third-party SAML IdP products, customers occasionally provide examples of how they have implemented their SAML IdP with ServiceNow. These documents provide examples of possible IdP setup configurations.

Note
Note: ServiceNow does not provide support for these example configurations.


Identity Provider Example Setup
Microsoft Active Directory Federation Services 2.0 Configuring ADFS 2.0 to Communicate with SAML 2.0
SSOCircle SSOCircle (Video Tutorial)

3.9 Cloning an Instance with a SAML Integration

Before cloning an instance that uses SAML 2.0, preserve the SAML SSO-related settings to prevent the target instance from redirecting all authentication requests to the original IdP with the wrong issuer and audience parameters. To preserve the settings:

  1. Navigate to System Clone > Preserve Data > Core Instance Properties.
  2. Ensure SAML SSO-related properties are preserved as shown below.
Preserving SAML SSO-related settings


4 Upgrading an Existing SAML 2.0 Integration to SAML 2.0 Update 1

The SAML 2.0 Single Sign-On - Update 1: security enhancements plugin improves integration security by requiring additional checks against the SAMLResponse URL parameter. The integration explicitly checks the SAML response for the proper Identity Provider (IdP) and intended audience URLs.

4.1 Additional SAMLResponse validations

With Update 1, the integration validates these elements in the SAMLResponse.

  • An Issuer element that matches the value listed in the issuer system property
  • The SubjectConfirmation and SubjectConfirmationData elements with a Recipient attribute
  • The AudienceRestriction and Audience elements that match the value listed in the audience system property

4.2 Support for Signed SingleLogoutRequest

With Update 1, the SAML 2.0 integration has the option to sign SingleLogoutRequest elements. Some IdPs, such as Microsoft ADFS, require a signed SingleLogoutRequest.

4.3 Support for AuthnContextClass

With Update 1, the SAML 2.0 integration has the option to specify the method by which the IdP authenticates the user in the AuthnContextClass element. For example, the integration can now specify contexts such as form-based Password Protected Transport or Kerberos. See Step 3d. (Optional) Enable Providing an Authentication Context Class for instructions on setting an authentication context class.

4.4 New Properties

The SAML 2.0 Update 1 plugin includes the following new system properties.

Property Description
The Identity Provider URL which will issue the SAML2 security token with user info.

glide.authenticate.sso.saml2.idp

Enter the value of the Issuer element that the integration uses to validate the IdP URL. See Sample SAML 2 Response with Issuer Element for a sample SAMLResponse message.
Sign LogoutRequest. Set this property to true if the Identity Provider's SingleLogoutRequest service requires signed LogoutRequest.

glide.authenticate.sso.saml2.require_signed_logoutrequest

Select whether the IdP requires a signed logout request.
URL to redirect users after logout, typically back to the portal that enabled the SSO (e.g. http://portal.companya.com/logout)

glide.authenticate.external.logout_redirect

Enter the URL where the integration redirects users after they log out. Typically, you set this property to a UI page if you are using Kerberos authentication to prevent users from being redirected back to the IdP and logging in again after a logout request.
The audience uri that accepts SAML2 token. (Normally, it is your instance URI. For example: https://<instance name>.service-now.com.)

glide.authenticate.sso.saml2.audience

Enter the value of the Audience element that integration uses to validate the SP URL in the SAMLResponse.
Create an AuthnContextClass request in the AuthnRequest statement.

glide.authenticate.sso.saml2.createrequestedauthncontext

Select whether to create an AuthnContextClass element in the SAMLRequest that specifies the login mechanism the IdP should use to authenticate the user. Not all IdPs support a AuthnContextClass element in the SAMLRequest. If you select Yes, you must specify the URN of the context class with the glide.authenticate.sso.saml2.authncontextclassref property.

The AuthnContextClassRef method that we will request in our SAML 2.0 AutnReqeust to the Identity Provider
glide.authenticate.sso.saml2.authncontextclassref

Enter the URN of the login mechanism you want the IdP to use to authenticate users. For example, by default ServiceNow uses the forms-based Password Protected Transport authentication context urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport.
The alias of key entry stored in SAML 2.0 SP Keystore used to sign SAML 2 requests.

glide.authenticate.sso.saml2.signing_key_alias

Enter the alias of the key that signs SAML 2 logout requests. You will have to create a Java Keystore for the alias.
The password of key entry stored in SAML 2.0 SP Keystore used to sign SAML 2 requests.

glide.authenticate.sso.saml2.signing_key_password

Enter the password for the key that signs SAML 2 logout requests.
The number in seconds before "notBefore" constraint, or after "notOnOrAfter" constraint, to consider still valid.

glide.authenticate.sso.saml2.clockskew

Enter the number of seconds between the two attributes that make up the SAMLResponse nonce. A valid SAMLResponse must fall between the notBefore and notOnOrAfter date-time values. See Sample SAML 2 Response with the SubjectConfirmation and SubjectConfirmationData Elements and Sample SAML 2 Response with the AudienceRestrictions and Audience Elements for a sample SAMLResponse message.

These properties are available with the Dublin release.

Property Description
AuthnRequest URL for eSignature Authentication.

com.snc.integration.saml_esig.idp_authnrequest_url

Enter the URL that points to the SAML 2.0 Identity Provider AuthnRequest Consumer for eSignature Authentication. In most cases, this will be the same as the AuthnRequest URL used in general authentication.

Leave this setting blank if you intend to use the same AuthnRequest Consumer URL that is used for general SAML 2.0 authentication in your instance.

The SAML 2.0 Assertion Consumer URL for eSignature authentication.

com.snc.integration.saml_esig.approval_consumer_url

In most cases, this URL will be: https://YOURINSTANCE.service-now.com/consumer.do. However, if you employ a customized method of handling the SAML authentication for eSignature, you can set up your own consumer URL.
The SAML 2.0 Assertion Consumer Index for eSignature authentication

com.snc.integration.saml_esig.assertion_consumer_service_index

If your Service Provider has more than one URL set for the AssertionConsumerURL, you can set the index to use for eSignature, starting with index 1 or more.
Authentication Pop-up Dialog Width

com.snc.integration.saml_esig.popup_dlg_width

When a user approves a request using eSignature, a dialog allows the user to enter their credentials. This setting controls the width of that dialog box.
Authentication Pop-up Dialog Height

com.snc.integration.saml_esig.popup_dlg_height

When a user approves a request using eSignature, a dialog allows the user to enter their credentials. This setting controls the height of that dialog box.

4.5 SAML 2.0 Update 1 Requirements

The SAML 2.0 update requires:

  • Activating the SAML 2.0 Update 1 plugin
  • Additional metadata from the SAML 2.0 Identity Provider (IdP)
    • SAML Request can include an AuthnContextClass element to specify the Service Provider's preferred login mechanism such as form-based authentication or Kerberos. If this element is not specified, the IdP chooses the login method.
    • SAML Response must include an Issuer element that matches the value listed in the issuer system property
    • SAML Response must include SubjectConfirmation and SubjectConfirmationData elements with a Recipient attribute
    • SAML Response must include AudienceRestriction and Audience elements that match the value listed in the audience system property

4.6 Update

Perform these steps to update your existing SAML 2.0 integration.

  1. Request the SAML 2.0 Update 1 plugin.
  2. Set the IdP issuer URL system property.
  3. (Optional) Enable providing an authentication context class.
  4. Set the audience URL system property.
  5. (Optional) Set advanced system properties.
  6. Merge customizations from existing scripts into new scripts.
  7. Test the update.

4.6.1 Request the SAML 2.0 Update 1 Plugin

Contact customer support to request the SAML 2.0 Single Sign-On - Update 1: security enhancements plugin. The plugin applies updated versions of the SAML2SingleSignon installation exit (login script), SAML2Logout installation exit (logout script), and SAML2 script include (script object).

4.6.2 Merge Customizations from Existing Installation Exit Scripts into New Scripts

The update saves an inactive copy of the integration's original installation exit scripts. You can use these copies to merge any customizations you made to the login and logout scripts to the new versions of these installation exits.

Original Installation Exit Script Name Original Script Status New Installation Exit Script Name New Script Status
SAML2SingleSignon Inactive SAML2SingleSignon_update1 Active
SAML2 Inactive SAML2_update1 Active
SAML2Logout Inactive SAML2Logout_update1 Active

You can navigate to the SAML 2.0 login and logout installation exit scripts using these paths.

  • SAML 2 Single Sign-on > Login script.
  • SAML 2 Single Sign-on > Logout script.
  • System Definition > Installation Exits.

You can navigate to the SAML 2.0 update 1 script include using these paths.

  • SAML 2 Single Sign-on > Script object.
  • System Definition > Script Includes.

4.6.3 Test the Update

Perform these steps to troubleshoot your integration update.

  1. Add a new system property called glide.authenticate.sso.saml2.debug with a value of true.
  2. Attempt SAML 2.0 login.
  3. Review the system log. SAML2 validation errors begin with the text SAML2ValidationError.
  4. Identify and fix any common login errors.

4.7 Sample SAML 2 Responses After the Update

The following sections illustrate the new required elements and attributes that the IdP should provide in the SAML Response.

4.7.1 Sample SAML 2 Response with Issuer Element

The following SAML 2 response uses the Issuer element.

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  Destination="https://demoi2.service-now.com/navpage.do"
  ID="s28da6774c88ae1eab292bf25fe625db81919d8e1e"
  InResponseTo="SNC841720c227c81948cfd68cadcad235c6"
  IssueInstant="2012-01-30T20:07:10Z"
  Version="2.0">
   <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://idp.ssocircle.com</saml:Issuer>
   ...
   <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
     ID="s2f347f973c063836cf70ea38302d94976f9c5b851"
     IssueInstant="2012-01-30T20:07:10Z"
     Version="2.0">
      <saml:Issuer>http://idp.ssocircle.com</saml:Issuer>
      ...
   </saml:Assertion>
</samlp:Response>

4.7.2 Sample SAML 2 Response with the SubjectConfirmation and SubjectConfirmationData Elements

The following SAML 2 response uses the SubjectConfirmation and SubjectConfirmationData elements with the NotOnOrAfter and Recipient attributes.

<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
   <saml:SubjectConfirmationData InResponseTo="SNC841720c227c81948cfd68cadcad235c6"
     NotOnOrAfter="2012-01-30T20:17:10Z"
     Recipient="https://demoi2.service-now.com/navpage.do"/>
</saml:SubjectConfirmation>

4.7.3 Sample SAML 2 Response with the AudienceRestrictions and Audience Elements

The following SAML 2 response uses the AudienceRestrictions and Audience elements with the NotBefore and NotOnOrAfter attributes.

<saml:Conditions NotBefore="2012-01-30T19:57:10Z"
  NotOnOrAfter="2012-01-30T20:17:10Z">
   <saml:AudienceRestriction>
      <saml:Audience>https://demoi2.service-now.com</saml:Audience>
   </saml:AudienceRestriction>
</saml:Conditions>

4.8 Configuring Users for Multi-Provider Single Sign-On

You can create and update SAML 2.0 Update 1 SSO configurations from the multiple provider single sign-on feature.

  1. Navigate to Multi-Provider SSO > Single Sign-On Properties.
  2. To update a configuration, click on an SSO configuration record.
  3. To create a new configuration, click New.
  4. Click SAML2 Update 1.
  5. Complete the form, using the fields from the table and submit the record.

For more information on multi-provider single-sign on, see Multi-Provider Single Sign-On.

Property Description
Name Enter the name for the SSO property record.
Active Select the check box to set the SAML configuration to active.
User Field Enter the field on the User table that contains the value the IdP needs to identify the user.
Identity Provider URL Enter the URL to your IdP.
Identity Provider's AuthnRequest Enter the URL to the HTTP-Redirect binding obtained from the SingleSignOnService element.
Identity Provider's SingleLogoutRequest Enter the URL obtained from the SingleLogoutService element.
Failed Requirement Redirect Enter the URL for redirecting failed authentication requests. Typically, the URL endpoint is an error page or logout page.
ServiceNow Homepage Enter the URL, including login page, of the ServiceNow instance for which the IdP authenticates. For example: https://yourinstance.service-now.com/navpage.do
Entity ID/Issuer Enter the base URL, excluding login page. of the instance for which the IdP authenticates. For example: </nowiki>https://yourinstance.service-now.com/</nowiki>
Protocol Binding for the IDP's SingleLogoutReuqest Enter one of the supported values listed in the Binding attribute from the SingleLogoutService element.
NameID Policy Enter the value of the NameIDFormat element the integration uses.
NameID Attribute Enter the name of the User table field to search for values that match the NameID token.
Create AuthnContextClass Select the check box to specify a particular context class such as Password Protected Transport. If the check box is cleared, the IdP selects the most appropriate context class.
AuthnContextClassRef Method Enter the URN of the login mechanism you want the IdP to use to authenticate users.
External logout redirect Enter the URL where the integration redirects users after they log out.
Signing Key Alias Enter the alias of the key entry stored in SAML 2.0 SP Keystore.
Signing Key Password Enter the password of the key entry stored in SAML 2.0 SP Keystore.
Clock Skew Enter the number of seconds between the two attributes that make up the SAMLResponse nonce. A valid SAMLResponse must fall between the notBefore and notOnOrAfter date-time values. See Sample SAML 2 Response with the SubjectConfirmation and SubjectConfirmationData Elements and Sample SAML 2 Response with the AudienceRestrictions and Audience Elements for a sample SAMLResponse message.
Force AuthnRequest Select the check box to force AuthnRequests to occur.
Is Passive AuthnRequest Select the check box if the AuthnRequest is passive.
Sign AuthnRequest Select the check box to enable the IdP's single-sign on service to receive a signed AuthnRequest.
Signing Signature Algorithm Enter the URL that points to the SAML 2.0 Identity Provider AuthnRequest Consumer for eSignature Authentication.
Single Sign-On Script Select the Single Sign-On script.
x509 Certificate Select the IdP certificate.

5 Login (AuthnRequest) Process Flow

SAML 2.0 specifies a Web Browser SSO Profile that involves exchanging information among an identity provider (IdP), a service provider (SP), and a principal (user) on a web browser. The identity provider can be any SSO service offering SAML authentication services (for example SSOCircle). The service provider is always a ServiceNow instance. The SAML 2.0 single sign-on integration supports the SP POST Request/IdP POST Response method.

This diagram illustrates a relatively simple deployment of the SAML 2.0 Web Browser SSO Profile where both the service provider and the identity provider (use the HTTP POST binding).

Login SAML 2.0 Web Browser SSO (POST)

The message flow begins with a request for a secured resource at the service provider.

5.1 1. Request the target resource at the SP

The principal requests a target resource at the service provider:

https://instance.service-now.com/

The ServiceNow instance checks the request to see if the SAMLRequest and RelayState URL parameters are present. If they exist, the user has already validated with the IdP and can skip steps 2–6.

5.2 2. Issue AuthnRequest to Identity Provider

ServiceNow instance constructs an AuthnRequest to be sent to the IdP using the SAMLRequest value. The instance also constructs and sends a RelayState URL parameter value.

The RelayState token is an opaque reference to state information maintained at the service provider. The value of the SAMLRequest parameter is the deflated and base64 encoded value of the <samlp:AuthnRequest> element:

  <samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="identifier_1"
    Version="2.0"
    IssueInstant="2004-12-05T09:21:59Z"
    AssertionConsumerServiceIndex="0">
    <saml:Issuer>https://sp.example.com/SAML2</saml:Issuer>
    <samlp:NameIDPolicy
      AllowCreate="true"
      Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/>
  </samlp:AuthnRequest>

The integration then URL-encodes the <samlp:AuthnRequest> element and sends it as the SAMLRequest URL parameter.

The SSO service processes the <samlp:AuthnRequest> element by URL-decoding, base64-decoding and inflating the request, in that order. It then performs a security check. If the user does not have a valid security context, the IdP identifies the user by prompting for login credentials. If the user is already logged in, the IdP simply responds with the SAMLResponse<tt> and <tt>RelayState URL parameters (see step 3).

5.3 3. Respond with an SAMLResponse and RelayState

After collecting the required login credentials, the SSO service validates the request and responds with a document containing an XHTML form:

  <form method="post" action="https://instance.service-now.com/navpage.do" ...>
    <input type="hidden" name="SAMLResponse" value="response ..." />
    <input type="hidden" name="RelayState" value="token ..." />
    ...
    <input type="submit" value="Submit" />
  </form>

The value of the RelayState parameter comes from this step. The value of the SAMLResponse parameter is the base64 encoding of the following <samlp:Response> element:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  ID="s2cdc74f37f923e26fe1aeec42b70a93d24230334f"
  InResponseTo="90AA6073F01567BFB0DF194F596314E2"
  Version="2.0"
  IssueInstant="2010-04-29T23:21:51Z"
  Destination="https://dloomac.service-now.com/navpage.do">
  <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">http://idp.ssocircle.com</saml:Issuer>
  <samlp:Status xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <samlp:StatusCode xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
       Value="urn:oasis:names:tc:SAML:2.0:status:Success">
    </samlp:StatusCode>
  </samlp:Status>
  <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="s23e536bfc51b8487d4d3299dec162d9c2e338823b"
    IssueInstant="2010-04-29T23:21:51Z"
    Version="2.0">
    <saml:Issuer>http://idp.ssocircle.com</saml:Issuer>
      <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
 
...
      </Signature>
      <saml:Subject>
          <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
            NameQualifier="http://idp.ssocircle.com" 
            SPNameQualifier="https://dloomac.service-now.com/navpage.do">david.loo@service-now.com</saml:NameID>
          <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml:SubjectConfirmationData
              InResponseTo="90AA6073F01567BFB0DF194F596314E2"
              NotOnOrAfter="2010-04-29T23:31:51Z"
              Recipient="https://dloomac.service-now.com/navpage.do" />
          </saml:SubjectConfirmation>
      </saml:Subject>
      <saml:Conditions NotBefore="2010-04-29T23:11:51Z"
        NotOnOrAfter="2010-04-29T23:31:51Z">
        <saml:AudienceRestriction>
            <saml:Audience>https://dloomac.service-now.com</saml:Audience>
        </saml:AudienceRestriction>
      </saml:Conditions>
      <saml:AuthnStatement AuthnInstant="2010-04-29T23:21:51Z"
        SessionIndex="s2dbf89ab99001e0e8cdaed67266d9d4b21b968a04">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
  </saml:Assertion>
</samlp:Response>

5.4 4. Validate SAMLResponse

The SAMLResponse value is base64 decoded and inflated to reveal the XML document in step 3. The ServiceNow login script extracts the XML value from the //Subject/NameID element and uses it to look up an existing user in the User table.

The login script also extracts the session ID from the //AuthnStatement/@SessionIndex element and stores it for the LogoutRequest.

6 Logout (LogoutRequest) Process Flow

During logout, ServiceNow issues the SAML 2.0 LogoutRequest service call to the IdP. This service logs the user out and then redirects back to the specified logout URL.

Logout SAML 2.0 Web Browser SSO (POST)

6.1 1. User Clicks the Logout Button

The user clicks the Logout button and the instance executes the logout script.

6.2 2. LogoutRequest issued

The logout script constructs a SAML 2.0 LogoutRequest and posts it to the preconfigured SingleLogoutRequest SAML 2.0 service at the IdP. The IdP deflates the request and then base64 encodes it. An example LogoutRequest looks like this:

<saml2p:LogoutRequest xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
  ID="21B78E9C6C8ECF16F01E4A0F15AB2D46"
  IssueInstant="2010-04-28T21:36:11.230Z"
  Version="2.0">
	<saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://dloomac.service-now.com
	</saml2:Issuer>
	<saml2:NameID xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
          Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
          NameQualifier="http://idp.ssocircle.com"
          SPNameQualifier="https://dloomac.service-now.com/navpage.do">david.loo@service-now.com</saml2:NameID>
	<saml2p:SessionIndex>s211b2f811485b2a1d2cc4db2b271933c286771104
	</saml2p:SessionIndex>
</saml2p:LogoutRequest>

6.3 3. User Logs Out

The user logs out of the IdP. The IdP redirects back to ServiceNow, which in turns redirects back to the IdP since the user is not logged in.

7 Adding Support for E-Signature

Configure the following properties for E-Signature with SAML 2.0 update 1 (starting with the Dublin release).

E-Signature with SAML properties

For an explanation of these properties, see New Properties.

If you are using E-Signature with SAML 1.0 or SAML 2.0 (not including update 1), see the special configuration instructions: Using E-Signature with Single Sign-On (SSO).

8 Adding Support for Deep Linking

Deep linking allows ServiceNow instances to support direct email links to a particular record in the system. With the SAML 2.0 integration enabled, deep-linking URLs must pass an authentication check before the IdP redirects the user to the originally requested URL. For example, if an email contains this URL:

https://<instance name>.service-now.com/nav_to.do?uri=incident.do?sys_id=46c88ac1a9fe1981014de1c831fbcf6d

The instance sends an authentication request to the IdP and uses the RelayState URL parameter to preserve the originally requested resource (in this case, uri=incident.do?sys_id=46c88ac1a9fe1981014de1c831fbcf6d). After the IdP authenticates the user, the instance reads the value of the RelayState URL parameter and redirects the user to the requested resource (if it exists in the instance).

To add support for deep linking verify that the identity provider supports the RelayState URL parameter.

9 Monitoring the Event Queue for Login Failures

The SAML 2.0 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
saml2.logout.validation.failed The logout response from the IdP failed validation against your logout request. The event validates the <inResponseTo> element against the session ID (ID attribute of the <saml2p:LogoutRequest> element). For example, see the workflow for Logout Request Issued.   Session ID The string, "SAML2 LogoutResponse validation failed.'
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."

10 Enhancements

10.1 Eureka

10.2 Dublin

  • A new set of system properties support using E-Signature with SAML 2.0 update 1.
  • Administrators can require the Identity Provider's single-sign on service to sign logout requests. Use the new system property glide.authenticate.sso.saml2.require_signed_authnrequest. See New Properties for more information.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance
Views
Personal tools