OAuth 2.0 credentials for GitHub Apps - JWT

Perform the following steps to integrate your GitHub Apps using the JWT bearer token.

Before you begin

Role required:

• oauth_admin in DevOps Change Velocity.

• Admin account in GitHub.

  Note: The OAuth 2.0 JWT grant type is supported for GitHub & GitHub Enterprise with MID server.

Configure the GitHub App in your GitHub account (JWT)

Create a custom GitHub App from your GitHub account to enable OAuth 2.0 authentication with your ServiceNow instance.

Before you begin

GitHub requirement: GitHub App configured to integrate with ServiceNow

Role required: No instance role required

About this task

Complete these steps from your GitHub account. See Building GitHub Apps on the GitHub Developer site for instructions on creating and configuring custom applications.

Procedure

1. From your GitHub account, create your GitHub App by navigating to Developer Settings > GitHub Apps.

2. In the Homepage URL field, enter https://<instance-name>.service-now.com.

3. In the User authorization callback URL field, enter https://<instance-name>.service-now.com/oauth_redirect.do.

4. In the Identifying and authorizing users section, deselect the Expire user authorization tokens field.

5. In the Webhook section, select the Active field.

6. In the Webhook URL field, enter https://<instance-name>.service-now.com/api/sn_devops/v2/devops/tool/apps?toolId=<Tool ID>, where Tool Id is your GitHub tool id (sys_id) from DevOps Change Velocity.

   Note:

   If you are newly creating the tool and don't have the Tool ID, you can enter the webhook URL without the Tool ID and configure it later. To configure later:

   1. Navigate to the connected tool's tool record page.
   2. Select Configure GitHub App, then select Auto configure with existing token.

This configures the Webhook URL of the GitHub App automatically.

You can get the Tool ID in one of the following ways:

-   While connecting with the tool in DevOps Change Velocity, the Tool Id is available in the page URL. For example, `https://<instance-name>.service-now.com/.../sn_devops_tool/<Tool ID>/...`.
-   You can copy the webhook URL from the GitHub tool record page in DevOps Change Velocity, from **Configure** &gt; **Configure manually** &gt; **Webhook URL**.

1. Leave the remaining fields empty (default).

2. In the Repository permissions section, configure the following settings.

**Note:** If you are already using a GitHub App and you update any of the permissions, you must review and accept those permissions for your GitHub App. You can navigate to your app, and select **Configure > Review request > Accept new permissions**.

1. Leave the remaining permissions as No access (default).

2. In the Subscribe to events section, select the Deployment protection rule option.

3. Save the changes.

4. After creating the GitHub App, generate a new private key and save it to your machine.

5. Install the newly created GitHub App on the accounts of your choice.

   1. From the GitHub Apps settings page, select your app.

   2. In the left sidebar, select Install App.

   3. Select Install next to the organization or personal account containing the correct repository.

   4. Install the app on all repositories or select repositories.

      For more information, see Installing GitHub Apps.

Generate the Java KeyStore certificate for GitHub

Generate a Java KeyStore (JKS) certificate for the JWT authentication.

Before you begin

Role required: admin

Procedure

1. Create a CA signed certificate using the GitHub App private key:

   openssl req -new -x509 -key <file-name>.pem -out <certificate-name>.pem -days 1095
   

2. Enter the required details.

3. Create the PKCS 12 file using the GitHub App private key and CA signed certificate:

   openssl pkcs12 -export -in <certificate-name>.pem -inkey <file-name>.pem -certfile <certificate-name>.pem -out <PKCS-12-file-name>.p12 
   

4. Provide the export password.

5. Create the JKS file:

   keytool -importkeystore -srckeystore <PKCS-12-file-name>.p12 -srcstoretype pkcs12 -destkeystore <JKS-certificate-filename>.jks -deststoretype JKS
   

6. Provide the destination and source keystore passwords.

Attach the GitHub Java KeyStore certificate to your instance

Enable the JWT Bearer Grant token authentication by attaching the valid GitHub Java KeyStore (JKS) certificate to your ServiceNow instance.

Before you begin

Ensure the availability of a valid Java KeyStore certificate.

Role required: admin

Procedure

1. Navigate to All > System Definition > Certificates.

2. Select New.

3. On the form, fill in the fields.

   Field	Description
   Name	Name to uniquely identify the record. For example, My GitHub App Certificate.
   Notify on expiration	Option to specify the users to be notified when the certificate expires.
   Warn in days to expire	Number of days to send a notification before the certificate expires.
   Active	Option to enable the certificate.
   Type	Option to select the type of the certificate. Select Java Key Store.
   Expires in days	Number of days until the certificate expires.
   Key store password	Password associated with the certificate (hint: the destination KeyStore password previously created).
   Short description	Summary about the certificate.

4. Select the attachments icon (

1. Select Validate Stores/Certificates.

Create a JWT signing key for the GitHub JKS certificate

Create a JSON Web Token (JWT) signing key to assign to your GitHub Java KeyStore certificate.

Before you begin

Role required: admin, sn_devops.admin

Procedure

1. Navigate to All > System OAuth > JWT Keys.

2. Select New.

3. On the form, fill in the fields.

   Field	Description
   Name	Name to uniquely identify the JWT signing key. For example, My GitHub App JWT Key.
   Signing Keystore	Valid JKS certificate attached in the previous task. For example, My GitHub App Certificate.
   Key Id	Unique Id to identify which key is used when multiple keys are used to sign tokens.
   Signing Algorithm	Algorithm to sign with the JWT key (hint: RSA 256).
   Signing Key Password	Password associated with the signing key (hint: the source keystore password previously created).
   Active	Option to enable the key.

4. Select Submit.

Create a JWT provider for your GitHub signing key

Add a JSON Web Token (JWT) provider to your ServiceNow instance for GitHub.

Before you begin

Role required: admin, sn_devops.admin

Procedure

1. Navigate to All > System OAuth > JWT Providers.

2. Select New.

3. On the form, fill in the fields.

   Field	Description
   Name	Name to uniquely identify the JWT provider. For example, My GitHub App JWT Provider.
   Expiry Interval (sec)	Number in seconds to set the lifespan of JWT provider tokens (Hint: You can leave it as default).
   Signing Configuration	Valid JWT signing key previously created. For example, My GitHub App JWT Key.

4. Right-click the form header, and select Save.

5. Enter your GitHub App App ID (available in the About section of your GitHub App configuration in GitHub ) as the value of the iss claim, in the Standard Claims related list.

6. Leave aud and sub values blank (default).

Register GitHub as an OAuth Provider (JWT)

Use the information generated during GitHub App account configuration to register GitHub as an OAuth provider and allow the instance to request OAuth 2.0 tokens.

Before you begin

Role required: admin, sn_devops.admin

Procedure

1. Navigate to All > System OAuth > Application Registry.

2. Select New.

   The What kind of OAuth application? message is displayed.

3. Select Connect to a third party OAuth Provider.

4. On the form, fill in the fields.