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

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

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.
    Code scanning Read-only
    Contents Read-only
    Custom properties Read-only
    Dependabot alerts Read-only
    Metadata Read-only
    Secret scanning alerts Read-only
    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.
  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.

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.
    Table 1. X.509 Certificate form fields
    FieldDescription
    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.
    Table 2. JWT Keys form fields
    FieldDescription
    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.
    Table 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. E nter 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

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.
    Table 4. Application Registry form fields
    FieldDescription
    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.
    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 that has com_snc_platform_security_oauth_glideencrypter as the Crypto module field value and the Script Include: OAuthGitHubJWTHandler.

    Crypto module field with Script Include OAuthGitHubJWTHandler

    Type: Script and Result: Track

  12. 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.
    FieldDescription
    Name Unique name for the record.
    Applies to Select the OAuth 2.0 Credentials from the list.
    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.
  8. Select New.
  9. Select HTTP(s) Connection.
  10. Select New and fill in the fields.
    FieldDescription
    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.
  11. Select Submit.
    The Connections and Credential Aliases list is displayed.
  12. Open your record and on the Connections related list tab select New and fill in the fields on the HTTP Connection record.
    FieldDescription
    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.
  13. 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.