Chapter 3. 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_HOST_DOMAIN

   Enter your GitHub host domain: https://github.com unless you are using GitHub Enterprise.

   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 ConfigMap such as app-config-rhdh, and add the following lines to the app-config-rhdh.yaml content:

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

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID}
           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

   environment: production

   Mark the environment as production to hide the Guest login in the Developer Hub home page.

   clientId, clientSecret, host, appId, webhookUrl, webhookSecret, privateKey

   Use the Developer Hub application information that you have created in GitHub and configured in OpenShift as secrets.

   sigInPage: github

   To enable the GitHub provider as default sign-in provider.

   Optional: Consider adding the following optional fields:

   dangerouslyAllowSignInWithoutUserInCatalog: true

   To enable authentication without requiring to provision users in the Developer Hub software catalog.

   Warning

   Use dangerouslyAllowSignInWithoutUserInCatalog to explore Developer Hub features, but do not use it in production.

   app-config-rhdh.yaml fragment with optional field to allow authenticating users absent from the software catalog

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID}
           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
   dangerouslyAllowSignInWithoutUserInCatalog: true

   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-rhdh.yaml fragment with optional enterpriseInstanceUrl field

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

   enterpriseInstanceUrl

   Your GitHub Enterprise URL. Requires you defined the GITHUB_HOST_DOMAIN secret in the previous step.

   app-config-rhdh.yaml fragment with optional enterpriseInstanceUrl field

   auth:
     providers:
       github:
         production:
           enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN}

   Tip

   To enable GitHub integration with a different authentication provider, complete the following configurations:

   • Add the GitHub provider to the existing auth section.
   • Keep the signInPage section from your authentication provider configuration.

   app-config-rhdh.yaml fragment with mandatory fields to enable GitHub integration and use a different authentication provider

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID}
           clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
       <your_other_authentication_providers_configuration>
   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: <your_main_authentication_provider>

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.