OAuth 2.0 credentials for GitHub Apps - Authorization Code

  • Release version: Washingtondc
  • Updated August 1, 2024
  • 3 minutes to read

    • Perform the following steps to integrate your GitHub Apps using Authorization code.

    Before you begin

    Role required:
    • oauth_admin in DevOps Change Velocity.
    • Admin account in GitHub.
    Note:
    Only user-level repositories are supported. You must have access to all the GitHub repositories that you want to configure in DevOps Change Velocity using Authorization code.
    Note:
    For GitHub Enterprise Server (on-premises instance), OAuth is not supported if you are connecting using a MID server.

    Configure the GitHub App in your GitHub account (Authorization Code)

    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, deselect the Active field.
    6. Leave the remaining fields empty (default).
    7. In the Repository permissions section, configure these settings.
      Action Read-only
      Checks Read-only
      Contents Read-only
      Deployments Read and write
      Environments Read-only
      Metadata Read-only
      Pull requests Read-only
      Secrets Read-only
      Webhooks Read and write
      Note:
      Read and write permissions are required to configure webhooks from ServiceNow.
    8. Leave the remaining permissions as No access (default).
    9. Install the newly created GitHub App on the accounts of your choice.

    Add Client ID to DevOps property

    After configuring your GitHub App, you must ensure that the Client ID prefix (first 3 or more characters of the ID) is added to the DevOps property: Client ID specifier for GitHub App.

    Before you begin

    Role required: sn_devops.admin

    Procedure

    1. Navigate to Workspaces > DevOps Change Workspace > Administration > System configuration > Properties.
    2. Change the Application scope to DevOps Data Model.
    3. Search for the property: Client ID specifier for GitHub App [sn_devops.github_oauth_client_id_specifier].
    4. Enter the Client ID prefix (first 3 or more characters of the ID) of your GitHub App to the property.
    5. Select Save.

    Register GitHub as an OAuth Provider (Authorization Code)

    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. Click New.
      The system displays the message What kind of OAuth application?
    3. Select Connect to a third party OAuth Provider.
      The system displays an empty Application Registries form.
    4. Complete the form.
      Field Value required
      Name Enter any name to uniquely identify the record. For example, enter My GitHub App Provider.
      Client ID Enter the client ID of your GitHub App (hint: available in the About section of your GitHub App configuration in GitHub ).
      Client Secret Enter the client secret of your GitHub App (hint: available in the About section of your GitHub App configuration in GitHub ).
      OAuth API script Select OAuthDevOpsGitHubHandler.
      Default Grant type Select Authorization Code.
      Authorization URL

      Enter https://github.com/login/oauth/authorize.

      For an on-premises deployment, use the proper GitHub host URL.
      Token URL

      Enter https://github.com/login/oauth/access_token.

      For an on-premises deployment, use the proper GitHub host URL.
    5. Leave the rest of the form fields as default.
      Application Registry form
    6. Right-click the form header, and click Save.
      • The system validates the OAuth credentials and populates the Redirect URL (Hint: It should match the User authorization callback URL previously provided in your GitHub App configuration).
      • The system populates OAuth Entity Profile with Grant Type as Authorization Code. For example, OAuth Entity Profile is created with default Name, My GitHub App Provider default_profile

    Create a credential record for GitHub App provider (Authorization Code)

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

    Before you begin

    Role required: admin, credential_admin

    Procedure

    1. Navigate to All > Connections & Credentials > Credentials.
    2. Click New.
      The system displays the message What type of Credentials would you like to create?.
    3. Select OAuth 2.0 Credentials.
      The pop-up window displays an empty OAuth 2.0 Credentials form.
    4. Fill in these values.
      Field Value required
      Name Enter any name to uniquely identify the record. For example, enter My GitHub App Credential.
      Active Enable
      OAuth Entity Profile Select the default OAuth Entity profile you created previously.
      Applies to Select the MID Servers that can use this credential. For example, select All MID Servers.
      Note:
      You must connect to your GitHub tool instance using MID Server to use this credential.
      Order Select the order to apply this credential. For example, enter 100.
    5. Save the record.
    6. Click the Get OAuth Token related link to generate the OAuth token.