Set Up OAuth Client Credentials for the ServiceNow SDK

[Jon G Lind]

Start using OAuth in your continuous integration and continuous delivery (CI/CD) pipeline using an OAuth client credentials grant.

The ServiceNow SDK (Now SDK) can use it so that no person's password is stored in your CI system, such as GitHub Actions or Jenkins, and a leaked secret can be rotated on the instance without touching anyone's account.

Repeat these steps for each instance your pipeline touches, such as TEST and PROD.

Caution: these credentials can write to your instance without a human in the loop. Start on a sub-production instance and keep secrets out of version control.

Step 1: Create a service user

1. Create a user, for example cicd.deployer.
2. Set Identity Type to Human (you may need to add the field to the form view).
3. Give it the admin role.

Step 2: Enable the client credentials grant

Set the system property glide.oauth.inbound.client.credential.grant_type.enabledto true. Create it if it does not exist. See KB1645212.

Step 3: Create the OAuth integration

1. Go to System OAuth > Inbound Integrations > New Integration > OAuth Client Credentials Grant.
2. Set these fields:
   1. Name: SDK CI
   2. Provider Name: SDK CI Provider (type it in)
   3. OAuth application user: the service user from Step 1
   4. Allow access only to APIs in selected scope: unchecked
3. Save. Skip the "assign an auth scope" warning.
4. Copy the Client ID and Client Secret (keep this one safe!)

Step 4: Check the credentials

You can optionally set these variables in your terminal then run a read-only query to verify the credentials. A working credential prints {"ok":true.

Bash:

export SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL
export SN_SDK_AUTH_TYPE=oauth
export SN_SDK_INSTANCE_URL=https://your-instance.service-now.com
export SN_SDK_OAUTH_CLIENT_ID=<client-id>
export SN_SDK_OAUTH_CLIENT_SECRET='<client-secret>'

npx @servicenow/sdk query sys_user -q "active=true" --limit 1 -o json

Windows:

set SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL
set SN_SDK_AUTH_TYPE=oauth
set SN_SDK_INSTANCE_URL=https://your-instance.service-now.com
set SN_SDK_OAUTH_CLIENT_ID=<client-id>
set SN_SDK_OAUTH_CLIENT_SECRET=<client-secret>

npx @servicenow/sdk query sys_user -q "active=true" --limit 1 -o json

Use the credentials in GitHub Actions

Store the four values as repository variables and secrets, with a prefix per instance such as SN_SDK_TEST_ and SN_SDK_PROD_:

Name	Kind
SN_SDK_<NAME>_INSTANCE_URL	variable
SN_SDK_<NAME>_AUTH_TYPE (oauth)	variable
SN_SDK_<NAME>_OAUTH_CLIENT_ID	secret
SN_SDK_<NAME>_OAUTH_CLIENT_SECRET	secret

The setup walkthroughs linked below include a script that prompts for these and stores them with the GitHub CLI.

Next steps

1. Configure CI/CD with GitHub Actions and Now SDK
2. ServiceNow SDK documentation: CI integration