How to configure JWT authentication for inbound API calls - Support and Troubleshooting

How to configure JWT authentication for inbound API calls Summary .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 your ServiceNow instance to accept inbound API calls using JSON Web Token (JWT) authentication. This article walks through creating a Java KeyStore, configuring JWT signing keys, setting up a JWT provider, and registering an OAuth application endpoint for external clients. This KB demonstrates how to set up the instance for inbound calls using the JWT token.

Release .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: ; } } All releases

Instructions .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: ; } } Complete these four major steps to create an application registry with an OAuth JWT API endpoint for external clients:

Create a Java KeyStore and upload it to the instance Configure a JWT signing key Create a JWT provider with a JWT signing key Connect to an OAuth provider and create an OAuth application registry Note : Only Steps 1 and 4 are mandatory to register a ServiceNow instance as a token provider. Steps 2 and 3 are included because a procedure for creating a JWT token is provided later in this article.

Step 1: Create a Java KeyStore and upload it to the instance A. Create a JKS file Run the following keytool command to generate a Java KeyStore file:

keytool -genkey -alias snclient -keyalg RSA -validity 365 -keystore snclient.keystore -storepass abcd1234 -keypass abcd1234

This command creates a file with the following properties:

File name : snclient.keystore Store ID : abcd1234 Key password : abcd1234 (These are examples only and must be replaced with strong passwords in production)

B. Import the certificate into the instance Import the certificate into your instance using the KeyStore password.

Note : Uploading the Java KeyStore is not mandatory when registering a ServiceNow instance as a token provider. Only substeps C and D are required. Substep B is included because a procedure for creating a JWT token is provided later in this article.

C. Export the certificate from the KeyStore Run the following command to export the certificate:

keytool -exportcert -alias snclient -keystore snclient.keystore -storepass abcd1234 -file snclient.cer

This command creates a .cer file named snclient.cer in the same folder.

To convert to PEM format, run:

openssl x509 -inform der -in snclient.cer -out certificate.pem

D. Create a certificate record in the instance Use certificate.pem to create a new record in the Certificate [sys_certificate] table.

Step 2: Configure a JWT signing key Create a JWT signing key record Go to System OAuth > JWT Keys . Select New . In the Signing Keystore field, select the KeyStore record you created in Step 1. Leave the Key ID field empty for now. You will update this field in Step 4. Note : The Signing Keystore field displays only certificate types supported by the selected KeyStore format (either Java KeyStore or BCFKS KeyStore).

Step 3: Create a JWT provider with a JWT signing key Create a JWT provider record Go to System OAuth > JWT Providers . Select New . In the Signing Configuration field, select the JWT signing key you created in Step 2. Save the record.

After you save the record, three standard claims are automatically created:

aud (audience) iss (issuer) sub (subject) Leave the claim values empty for now. You will configure these values in Step 4.

For more information about JWT claims, see the Related Links section.

Step 4: Connect to an OAuth provider and create OAuth application registry A. Create an OAuth application registry Go to System OAuth > Application Registry . Select New . Select Create an OAuth JWT API endpoint for external clients. Complete the required fields, including the User field (default is email). Save the record. Note : The User field value determines how the platform identifies the user. Verify this field is configured correctly

B. Configure the JWT Verifier Map On the application registry record, scroll to the JWT Verifier Maps related list. Select New . In the Sys Certificate field, select the PEM certificate you created. Copy the auto-populated kid (Key ID) value for use in later steps. In the Shared Key field, enter the shared ID you used when creating the certificate. Save the record.

C. Update the JWT provider claim values Note: This substep is not mandatory when registering the ServiceNow instance as a token provider. It is included because a procedure for creating a JWT token is provided later in this article.

Go to System OAuth > JWT Providers . Open the JWT provider record you created in Step 3. Update the claim values: aud (audience): Enter the Client ID from the application registry record iss (issuer): Enter the Client ID from the application registry record sub (subject): Enter the email address of the user to associate with the token Save the record. D. Update the JWT signing key with the Key ID Note : This substep is not mandatory when registering the ServiceNow instance as a token provider. It is included because a procedure for creating a JWT token is provided later in this article.

Go to System OAuth > JWT Keys . Open the JWT signing key record you created in Step 2. In the Key ID field, enter the kid value you copied from the JWT Verifier Map in substep B. Save the record.

Generate a JWT token After completing the setup, you can generate a JWT token and use it to obtain an access token.

Run the following script to generate a JWT token:

var jwtAPI = new sn_auth.GlideJWTAPI(); var headerJSON = { "kid": " " }; var header = JSON.stringify(headerJSON);

var payloadJSON = { "aud": "{client-id}", "iss": "{client-id}", "sub": "{email of the user for which the token needs to be associated to}" }; var payload = JSON.stringify(payloadJSON);

var jwtProviderSysId = " "; var jwt = jwtAPI.generateJWT(jwtProviderSysId, header, payload);

gs.info("JWT:" + jwt);

Example result

Note : Generating the JWT assertion is the responsibility of the client application. The client application must generate the assertion using its private key and the configured signing algorithm. This script is provided for informational purposes only.

Verify the JWT token Copy the JWT token generated by the script. Go to jwt.io to verify the token. For signature verification, use the value from the certificate.pem file you created in Step 1. After the signature is validated, proceed to testing.

Test the token using Postman Send a POST request to the following URL:

.service-now.com/oauth_token.do" target="_blank" rel="noreferrer noopener"> https:// .service-now.com/oauth_token.do

Configure the request with these settings:

Authorization : None Body type : x-www-form-urlencoded Include the following parameters in the body:

Parameter Value client_id Client ID from the application registry client_secret Client secret from the application registry grant_type urn:ietf:params:oauth:grant-type:jwt-bearer assertion Your JWT token value Sample response { "access_token": "wjphK8iz6_ixm8QdklkIm9Ps2Nq1t1NG9CqtKMNZvWwDEAIUD5Rc8hvZZXlWXPU9IHRFIe_VCfeh_hSuQ", "scope": "useraccount", "token_type": "Bearer", "expires_in": 1799 }

After receiving a successful response, you can verify the token in System OAuth > Manage Tokens .

Related Links .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: ; } } Introduction to JSON Web Tokens

JSON Web Token Claims