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

   Copy to Clipboard Toggle word wrap

   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>

      Copy to Clipboard Toggle word wrap

      enterpriseInstanceUrl

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

      app-config.yaml file fragment with optional enterpriseInstanceUrl field

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

      Copy to Clipboard Toggle word wrap

      signIn

      resolvers

      After successful authentication, the user signing in must be resolved to an existing user in the Developer Hub catalog. To best match users securely for your use case, consider configuring a specific resolver. Enter the resolver list to override the default resolver: usernameMatchingUserEntityName.

      The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.

      Warning

      In production mode, only configure one resolver to ensure users are securely matched.

      resolver

      Enter the sign-in resolver name. Available resolvers:

      • usernameMatchingUserEntityName
      • preferredUsernameMatchingUserEntityName
      • emailMatchingUserEntityProfileEmail

      dangerouslyAllowSignInWithoutUserInCatalog: true

      Configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

      Warning

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

      app-config.yaml file fragment with optional field to allow signing in users absent from the software catalog

      auth:
        environment: production
        providers:
          github:
            production:
              clientId: ${AUTH_GITHUB_CLIENT_ID}
              clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
              signIn:
                resolvers:
                  - resolver: usernameMatchingUserEntityName
                    dangerouslyAllowSignInWithoutUserInCatalog: true
      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

      Copy to Clipboard Toggle word wrap

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.

Procedure

1. Enable the backstage-plugin-catalog-backend-module-github-dynamic plugin.

   dynamic-plugins.yaml file fragment

   plugins:
     - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic'
       disabled: false

   Copy to Clipboard Toggle word wrap

2. To enable GitHub member discovery, edit app-config.yaml, your custom Developer Hub configuration file:

   app-config.yaml fragment with mandatory github fields

   catalog:
     providers:
       github:
         providerId:
           organization: "${GITHUB_ORGANIZATION}"
           schedule:
             frequency:
               minutes: 30
             initialDelay:
               seconds: 15
             timeout:
               minutes: 15
       githubOrg:
         githubUrl: "${GITHUB_HOST_DOMAIN}"
         orgs: [ "${GITHUB_ORGANIZATION}" ]
         schedule:
           frequency:
             minutes: 30
           initialDelay:
             seconds: 15
           timeout:
             minutes: 15

   Copy to Clipboard Toggle word wrap

   organization, githubUrl, and orgs

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

   schedule.frequency

   To specify custom schedule frequency. Supports cron, ISO duration, and "human duration" as used in code.

   schedule.timeout

   To specify custom timeout. Supports ISO duration and "human duration" as used in code.

   schedule.initialDelay

   To specify custom initial delay. Supports ISO duration and "human duration" as used in code.

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"}

   Copy to Clipboard Toggle word wrap

2. Log in with a GitHub account.