Digest Token Authentication Integration

Digest Token Authentication uses data, key and mac algorithms to generate digest data. A user accessed an instance with the digest data. This digest data is  compared against the digest data calculated within the instance. If the digest data matches then the user is authenticated.

How does the Digest Token Authentication work?

1. The user accesses the instance URL with a Digest token.
   • ex: https://<instance-name>.service-now.com?glide_sso_id=9bd23f131b121100227e5581be0713d7&SM_USER=admin&DE_USER=SuaGUdiqQZikiOfxcgQZALaQJpE=
   • **glide_sso_id is required if default or redirect IDP is not configured.
2. MultiSSO Digest Token Authentication uses MultiSSO_DigestToken installation exits to parse request parameters, cookies or headers.
3. NOW platform calculates digest value based on the digest token configurations configured within the platform.
4. MultiSSO_DigestToken installation exit compares digest data with digest data extracted ( DE_USER )from request parameters.
5. If digest data matches
   1. MultiSSO_DigestToken script validates user ( SM_USER ) against the user table.
   2. If there is a valid user record session is initialized for that user.
   3. else, the user is redirected to a failed SSO redirect page.
6. else, the user is redirected to a failed SSO redirect page.

Integration Setup

1. 1. Go to Multi-Provider SSO > Identity Providers > New > What kind of SSO are you trying to create? ( Select Digest )

      Name	Description
      DE_USER	Digest token is sent with DE_USER
      SM_USER	User field for lookup with the user table
      User Field	Name of the field  which is queried with the user table
      Secret Passphrase	secret key to encrypt/decrypt digest data ( ex:12345 )
      Single Sign-On Script	Select MultiSSO_DigestedToken. This script decrypts the token and authenticates the user
      Failed SSO redirect	page user redirected to post login failure
      External logout redirect	page user redirected to post logout

   2. Multi-Provider SSO > Properties > Enable multiple provider SSO

Supported Algorithms

The NOW platform uses the HmacSHA1 algorithm to generate digest token by default. If the HMAC algorithm needs to be changed please use the below steps.

1. Open MultiSSO_DigestedToken Installation Exit
2. Update MAC_ALG var with the MAC algorithm supported by Java.
   The Java 8 platform supports the below Mac Algorithms.
   1. HmacMD5
   2. HmacSHA1
   3. HmacSHA224
   4. HmacSHA256
   5. HmacSHA384
   6. HmacSHA512

How to generate digest data with scripting?

Run this script via System Definition > Scripts background to generate Digest data with different MAC algorithms

generateDigestData();
function generateDigestData(){
  //SM_USER
  var data="admin";
  //Secret Passphrase
  var secretKey = "12345";
  var MAC_ALG_1 = "HmacSHA1";
  var MAC_ALG_2 = "HmacSHA224";
  var MAC_ALG_3 = "HmacSHA256";
  var MAC_ALG_4 = "HmacSHA384";
  var MAC_ALG_5 = "HmacSHA512";
  var MAC_ALG_6 = "HmacMD5";

  //SncAuthentication.encode() function generates digest data.This is compared against DE_USER
  gs.print("Digest data generated with HmacSHA1: "+SncAuthentication.encode(data, secretKey, MAC_ALG_1));
  gs.print("Digest data generated with HmacSHA224: "+SncAuthentication.encode(data, secretKey, MAC_ALG_2));
  gs.print("Digest data generated with HmacSHA256: "+SncAuthentication.encode(data, secretKey, MAC_ALG_3));
  gs.print("Digest data generated with HmacSHA384: "+SncAuthentication.encode(data, secretKey, MAC_ALG_4));
  gs.print("Digest data generated with HmacSHA512: "+SncAuthentication.encode(data, secretKey, MAC_ALG_5));
  gs.print("Digest data generated with HmacMD5: "+SncAuthentication.encode(data, secretKey, MAC_ALG_6));
}

Output

