Chapter 4. Authenticating with GitHub

Procedure

1. To allow Developer Hub to authenticate with GitHub, create a GitHub App. Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens.

   1. Register a GitHub App with the following configuration:

      • GitHub App name: Enter a unique name identifying your GitHub App, such as <Red Hat Developer Hub>-<GUID>.
      • Homepage URL: Your Developer Hub URL: https://<my_developer_hub_url>.
      • Authorization callback URL: Your Developer Hub authentication backend URL: https://<my_developer_hub_url>/api/auth/github/handler/frame.
      • Webhook URL: Your Developer Hub URL: https://<my_developer_hub_url>.
      • Webhook secret: Provide a strong secret.

      • Repository permissions:

        • Enable Read-only access to:

          • Administration
          • Commit statuses
          • Contents
          • Dependabot alerts
          • Deployments
          • Pull Requests

          • Webhooks

            Tip

            If you plan to make changes using the GitHub API, ensure that Read and write permissions are enabled instead of Read-only.

        • Toggle other permissions as per your needs.

      • Organization permissions:

        • Enable Read-only access to Members.
      • For Where can this GitHub App be installed?, select Only on this account.
   2. In the General Clients secrets section, click Generate a new client secret.
   3. In the General Private keys section, click Generate a private key.
   4. In the Install App tab, choose an account to install your GitHub App on.

   5. Save the following values for the next step:

      • App ID
      • Client ID
      • Client secret
      • Private key
      • Webhook secret

2. To add your GitHub credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets:

   AUTH_GITHUB_APP_ID

   Enter the saved App ID.

   AUTH_GITHUB_CLIENT_ID

   Enter the saved Client ID.

   GITHUB_ORGANIZATION

   Enter your GitHub organization name, such as `<your_github_organization_name>'.

   GITHUB_ORG_URL

   Enter $GITHUB_HOST_DOMAIN/$GITHUB_ORGANIZATION.

   GITHUB_CLIENT_SECRET

   Enter the saved Client Secret.

   GITHUB_PRIVATE_KEY_FILE

   Enter the saved Private key.

   GITHUB_WEBHOOK_URL

   Enter your Developer Hub URL: https://<my_developer_hub_url>.

   GITHUB_WEBHOOK_SECRET

   Enter the saved Webhook secret.

3. . To set up the GitHub authentication provider and enable integration with the GitHub API in your Developer Hub custom configuration, edit your custom Developer Hub config map such as my-rhdh-app-config, and add the following lines to the app-config.yaml file content:

   app-config.yaml file fragment with mandatory fields to enable authentication with GitHub

   auth:
     environment: production 

   1

   
     providers:
       github:
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID} 

   2

   
           clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
   integrations:
     github:
       - host: ${GITHUB_HOST_DOMAIN}
         apps:
           - appId: ${AUTH_GITHUB_APP_ID}
             clientId: ${AUTH_GITHUB_CLIENT_ID}
             clientSecret: ${GITHUB_CLIENT_SECRET}
             webhookUrl: ${GITHUB_WEBHOOK_URL}
             webhookSecret: ${GITHUB_WEBHOOK_SECRET}
             privateKey: |
               ${GITHUB_PRIVATE_KEY_FILE}
   signInPage: github 

   3

   1

   Mark the environment as production and disable the Guest login option in the Developer Hub login page.

   2

   Apply the GitHub credentials configured in your Developer Hub secrets.

   3

   To enable the GitHub provider as your Developer Hub sign-in provider.

   1. Optional: Consider adding the following optional fields:

      callbackUrl

      The callback URL that GitHub uses when initiating an OAuth flow, such as: <your_intermediate_service_url/handler>. Define it when Developer Hub is not the immediate receiver, such as in cases when you use one OAuth app for many Developer Hub instances.

      app-config.yaml file fragment with optional enterpriseInstanceUrl field

      auth:
        providers:
          github:
            production:
              callbackUrl: <your_intermediate_service_url/handler>

Verification

1. Go to the Developer Hub login page.
2. Your Developer Hub sign-in page displays Sign in using GitHub and the Guest user sign-in is disabled.
3. Log in with GitHub.

Verification

1. Check the console logs to verify that the synchronization is completed.

   Successful synchronization example:

   {"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:production:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"}
   {"class":"GithubMultiOrgEntityProvider","level":"info","message":"Read 7 GitHub users and 2 GitHub groups in 0.4 seconds. Committing...","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:production:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"}

2. Log in with a GitHub account.