You can configure an OAuth OIDC provider to accept identity tokens generated by a third-party OIDC provider using inbound API calls using Single Sign-On option (Multi-Provider SSO).

Before you begin

Role required: admin

About this task

The Now Platform supports OIDC through our external Single Sign-On (SSO) implementation in addition to inbound API calls. For an example of an OIDC provider configuration, see setting up Azure AD. For an SSO-specific example of an OIDC provider configuration, see Create an OpenID Connect (OIDC) configuration for Single Sign-On (SSO).

Procedure

  1. Navigate to All > System OAuth > Application Registry.
    • Select New, select Configure an OIDC provider to verify ID tokens, and then fill in the form.
    • Select an existing template for an OIDC provider (ADFS, Auth0, Azure AD, Google, Okta), and then fill in the form.
      Note: OIDC provider templates are available after loading demo data with the OAuth 2.0 plugin.
    FieldDescription
    Name A unique name that identifies the OAuth OIDC entity.
    Client ID The client ID of the application registered in the third-party OAuth OIDC server. This value should be the same as the value of the aud claim in the JWT token.
    OAuth API Script A script you can use to customize requests and responses to an external OAuth provider.
    OAuth OIDC Provider Configuration The OIDC providers (ADFS, Auth0, Azure AD, Google, Okta) can be used to validate the JWT token. Select the record of your OIDC provider configuration to validate the User Claim and User Field are set appropriately.
    Also, make sure to fill the following fields:
    • Enable JTI claim verification: When enables,the ServiceNow JWT token validation also validates the JTI sent by the provider.
    • OIDC Metadata URL: Details of the Well known configuration of the OIDC provider.
    Note: If validation isn’t checked, the jti can’t be validated, regardless if it’s present in the JWT token. The claim name in the token must be jti.
    Clock Skew The number, in seconds, for the constraint to be considered valid. The default is 300.
    Enforce Token Restrictions Select to only enable tokens to be used with APIs set to enable the authentication profile. You can set grant access using an API access policy. For more information, see Create REST API access policy.

    Default: Unselected.
    Active Select the check box to make the OAuth application active.
    Enable force authentication Option to enable force authentication for users.
  2. Select Submit.
    The record is saved in the Application Registries [oauth_entity] table.
    When your instance issues tokens and authorization codes it creates a record in the Application Registries [oauth_entity] table with type External OIDC Provider. See for more information.
  3. (Optional) Go to the related list on the record OAuth Entity Profiles to validate a system-generated default profile for the new OAuth provider without any scope.
    You can change or add an OAuth provider profile including the name, grant type, and OAuth Scope.
  4. (Optional) Go to the related list on the record OAuth Entity Scopes to define all available OAuth scopes for this OAuth provider.
    The scopes defined can be selected when you create or update a profile. Each OAuth scope defined contains a name and a scope that you must get from the provider specification, such as a read-scope or a write-scope. Each scope must be defined separately.
  5. (Optional) Go to the related list on the record User Provisioning to enable automatic user provisioning.
    OptionDescription
    Automatically provision users Option to enable force authentication for users.
    Provision data source The data source to use to transform an OIDC token to a ServiceNow user. Use the Lookup list to select the pre-defined data source template, then open the record to configure the Transformed table mapping. When configuring the Transform mapping, the source fields are from the JWT token, the target fields are from the sys_user table.
    User roles applied to provisioned users The user roles applied to the newly provisioned ServiceNow users.

Example: The following is an example of a cURL request to invoke a REST API call

Invoke a REST API call.

Perform the following steps:

  • Register the app in the OpenID Connect Provider.
  • Configure the OAuth OIDC Entity.
  • Configure the OIDC Provider:
    Table 1. OIDC Provider
    OIDC Provider Name of the OIDC provider.
    OIDC Metadata URL Specify the OIDC Metadata URL (well-known configuration URL). This information is used to fetch the public keys to validate the token through the jwks endpoint.
    User Claim The claim which is validated against user table.
    User Field User claim which identifies user record.
    Enable JTI claim verification When enabled, the ServiceNow JWT token validation will also validate the JTI sent by the provider.
    Note: If validation isn’t checked, the jti can’t be validated, regardless if it’s present in the JWT token. The claim name in the token must be jti. This information is used to prevent replay attacks.
  • Get a JWT token.
  • Invoke a REST API call.
    • The ID token in the Authorization header to access Table API or Scripted Web Service.
      curl -X GET --header "Accept:application/json" https://<instance_name>.service-now.com/api/now/table/incident/897b04f2dbd4a300a135364e9d961952 -k 
--header "Authorization: Bearer eyJraWQiOiJjNTZtZTlXU0xPVnY3UFMwcTg4Qzl1b0lzNjFQYTdmUG4yZFVFOW9RNUg4IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIwMHVnZDg1OD
VkczI1WXpUSjBoNyIsIm5hbWUiOiJpbXJhbiBhbGkiLCJsb2NhbGUiOiJlbi1VUyIsImVtYWlsIjoiaW1yb241NDNAZ21haWwuY29tIiwidmVyIjoxLCJpc3MiOiJodHRwczovL2Rldi05MzQ
xMjEub2t0YXByZXZpZXcuY29tIiwiYXVkIjoiMG9hZ2Q4bzk3a2lCT3dwd0IwaDciLCJpYXQiOjE1Mzc5MzMzMjYsImV4cCI6MTUzNzkzNjkyNiwianRpIjoiSUQueThVdXpWNUg2bm16SzRs
OTI1RFVrQnJoR1o1MmJzVVpGVHRVTEphQjg3ayIsImFtciI6WyJwd2QiXSwiaWRwIjoiMDBvZ2Q4NTgycEFqZDZTemcwaDciLCJub25jZSI6InNub3ciLCJwcmVmZXJyZWRfdXNlcm5hbWUiO
iJpbXJvbjU0M0BnbWFpbC5jb20iLCJnaXZlbl9uYW1lIjoiaW1yYW4iLCJmYW1pbHlfbmFtZSI6ImFsaSIsInpvbmVpbmZvIjoiQW1lcmljYS9Mb3NfQW5nZWxlcyIsInVwZGF0ZWRfYXQiOj
E1Mzc5MzAxOTcsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJhdXRoX3RpbWUiOjE1Mzc5Mjk2NjF9.OG87SYxWFgHGlhBYby2H79diRm9rlYZTeEkIINRUatwg-p4739htB8xEY-5_t6yU_6k5w1
0pdgtt5M5QFZRPXVbQZNoGtY-Bxn0BjaimcFgoWfhY_0ldnGTkzN2RYyIHvrf9-yhxg347zvczmLrgMMa_VwG4rxrtE6rUXaIpIeIK5b-Deq8ADz8UTUTKpF_5RWk4X-oh5xK6BLniFHk4ShO
Zq2v_mjproXwKk5euJKrVrar2lQ4adZCOSTRuTf3ThMO5WDh0sel-82LngXtLzRJJ51IqxAsXns0kJHLLqLtH1hXNRKfwT1ScQoE_OfWm4t0KryI2j4wSMEanFtLXIw"
    • If the user is authenticated a valid application/json response will be returned. Otherwise, a user not authenticated error message is returned.
      User Not Authenticated
{"error":{"message":"User Not Authenticated","detail":"Required to provide Auth information"},"status":"failure"}