How to configure external ID token authentication (OIDC) for REST APIsIssue <!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Learn how to configure external ID token authentication using OpenID Connect (OIDC) to access the Table API or a Scripted Web Service with JSON Web Tokens (JWTs). OIDC is an authentication layer built on OAuth 2.0. It allows clients, including ServiceNow, to verify end-user identity by validating JWT tokens that contain user information. ServiceNow supports only JWT tokens for API authentication. A JWT, defined in RFC 7519, consists of three parts separated by dots: Header, Payload, and Signature. The payload contains claims that the system validates during token verification. How OIDC authentication works The instance admin registers an app with a third-party OIDC provider.The instance admin configures the OIDC provider in the instance, specifying the OIDC metadata URL, user claim, and user field.The instance admin sets up the OAuth OIDC Entity using the client ID [client_id] and client secret [secret_id] from the provider.API users obtain a JWT and include it in the Authorization bearer header when calling ServiceNow REST APIs.The instance checks whether the bearer token is an OAuth access token. If not, it validates the token as a JWT.The instance validates the JWT by verifying the signature, expiry, and user claim.The instance authenticates the request by matching the user from the JWT to a record in the User [sys_user] table. Authentication outcomes User found: The request is authenticated.User not found, auto user-import enabled: The system creates the user using a predefined transform map, and then authenticates the request.User not found, auto user-import disabled: Authentication fails and the API call returns a 401 error. JTI claim verification If Enable JTI claim verification is selected, each JWT can be used for only one API call. Subsequent calls using the same token fail. If this option is not selected, the instance does not check whether the JWT has been used previously. Integration setup Register the app with your OIDC provider Register your application with your OpenID Connect provider. Check your identity and access management solution documentation for provider-specific instructions. For a list of certified providers, see OpenID Certification. Set up the OAuth OIDC Entity configuration Go to System OAuth > Application Registry.Select an existing record (Demo data) or select New to create a new record.Select Configure an OIDC provider to verify ID tokens.Complete all required fields, including Client ID and Client Secret. Your OIDC provider supplies these values.Configure the OAuth Entity Scopes. Your OIDC provider supplies the scope details. Optimized version OIDC provider configuration fields OIDC provider configurations Description OIDC provider The name of the OIDC provider OIDC metadata URL The metadata URL for your OIDC provider. Check your provider documentation for this value. User claim The claim which is validated against user table User field The claim validated against the User [sys_user] table. Enable JTI claim verification When enabled, JWT validation includes verification of the JTI (JWT ID) sent by the provider. When disabled, the JTI is not validated even if present in the token. Get a JWT Use your OIDC provider to generate an ID token for the client program. Invoke a REST API call Include the ID token in the Authorization header to access the Table API or a Scripted Web Service. Example cURL request curl -X GET --header "Accept:application/json" https://<instance_name>.service-now.com/api/now/table/incident/897b04f2dbd4a300a135364e9d961952 -k --header "Authorization: Bearer eyJraWQiOiJjNTZtZTlXU0xPVnY3UFMwcTg4Qzl1b0lzNjFQYTdmUG4yZFVFOW9RNUg4IiwiYWxnIjoiUlMyNTYifQ..." If authentication succeeds, the API returns a valid application/json response. If authentication fails, the API returns an error message. User not authenticated error {"error":{"message":"User Not Authenticated","detail":"Required to provide Auth information"},"status":"failure"} JWT claim validations The Now Platform parses the payload in the JWT and compares it against the JWT claim validation configurations. If the configured values do not match the claims in the JWT, a validation error is logged in the localhost log. User provisioning To automatically provision users from OIDC claims, configure a data source and transform map. Create a data source with type OIDC.Associate a transform map with the data source.Select the data source in the OIDC provider configuration.Select Automatically provision users.Assign the appropriate roles. The Now Platform parses the claim values and populates the staging table. The transform map runs and loads data into the target table. Example of Import Sets screen Localhost log examples The following examples show key log entries for different authentication scenarios. Use these patterns to troubleshoot OIDC authentication issues. Note that transaction IDs, timestamps, session IDs, and user names will differ per instance. Successful authentication 2018-12-11 15:50:32 (275) API_INT-thread-2 SYSTEM txid=db83700edb1a DEBUG: Auth JWT token sucessfully verified for algorithm=RS256 2018-12-11 15:50:32 (299) API_INT-thread-2 SYSTEM txid=db83700edb1a DEBUG: Auth All claims are sucessfully validated. 2018-12-11 15:50:32 (319) API_INT-thread-2 SYSTEM txid=db83700edb1a HTTP authorization validated user 'oauth.admin' 2018-12-11 15:50:32 (319) API_INT-thread-2 SYSTEM txid=db83700edb1a Session user set to oauth.admin Failed authentication (JTI claim verification failure) 2018-12-11 13:16:59 (966) API_INT-thread-2 SYSTEM txid=a260184adbd6 SEVERE *** ERROR *** Failed in jti(JWT token_id) claim verification. Token is already used. 2018-12-11 13:16:59 (966) API_INT-thread-2 SYSTEM txid=a260184adbd6 WARNING *** WARNING *** Oauth authentication failed for access token ... No user found. 2018-12-11 13:16:59 (966) API_INT-thread-2 SYSTEM txid=a260184adbd6 WARNING *** WARNING *** Failed authorization by script include 'BearerAuth' 2018-12-11 13:16:59 (967) API_INT-thread-2 SYSTEM txid=a260184adbd6 #30849 [REST API] RESTAPIProcessor : User Not Authenticated 2018-12-11 13:16:59 (967) API_INT-thread-2 SYSTEM txid=a260184adbd6 DEBUG: Session inactivity timeout changed for unauthorized session. Inactive_interval=60 seconds Successful claims validation 2018-12-11 17:44:24 (316) API_INT-thread-3 SYSTEM txid=2f9dcd4edb9e DEBUG: Auth Going to verify claims:[name] 2018-12-11 17:44:24 (317) API_INT-thread-3 SYSTEM txid=2f9dcd4edb9e DEBUG: Auth JWT token sucessfully verified for algorithm=RS256 2018-12-11 17:44:24 (320) API_INT-thread-3 SYSTEM txid=2f9dcd4edb9e DEBUG: Auth All claims are sucessfully validated. Failed claims validation 2018-12-11 18:06:15 (276) API_INT-thread-1 SYSTEM txid=67925142dbde DEBUG: Auth Going to verify claims:[name] 2018-12-11 18:06:15 (278) API_INT-thread-1 SYSTEM txid=67925142dbde SEVERE *** ERROR *** JWT verification failed. exception:com.auth0.jwt.exceptions.InvalidClaimException: The Claim 'name' value doesn't match the required one. Troubleshooting Enable OAuth debugging Set the following system properties to true to enable detailed logging: com.snc.platform.security.oauth.debugglide.auth.debug.enabled Review logs and validate tokens Check the localhost log for error messages.Use an external JWT decoder to inspect token contents and verify claims. Release<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Beginning with the London release Resolution<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } This article provides configuration guidance. No resolution is required. Related Links<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Standards and specifications RFC 7519: JSON Web Token (JWT)OpenID Connect protocol documentationOpenID Certification (list of certified providers) Okta resources (example OIDC provider) Okta OIDC API documentationOkta Overview: OAuth 2.0 and OpenID ConnectOkta JWT validation guideSign up for an Okta developer account ServiceNow product documentation OAuth 2.0Inbound REST API authentication