Creating OAuth 2.0 credentials for GitHub Apps - JWT for the GitHub Application Vulnerability Integration

Perform the following steps to integrate your GitHub Apps using the JWT bearer token for the GitHub Application Vulnerability Integration.

Roles required:

• sn_vul.app_sec_manager and admin (maint) for records in your ServiceNow AI Platform.
• Unless you're logged in as admin (maint), you must have the following KMF roles to access the Module Access Policy [sys_kmf_crypto_caller_policy] table and locate and configure policy records:
  • sn_kmf.admin
  • sn_kmf.cryptographic_manager
  • sn_kmf.cryptographic_auditor
• No instance role required for tasks in your GitHub account.
• For more information about the context of the steps for this setup, see OAuth 2.0 protocol.

Only GitHub Organization accounts are currently supported through the OAuth-based integration workflow. Enterprise accounts aren't supported.

Create and configure the GitHub app for the GitHub Application Vulnerability Integration

Create a custom GitHub App from your GitHub account to activate OAuth 2.0 authentication with your GitHub Application Vulnerability Integration in your instance.

Before you begin

Role required: No instance role required

About this task

Only GitHub Organization accounts are currently supported through the OAuth-based integration workflow. Enterprise accounts aren't supported.

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/.

7. Leave the remaining fields empty (default).

8. 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. Right-click in the header to save the changes.

4. 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.

5. After installation, select the settings (gear icon) for your App and write down or note the following information.

   These details are required when you create the application registry in your ServiceNow AI Platform instance.

   • App ID
   • Client ID
   • Client secret.
   • Note the token in the URL. This is the token ID you enter in the Token URL in your instance.
   • Scroll down the page and generate a new private key and save it to your machine.

Generate the JKS certificate for the GitHub Application Vulnerability Integration

Generate a JKS certificate for the JWT authentication for the GitHub Application Vulnerability Integration.

Before you begin

You need to note the password that you use to generate the .jks file (KeyStore password).

Role required: sn_vul.app_sec_manager

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 Key Store certificate to your instance for the GitHub Application Vulnerability Integration

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

Before you begin

A valid Java KeyStore certificate.

Role required: sn_vul.app_sec_manager

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 for AVR.
   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 and attach a JKS certificate.

5. Select Validate Stores/Certificates.

   A Valid key_store message is displayed for valid certificate files.

Create a JWT signing key for the GitHub JKS certificate for the GitHub Application Vulnerability Integration

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

Before you begin

Roles required:

• admin
• sn_vul.app_sec_manager

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 for AVR.
   Signing Keystore	Select the Valid JKS certificate you attached in the previous task.
   Key Id	Leave this field blank.
   Signing Algorithm	Leave this value as RSA 256.
   Signing Key Password	Password associated with the signing key. This is the password you used to generate the JKS file.
   Active	Option to enable the key.

4. Right-click anywhere in the gray header of the page and select Save.

Create a JWT provider for your GitHub signing key for the GitHub Application Vulnerability Integration

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

Before you begin

Roles required:

• admin
• sn_vul.app_sec_manager

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 for AVR.
   Expiry Interval (sec)	Number in seconds to set the lifespan of JWT provider tokens. You can leave this setting in its default.
   Signing Configuration	Select the JWT key you created in the previous steps.

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

5. Enter your GitHub App App ID for the value of the iss claim, in the Standard Claims related list.

   This is the App ID from the GitHub App in your GitHub console that you created in the previous steps.

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

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

Register GitHub as an OAuth Provider (JWT) for the GitHub Application Vulnerability Integration

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

Roles required:

• admin
• sn_vul.app_sec_manager
• Unless you're logged in as admin (maint), you must have the following KMF roles to access the Module Access Policy [sys_kmf_crypto_caller_policy] table and locate and configure policy records:
  • sn_kmf.admin
  • sn_kmf.cryptographic_manager
  • sn_kmf.cryptographic_auditor

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.

1. Leave the rest of the form fields as default.

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

3. Scroll to the OAuth Entity Profiles related list, select it, and open the default profile that was created on the list.

4. Populate the JWT Provider field with the JWT provider previously created and save the form.

5. Return to the application registry file and save it.

6. Navigate to Key Management > Module Access Policies > All.

   Note: You might not have access to records on the Module Access Policy table if you try to filter by parameters other than sys_id. You can use the 164580a20f70cb14a217070400d1b295 sys_id to help you search.

7. Select the com_snc_platform_security_oauth_glideencrypter policy so its name is displayed as the Crypto module field value, and OAuthGitHubJWTHandler is the Script Include in the Target script field.

   In the following image the com_snc_platform_security_oauth_glideencrypter is selected as the value for the Crypto module field. The Script table field displays the Script Include [sys_script_include] table, and the Target script field value is OAuthGitHubJWTHandler.

1. Select Update.

As shown in the preceding image, the value in the **Policy name** field changes and the **Script table** and **Target script** fields are no longer displayed.

1. Verify the Result field is set to Track and save your changes.

Create Credentials and Connections for the GitHub Application Vulnerability Integration

Create a credential record to the GitHub App provider previously created to authorize actions.

Before you begin

Roles required:

• admin
• sn_vul.app_sec_manager

Procedure

1. Navigate to Credentials and Connections > Credentials.

2. Select New.

3. Select OAuth 2.0 Credentials.

4. Select New and fill in the fields.

   Field	Description
   Name	Unique name for the record.
   Applies to	Select All MidServer or a specific MidServer.
   OAuth Entity Profile	Select the search icon and locate the entity profile you created in the preceding steps.
   Other fields	Leave these fields in their defaults.

5. Right-click anywhere in the header of the page and select Save.

   The Credentials list is displayed.

6. Open the record you just created and select the Get OAuth Token related link.

   A message is displayed that the OAuth token was imported successfully.

7. Navigate to Credentials and Connections > Connections & Credential Aliases.

8. Select New and fill in the fields.

   Field	Description
   Name	Name for the record.
   Application	Read-only.
   Parent Alias (optional)	Select the search icon and choose one from the list.
   Type	Connection and Credential.
   Connection type	HTTP.
   Support Multiple Active Connections (optional)	Deactivated.
   Default Retry Policy	Default HTTP Retry Policy
   Configuration Template	Leave empty.

9. Select Submit.

   The Connections and Credential Aliases list is displayed.

10. Open your record and on the Connections related list tab select New and fill in the fields on the HTTP Connection record.

1. Select Submit.

   The Connections and Credential Aliases list is displayed. You are now ready to complete the steps to Configure the GitHub Application Vulnerability Integration. In the Connection field, you enter the credentials that you created in the preceding steps.