*** Script: Digest data generated with HmacSHA1: SuaGUdiqQZikiOfxcgQZALaQJpE=
*** Script: Digest data generated with HmacSHA224: HcTdLXVPwfK+3MRsI1m9BN10xYXKGTqzWYmGMg==
*** Script: Digest data generated with HmacSHA256: IMafPR3HHBl+ykp7ACAfQqMffxtCI86Qv1oI8dqQJr0=
*** Script: Digest data generated with HmacSHA384: 3atp1KaQgbr7W+/Wr9Lq7/K+/OTGk1X5YkhF+d+DwiGpI2rSFBP7cC1FN3fDlhLR
*** Script: Digest data generated with HmacSHA512: c22+q9VaE720r4uWo19Ot9VTRQXQc1oXKHi3mnWB6G/A6gjDG55DXw6fg8JizH/Z5reovgW1oat8
eZTcqxyKcg==
*** Script: Digest data generated with HmacMD5: 8ETw8Cm8Az6JOuWzotRYZA==

Deep Linking

The NOW platform supports deep linking for digest token authentication. Include glide_sso_id, SM_USER, and DE_USER in the deep link URL for authentication.

https://<instance-name>.service-now.com/nav_to.do?uri=incident.do?sys_id=9d385017c611228701d22104cc95c371&glide_sso_id=9bd23f131b121100227e5581be0713d7&SM_USER=itil&DE_USER=UjHopjjPczCNpN2xcCXl7kQty4=

System logs

Set glide.authenticate.multisso.debug = true to print debugger messages in the System logs.

Login Successful 

Login Failure

Service Portal and CMS Redirection

The NOW platform does not support digest token authentication for CMS & Service Portal.This is because CMS & Service Portal has login page configured so user will be redirected to the platform configured login page.navpage.do is the only public page platform support digest token for authentication.

Workaround 1:

Service Portal has $sp set to true and CMS has view_content set to true in the sys_public table.Setting $sp= false and view_content = false allows platform to authenticate user with digest token authentication.This approach does not allow the user to access any public pages configured for Service Portal and CMS.

Workaround 2:

1. Configure the first page for CMS & Service Portal.
2. Configure login redirection  (see: Single sign-on, logins, and URL redirects)
   Service Portal
   
   CMS
   see: Define login scenarios
3. Authenticate with instance URL
4. The platform redirects the user to the first page ( landing page ) after authentication.

****Admin User:

Login URL

https://<instance-name>.service-now.com?glide_sso_id=9bd23f131b121100227e5581be0713d7&SM_USER=admin&DE_USER=SuaGUdiqQZikiOfxcgQZALaQJpE=

The user is redirected to navpage.do after authentication

*****ESS User:

Login URL

https://<instance-name>.service-now.com?glide_sso_id=9bd23f131b121100227e5581be0713d7&SM_USER=ess&DE_USER=er/ve0+vrkJxXlgA3dvjOn306PQ=

user is redirected to service portal ( first page/landing page ) after authentication

***Admin User

Login URL

https://<instance-name>.service-now.com/nav_to.do?uri=incident.do?sys_id=9d385017c611228701d22104cc95c371&glide_sso_id=9bd23f131b121100227e5581be0713d7&SM_USER=admin&DE_USER=SuaGUdiqQZikiOfxcgQZALaQJpE=

user is redirected to incident record after authentication.

***ESS User

https://<instance-name>.service-now.com/nav_to.do?uri=incident.do?sys_id=d297357ddb1ba300dca1f6dc0c96198a&glide_sso_id=9bd23f131b121100227e5581be0713d7&SM_USER=ess&DE_USER=er/ve0+vrkJxXlgA3dvjOn306PQ=

ess user is redirected to service portal after authentication.

See our documentation for the applicable versions: https://docs.servicenow.com/search?q=Digest+token+authentication

1. Check our documentation for Integration Setup, Sample Digest Token Implementations and deep linking within an instance:
   • https://docs.servicenow.com/search?q=Digest+token+authentication
   • https://docs.servicenow.com/search?q=Create+links+for+digest+authentication
2. Mac Algorithms supported by Java 8 at the time of writing this article.
   • https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Mac
   • https://docs.oracle.com/javase/8/docs/api/javax/crypto/Mac.html