Hello Folks! Happy New year!
As OIDC is picking up the pace as compared to the other options like SAML, its crucial to add more details around this specifically when it comes to debugging the OIDC flow.
In this article I am going to explain the OIDC SSO login debugging and a few other details. In the first section I will explain the basics of OIDC and how ServiceNow acts as a service provider in this case. In the second section of the article I have explained the detailed debugging steps.
OIDC (Open ID Connect) is the latest and modern identity protocol that is built on Oauth2.0.
- Core Purpose: Authentication protocol that lets applications verify user identity without handling passwords
- Key Components:
- Identity Provider (IdP): The trusted service that knows the user (e.g., Google, Okta)
- Relying Party (RP): The application that needs to verify user identity (ServiceNow here)
- End User: The person trying to log in
- How It Works:
- User clicks "Login with Okta" on your app
- App redirects to Google (IdP)
- User authenticates with Okta
- Okta sends back:
- Authorization Code + other details.
- Relying party calls Okta API to get ID Token.
- Relying Party establishes the session if ID Token is valid
- Initial Request
- App redirects user to IdP with:
- client_id
- redirect_uri
- scope (e.g., "openid profile email")
- state (for verification)
- response_type=code
- User Authentication
- User logs in at IdP
- IdP asks user to consent to requested scopes
- Authorization Code Return
- IdP redirects back to app's redirect_uri with:
- code (short-lived, one-time-use)
- state (same value for verification)
- Token Exchange (Backend-only)
- App server sends to IdP:
- Endpoint: /token
- code
- client_id
- client_secret
- redirect_uri
- grant_type=authorization_code
- IdP returns:
- ID Token (JWT with user info)
- Access Token (Mandatory)
- Refresh Token (optional)
- UserInfo Endpoint Call (optional, only if user provisioning enabled in servicenow)
- App server sends to IdP:
- App uses Access Token to request additional user info
- Endpoint: /userinfo
- Headers Format: Authorization: Bearer <access_token>
- IdP returns:
- Returns: Additional user claims about user
glide.authenticate.multisso.enabled
com.snc.platform.security.oauth.is.activeGlide Properties controlling the OIDC feature debugging in -
glide.authenticate.multisso.debug
Once the debug property is enabled, the additional debug logs will start generating for the OIDC SSO flow. Just by enabling the above mentioned SSO debug property, we can get most of the details like the which SSO record getting selected for Authentication, redirection URL with scopes, the auth code getting sent from the IDP, the returned result of the back channel call and why exactly the flow failed if happening so.
However, in case of failures, it may not present a clear picture since some of the transactions take place only in the back channel and no additional debug details are logged due to security reasons or due to heavy debug logs being generated by default.
As we have seen the OIDC flow for Servicenow, the first step is getting the auth code from IdP. This step is easy to debug, that is getting the auth code from the identity provider. As the action is performed between the IDP and browser client, auth code being received can be seen clearly in the browser URL. This step is complete once the IDP redirects the request to ServiceNow on the instance/navpage.do endpoint with Authcode and other parameters.
The next subsequent and important step is the back channel call in which ServiceNow hits the IDP token end point with the clientID, client Secret, AuthCode and other additional parameters. This is an outbound HTTP call to the IDP from ServiceNow which is a backchannel call (Server to server HTTP call) and to get the complete picture of what is happening behind the scene, two important debug steps to be taken -
Add debug logs in the OauthUtil script include to enable the additional debug logging. This is a relatively very simple step but its almost as effective as the other step next to it. The only case it fails into is when the outbound http request itself didn’t complete and failed for some reasons.
In this step, the idea is to add two debug statements in the OauthUtil script include and it requires appropriate access to edit both SSO configurations and script includes to make changes into it. Link of the script include is (instance to be replaced with actual servicenow instance)-
Code change to be done to get additional debug logs -
postprocessAccessToken: function(accessTokenResponse) {
var contentType = accessTokenResponse.getContentType();
if (contentType && contentType.indexOf('application/json') != -1) {
var tokenResponse = (new global.JSON()).decode(accessTokenResponse.getBody());
gs.debug("DebugOIDC:Response: " + JSON.stringify(tokenResponse)); //DEBUG
var paramMap = accessTokenResponse.getparameters();
for (param in tokenResponse){
paramMap.put(param, tokenResponse[param].toString());
gs.debug("DebugOIDC:param: " + param + ", Response: " + tokenResponse[param].toString()); //DEBUG
}
}
},
Once this change is done, you need to set this script include into Oauth OIDC entity record:
- Navigate to oauth_oidc_entity table, open the record corresponding to your OIDC IDP record (alternatively you can open the IDP record from the navigation, open the IDP record and navigate to the entity tab to get the same record).
- Once on the OIDC Entity record form view, open the Oauth API script selector field, search for OauthUtil script record which you modified above and select it.
This will ensure the changes we did are now effectively getting applied and it would print the required debug details. Now reproduce the issue again, then open the system logs and search with "DebugOIDC" keyword to get the required debug logs like this:
Below mentioned information can be retrieved using this debug step -
- Access Token, ID Token and other output parameters
- Complete response output of the http outbound call made to the IDP.
Outbound HTTP Debug logging
As this back channel call falls under outbound http category, enabling the outbound http debug logs will give the complete details of the back channel call.
Outbound HTTP Properties List - https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/outbound-web-services/ref...
Steps of enabling the debug properties and getting the debug logs -
- Properties to bet set for debugging OIDC SSO flow -
- glide.outbound_http.content.max_limit = 2000
- glide.outbound_http_log.override = true
- glide.outbound_http.file.log.allow.all.fields = true
- glide.outbound_http.text.content_types = application/x-www-form-urlencoded
- glide.outbound_http_log.override.level = all
- Once the above properties are set accordingly, navigate to All-> System Logs -> Outbound HTTP Requests. Log Table Name - sys_outbound_http_log
- Apply the filter in table list view on URL hostname column with URL hostname of the IDP. Alternatively filter can be applied on the URL path with "token" keyword. The exact endpoint looks similar to this - https://trial-account.okta.com/oauth2/default/v1/token.
- Once the exact http request has been identified, we can get the complete details from this like response status, failure reason, request parameters being sent from ServiceNow, response parameters being received etc. [refer to attached screenshots below]
Here is the sample request and response of a successful backchannel call:
Request -
Response -
1: The second step is only required/helpful if
- either the backchannel call fails, in which case you may not get the complete details.
- or you are not able to/don't want to make the changes into the script include mentioned above. However, you can revert the changes made into that script anytime to avoid any issues further.
2: The debug properties/http outbound logs/other customisations done in any of the scripts must be switched off due to below reasons.
- It continues to print ID token/Access token and other sensitive details in the debug logs.
- Debug log occupies additional disk space.
Happy debugging!
Cheers!
