SAML 2.0 Web Browser SSO Profile
|Note: The latest release this documentation applies to is Fuji. For the Helsinki release, see SAML 2.0. Documentation for later releases is also on docs.servicenow.com.|
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 2.0 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.
If you are using the SAML 2.0 plugin for Single Sign-on authentication, then you need to set the glide.ui.rotate_sessions property to false. Otherwise, it interferes with the session information sharing that takes place between ServiceNow and the Identity Provider. Users with the security_admin elevated privilege can access this high security property by selecting System Security > High Security Settings.
|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 Support for RSA SHA-256
The instance supports signing of SAML assertions with RSA SHA-256, which is recommended over SHA-1.
2.5 New Properties
The SAML 2.0 Update 1 plugin includes the following new system properties.
| The Identity Provider URL which will issue the SAML2 security token with user info.
|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.
|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)
|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.)
|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.
|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
|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.
|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.
|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.
|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.
| AuthnRequest URL for eSignature Authentication.
| 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.
|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
|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
|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
|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 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:
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">firstname.lastname@example.org</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.
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">email@example.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
When E-signature is active with Multi-SSO, SAML properties are not used. The system adds E-signature properties to the SAML2 Update1 Properties [saml2_update1_properties] table:
- Assertion Consumer Index for eSignature authentication: An index number that identifies the endpoint. The default value is 1.
- Assertion Consumer URL for eSignature authentication: your instance URL.
- AuthnRequest URL for eSignature Authentication: the URL for authentication.
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: 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)|
- Supports encrypted SAML assertions when Multi-Provider Single Sign-on is enabled. See Configuring Users for Multi-Provider Single Sign-On for descriptions of the settings you need to configure.
- Support for multiple provider single sign-in configuration. See Multi-Provider Single Sign-On for more information.
- 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.