Practical guide for retrieving JWT token for inbound calls. - Support and Troubleshooting

Practical guide for retrieving JWT token for inbound calls. Summary This KB will demonstrate on how to set up the instance for inbound calls using the JWT token.

Release Rome and above

Instructions There are 4 major steps involved in creating an application registry with OAuth JWT API endpoint for external clients

Create a Java Key Store 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 OAUTH app registry STEP 1: Create a Java Key Store and upload it to the instance

Create a JKS file using the following keytool command

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

File name : snclient.keystore

Store ID – abcd1234 keypass – abcd1234

Import that cert into the instance with the key store password:

Export certificate from the keystore

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

A cer file will be created with the name snclient.cer in the same folder.

For PEM format you may use:

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

Use certificate.pem and create a new record in the instance.

STEP -2 : Configure a JWT signing key

Now Navigate to JWT keys under system OAUTH and create a new record and use the same keystore record created as below.

For now, ignore the key id and you can create a record without the key id, we will come back to this soon.

STEP -3 : Create a JWT provider with a JWT signing key

Now navigate to JWT provider and create a record by using the above record as signing configuration of the provider. Please refer below image:

Once you create this record you can see the above 3 standard claims created namely aud(audience), iss(issuer) and sub(subject). More about these here:

https://jwt.io/introduction

https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-claims

For now, leave the claim value empty we will cover this in the next steps.

STEP -4 : Connect to an OAuth provider and create OAUTH app registry

Now under OAUTH> Application registry, create a new app registry with the type "Create an OAuth JWT API endpoint for external clients"

NOTE : Ensure to fill in the User field (By default it will be email) this will be important as the platform will recognize the user using the field defined here.

In the related Lists under JWT Verifier Maps:

Create a JWT verifier map by selecting the PEM cert in the sys certificate column, please note that kid will be auto-populated here copy this for further use.

Now under the shared key just enter the sharedid that we used to create this cert.

Update JWT provider with the claim values specified in step-3 :

aud- clientid of the app registry record created.

iss- clientid of the app registry record created.

sub – email ID of the user that you want to use.

Now navigate to the JWT keys module and open the key which is created before in step-2 and update the kID with the auto-populated kid in the JWT map.

Now the setup is complete, we may proceed to creating JWT token and further generate access token using it:

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

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

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

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

Example result:

Copy the JWT token which is generated from the script.

Verify your JWT token here: https://jwt.io/ Once the signature is valid and verified proceed with next steps.

Note: For verifying the singnature you should use the value inside the certificate.pem file from step-1, it will look something like below:

TESTING TOKEN USING POSTMAN: Send a post call to the following url:

/oauth_token.do

Authorization: none

body

In body: x-www-form-urlencoded

client_id: client ID of the app

client_secret :Client secret of the app

grant_type : urn:ietf:params:oauth:grant-type:jwt-bearer

assertion :

Sample response:

{ "access_token": "wjphK8iz6_ixmYUY358QdklkIm9Ps2Nq1t1NG9CqtKMNZvWwDEAIUD5Rc8hvZZXlWXPU9IHRFIe_VCfeh_hSuQ", "scope": "useraccount", "token_type": "Bearer", "expires_in": 1799 } Now you can use can check the same Manage tokens