{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":32107,"path":"it-service-management/devops-change-velocity/dev-ops-github-apps-oath-jwt.md","title":"OAuth 2.0 credentials for GitHub Apps - JWT","bundle":null,"doc_type":null,"release":"australia","body":"\n# OAuth 2.0 credentials for GitHub Apps - JWT\n\nPerform the following steps to integrate your GitHub Apps using the JWT bearer token.\n\n**Before you begin**\n\nRole required:\n\n- oauth\\_admin in DevOps Change Velocity.\n- Admin account in GitHub.\n\n **Note:** The OAuth 2.0 JWT grant type is supported for GitHub & GitHub Enterprise with MID server.\n\n\n## Configure the GitHub App in your GitHub account \\(JWT\\)\n\nCreate a custom GitHub App from your GitHub account to enable OAuth 2.0 authentication with your ServiceNow instance.\n\n### Before you begin\n\nGitHub requirement: GitHub App configured to integrate with ServiceNow\n\nRole required: No instance role required\n\n### About this task\n\nComplete these steps from your GitHub account. See [Building GitHub Apps](https://developer.github.com/apps/building-github-apps/) on the GitHub Developer site for instructions on creating and configuring custom applications.\n\n### Procedure\n\n1. From your GitHub account, create your GitHub App by navigating to **Developer Settings** > **GitHub Apps**.\n\n2. In the **Homepage URL** field, enter `https://.service-now.com`.\n\n3. In the **User authorization callback URL** field, enter `https://.service-now.com/oauth_redirect.do`.\n\n4. In the **Identifying and authorizing users** section, deselect the **Expire user authorization tokens** field.\n\n5. In the **Webhook** section, select the **Active** field.\n\n6. In the **Webhook URL** field, enter `https://.service-now.com/api/sn_devops/v2/devops/tool/apps?toolId=`, where Tool Id is your GitHub tool id \\(sys\\_id\\) from DevOps Change Velocity.\n\n **Note:**\n\n 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:\n\n 1. Navigate to the connected tool's tool record page.\n 2. Select **Configure GitHub App**, then select **Auto configure with existing token**.\n\n \\[Omitted image \"github-jwt-config-01.png\"\\] Alt text: Auto configure with existing token.\n\n This configures the Webhook URL of the GitHub App automatically.\n\n You can get the Tool ID in one of the following ways:\n\n - While connecting with the tool in DevOps Change Velocity, the Tool Id is available in the page URL. For example, `https://.service-now.com/.../sn_devops_tool//...`.\n - You can copy the webhook URL from the GitHub tool record page in DevOps Change Velocity, from **Configure** > **Configure manually** > **Webhook URL**.\n7. Leave the remaining fields empty \\(default\\).\n\n8. In the **Repository permissions** section, configure the following settings.\n\n\n
\n\nAction\n\n\n\nRead-only\n\n
\n\nChecks\n\n\n\nRead-only\n\n
\n\nContents\n\n\n\nRead-only\n\n
\n\nDeployments\n\n\n\nRead and write\n\n
\n\nEnvironments\n\n\n\nRead-only\n\n
\n\nMetadata\n\n\n\nRead-only\n\n
\n\nPull requests\n\n\n\nRead-only\n\n
\n\nSecrets\n\n\n\nRead-only\n\n
\n\nWebhooks\n\n\n\nRead and write**Note:** Read and write permissions are required to configure webhooks from ServiceNow.\n\n
**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**.\n\n9. Leave the remaining permissions as `No access` \\(default\\).\n\n10. In the **Subscribe to events** section, select the **Deployment protection rule** option.\n\n11. Save the changes.\n\n12. After creating the GitHub App, generate a new private key and save it to your machine.\n\n13. Install the newly created GitHub App on the accounts of your choice.\n\n 1. From the GitHub Apps settings page, select your app.\n\n 2. In the left sidebar, select **Install App**.\n\n 3. Select **Install** next to the organization or personal account containing the correct repository.\n\n 4. Install the app on all repositories or select repositories.\n\n For more information, see [Installing GitHub Apps](https://docs.github.com/en/developers/apps/managing-github-apps/installing-github-apps).\n\n\n## Generate the Java KeyStore certificate for GitHub\n\nGenerate a Java KeyStore \\(JKS\\) certificate for the JWT authentication.\n\n### Before you begin\n\nRole required: admin\n\n### Procedure\n\n1. Create a CA signed certificate using the GitHub App private key:\n\n ```\n openssl req -new -x509 -key .pem -out .pem -days 1095\n ```\n\n2. Enter the required details.\n\n3. Create the PKCS 12 file using the GitHub App private key and CA signed certificate:\n\n ```\n openssl pkcs12 -export -in .pem -inkey .pem -certfile .pem -out .p12 \n ```\n\n4. Provide the export password.\n\n5. Create the JKS file:\n\n ```\n keytool -importkeystore -srckeystore .p12 -srcstoretype pkcs12 -destkeystore .jks -deststoretype JKS\n ```\n\n6. Provide the destination and source keystore passwords.\n\n\n## Attach the GitHub Java KeyStore certificate to your instance\n\nEnable the JWT Bearer Grant token authentication by attaching the valid GitHub Java KeyStore \\(JKS\\) certificate to your ServiceNow instance.\n\n### Before you begin\n\nEnsure the availability of a valid Java KeyStore certificate.\n\nRole required: admin\n\n### Procedure\n\n1. Navigate to **All** > **System Definition** > **Certificates**.\n\n2. Select **New**.\n\n3. On the form, fill in the fields.\n\n |Field|Description|\n |-----|-----------|\n |Name|Name to uniquely identify the record. For example, `My GitHub App Certificate`.|\n |Notify on expiration|Option to specify the users to be notified when the certificate expires.|\n |Warn in days to expire|Number of days to send a notification before the certificate expires.|\n |Active|Option to enable the certificate.|\n |Type|Option to select the type of the certificate. Select **Java Key Store**.|\n |Expires in days|Number of days until the certificate expires.|\n |Key store password|Password associated with the certificate \\(hint: the destination KeyStore password previously created\\).|\n |Short description|Summary about the certificate.|\n\n4. Select the attachments icon \\(\\[Omitted image \"dev-ops-attachments-icon.png\"\\] Alt text: Attachments icon\\) and attach a JKS certificate.\n\n5. Select **Validate Stores/Certificates**.\n\n\n## Create a JWT signing key for the GitHub JKS certificate\n\nCreate a JSON Web Token \\(JWT\\) signing key to assign to your GitHub Java KeyStore certificate.\n\n### Before you begin\n\nRole required: admin, sn\\_devops.admin\n\n### Procedure\n\n1. Navigate to **All** > **System OAuth** > **JWT Keys**.\n\n2. Select **New**.\n\n3. On the form, fill in the fields.\n\n |Field|Description|\n |-----|-----------|\n |Name|Name to uniquely identify the JWT signing key. For example, `My GitHub App JWT Key`.|\n |Signing Keystore|Valid JKS certificate attached in the previous task. For example, `My GitHub App Certificate`.|\n |Key Id|Unique Id to identify which key is used when multiple keys are used to sign tokens.|\n |Signing Algorithm|Algorithm to sign with the JWT key \\(hint: RSA 256\\).|\n |Signing Key Password|Password associated with the signing key \\(hint: the source keystore password previously created\\).|\n |Active|Option to enable the key.|\n\n4. Select **Submit**.\n\n\n## Create a JWT provider for your GitHub signing key\n\nAdd a JSON Web Token \\(JWT\\) provider to your ServiceNow instance for GitHub.\n\n### Before you begin\n\nRole required: admin, sn\\_devops.admin\n\n### Procedure\n\n1. Navigate to **All** > **System OAuth** > **JWT Providers**.\n\n2. Select **New**.\n\n3. On the form, fill in the fields.\n\n |Field|Description|\n |-----|-----------|\n |Name|Name to uniquely identify the JWT provider. For example, `My GitHub App JWT Provider`.|\n |Expiry Interval \\(sec\\)|Number in seconds to set the lifespan of JWT provider tokens \\(Hint: You can leave it as default\\).|\n |Signing Configuration|Valid JWT signing key previously created. For example, `My GitHub App JWT Key`.|\n\n4. Right-click the form header, and select **Save**.\n\n5. 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.\n\n6. Leave **aud** and **sub** values blank \\(default\\).\n\n\n## Register GitHub as an OAuth Provider \\(JWT\\)\n\nUse 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.\n\n### Before you begin\n\nRole required: admin, sn\\_devops.admin\n\n### Procedure\n\n1. Navigate to **All** > **System OAuth** > **Application Registry**.\n\n2. Select **New**.\n\n The **What kind of OAuth application?** message is displayed.\n\n3. Select **Connect to a third party OAuth Provider**.\n\n4. On the form, fill in the fields.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nName\n\n\n\nName to uniquely identify the record. For example, enter `My GitHub App Provider`.\n\n
\n\nClient ID\n\n\n\nClient ID of your GitHub App \\(hint: available in the **About** section of your GitHub App configuration in GitHub \\).\n\n
\n\nClient Secret\n\n\n\nClient secret of your GitHub App \\(hint: available in the **About** section of your GitHub App configuration in GitHub \\).\n\n
\n\nOAuth API script\n\n\n\nOption that enables you to reference an amended OAuthUtil script include. Select **OAuthDevOpsGitHubJWTHandler**.\n\n
\n\nDefault Grant type\n\n\n\nType of grant associated with application registry. Select **JWT Bearer**.\n\n
\n\nToken URL\n\n\n\nThe location of the token endpoint that the instance uses to retrieve and refresh tokens. For cloud version, enter: `https://api.github.com/app/installations//access_tokens`.\n\nFor enterprise version, enter: `https:///api/v3/app/installations//access_tokens`.\n\nFor the installation id, go to Install App section in your GitHub App configuration in GitHub and select the gear icon to configure your app. The installation id will be in the webpage URL. For example, https://github.com/settings/installations/<installation\\_id>.\n\n
5. Leave the rest of the form fields as default.\n\n \\[Omitted image \"github-oauth-jwt-app-registries.png\"\\] Alt text: Application Registry form\n\n6. Right-click the form header, and select **Save**.\n\n7. Open the default profile created in the **OAuth Entity Profiles** related list.\n\n8. Populate the **JWT Provider** field with the JWT provider previously created and save the form.\n\n9. Navigate to **Key Management > Module Access Policies > All**.\n\n10. Select the policy that has **com\\_snc\\_platform\\_security\\_oauth\\_glideencrypter** as the **Crypto module** field value and **Script Include: OAuthDevOpsGitHubJWTHandler** as the **Target script** field value.\n\n11. Ensure the **Result** field is set to **Track** and save the changes.\n\n \\[Omitted image \"github-oauth-provider.png\"\\] Alt text: Form that shows the result field is set to track.\n\n\n## Create a credential record for GitHub App provider \\(JWT\\)\n\nCreate a credential record to the GitHub App provider previously created to authorize actions.\n\n### Before you begin\n\nRole required: admin, sn\\_devops.admin\n\n### Procedure\n\n1. Navigate to **All** > **Connections & Credentials** > **Credentials**.\n\n2. Select **New**.\n\n The **What type of Credentials would you like to create?** message is displayed.\n\n3. Select **OAuth 2.0 Credentials**.\n\n4. On the form, fill in the fields.\n\n |Field|Value required|\n |-----|--------------|\n |Name|Name to uniquely identify the record. For example, enter `My GitHub App Credential`.|\n |Active|Option to enable the record.|\n |OAuth Entity Profile|Default OAuth Entity profile created in the Application Registry.|\n\n5. Save the record.\n\n6. Select the **Get OAuth Token** related link to generate the OAuth token.\n\n\n**Related topics** \n\n\n[GitHub Actions configurations]()\n\n[ServiceNow DevOps custom actions from GitHub marketplace]()\n\n[GitHub Deployment Gates for ServiceNow DevOps Change]()\n\n"}}