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 for records in your ServiceNow AI Platform.
• 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.

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.

Avant de commencer

Role required: No instance role required

Pourquoi et quand exécuter cette tâche

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

Procédure

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.

   Code scanning	Read-only
   Contents	Read-only
   Custom properties	Read-only
   Dependabot alerts	Read-only
   Metadata	Read-only

   Remarque :

   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.
9. Leave the remaining permissions as No access (default).
10. In the Subscribe to events section, select the Deployment protection rule option.
11. Right-click in the header to save the changes.
12. 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.
13. 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.
14. 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.

Avant de commencer

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

Role required: sn_vul.app_sec_manager

Procédure

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.

Avant de commencer

A valid Java KeyStore certificate.

Role required: sn_vul.app_sec_manager

Procédure

1. Navigate to All > System Definition > Certificates.
2. Select New.
3. On the form, fill in the fields.

   Tableau 1. X.509 Certificate form 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.

Avant de commencer

Roles required:

• admin
• sn_vul.app_sec_manager

Procédure

1. Navigate to All > System OAuth > JWT Keys.
2. Select New.
3. On the form, fill in the fields.

   Tableau 2. JWT Keys form 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.

Avant de commencer

Roles required:

• admin
• sn_vul.app_sec_manager

Procédure

1. Navigate to All > System OAuth > JWT Providers.
2. Select New.
3. On the form, fill in the fields.

   Tableau 3. JWT Provider form 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.

Avant de commencer

Roles required:

• admin
• sn_vul.app_sec_manager

Procédure

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.

   Tableau 4. Application Registry form fields

   Field	Description
   Name	Name to uniquely identify the record. For example, enter My GitHub App Provider for AVR.
   Client ID	Client ID of your GitHub App. The Client ID is from the GitHub application in your GitHub console that you created in the previous steps. This ID available in the About section of your GitHub App configuration in GitHub.
   Accessible	Leave this setting in its current value.
   Client Secret	Client Secret of your GitHub App. The Client secret is from the GitHub application in your GitHub console that you created in the previous steps. This ID available in the About section of your GitHub App configuration in GitHub.
   Active	Option to enable the key. Leave this selected.
   Authorization URL	This URL is generated automatically.
   Token URL	The location of the token endpoint that the instance uses to retrieve and refresh tokens. Enter the Token from the URL in your GitHub App. This is the token displayed in the URL after your app is installed in GitHub. From the Install App section in your GitHub App configuration in GitHub, select the gear. The token is displayed in the webpage URL. For Cloud: https://api.github.com/app/installations/49374672/access_tokens. Installation ID: 9374672. For on-premise: https://github-372.secops-eng.com/api/v3/app/installations/7/access_tokens/api/v3.
   OAuth API script	Option that enables you to reference an amended OAuthUtil script include. Select OAuthGitHubJWTHandler.
   Default Grant type	Type of grant associated with application registry. Select JWT Bearer.

5. Leave the rest of the form fields as default.
6. Right-click the form header, and select Save.
7. Scroll to the OAuth Entity Profiles related list, select it, and open the default profile that was created on the list.
8. Populate the JWT Provider field with the JWT provider previously created and save the form.
9. Return to the application registry file and save it.
10. Navigate to Key Management > Module Access Policies > All.
11. Select the policy so that com_snc_platform_security_oauth_glideencrypter 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.

    

12. 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.
13. 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.

Avant de commencer

Roles required:

• admin
• sn_vul.app_sec_manager

Procédure

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.

    Field	Description
    Name	Name for the record.
    Active	Activated.
    Credential	Select the Credential record you created in the preceding steps.
    Connection alias	Your record is displayed.
    URL builder	Deactivated.
    Connection URL	This is the base URL: https://api.github.com for Enterprise. The on-premise is your GitHub endpoint URL.
    Use MID Server (optional)	MID Server is required for on-premise. It is optional for Enterprise.
    Connection timeout	Enter a value.

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