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)

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 the ServiceNow system. If the ServiceNow system finds a user with a matching NameID token (for example, the email address), the instance logs in that user.

Note
Note: It is recommended that customers using an existing SAML 2.0 integration upgrade to the latest SAML 2.0 integration update.


2 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.

2.1 SAMLResponse Validations

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

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

2.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.

2.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.

2.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 the ServiceNow system 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.

3 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.

3.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.

3.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).

3.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>

3.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.

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

4.1 1. User Clicks the Logout Button

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

4.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>

4.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.

5 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).

Note: If you are a Life Science Customer using E-Signature, you must deactivate the User self-lockout prevention business rule, which is new with Fuji. See KB0547061 for more information.

6 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.

7 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."

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)


9 Enhancements

9.1 Fuji

9.2 Eureka

9.3 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