第4章 Enabling user authentication 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 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 authenticating-with-rhdh-<GUID>.

      Homepage URL

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

      Authorization callback URL

      Enter your Developer Hub authentication backend URL: https://<my_developer_hub_domain>/api/auth/github/handler/frame.

      Webhook

      Clear "Active", as this is not needed for authentication and catalog providers.

      Organization permissions

      Enable Read-only access to Members.

      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 Install App tab, choose an account to install your GitHub App on.

   4. Save the following values for the next step:

      • Client ID
      • Client secret

2. To add your GitHub credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using their respective environment variable name.

   AUTHENTICATION_GITHUB_CLIENT_ID

   Enter the saved Client ID.

   AUTHENTICATION_GITHUB_CLIENT_SECRET

   Enter the saved Client Secret.

   AUTHENTICATION_GITHUB_HOST_DOMAIN

   Enter the GitHub host domain: github.com.

   AUTHENTICATION_GITHUB_ORGANIZATION

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

3. Enable the GitHub organization provisioning plugin (backstage-plugin-catalog-backend-module-github-org-dynamic). This plugin ingests GitHub users and groups to the Developer Hub software catalog.

   dynamic-plugins.yaml file fragment

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

4. To provision GitHub users and groups to the Developer Hub software catalog, add the catalog.providers.githubOrg section to your custom Developer Hub app-config.yaml configuration file:

   app-config.yaml fragment with mandatory catalog.providers.githubOrg fields

   catalog:
     providers:
       githubOrg:
         id: githuborg
         githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}"
         orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ]
         schedule:
           frequency:
             minutes: 30
           initialDelay:
             seconds: 15
           timeout:
             minutes: 15

   id

   Enter a stable identifier for this provider, such as githuborg. Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts.

   githubUrl

   Enter the configured secret variable name: ${AUTHENTICATION_GITHUB_HOST_DOMAIN}.

   orgs

   Enter the configured secret variable name: ${AUTHENTICATION_GITHUB_ORGANIZATION}.

   schedule.frequency

   Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.

   schedule.timeout

   Enter your schedule timeout, in the ISO duration or "human duration" format.

   schedule.initialDelay

   Enter your schedule initial delay, in the ISO duration or "human duration" format.

5. To set up the GitHub authentication provider, add the auth.providers.github section to the app-config.yaml file content:

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

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
   signInPage: github

   environment

   Enter production to disable the Guest login option in the Developer Hub login page.

   clientId

   Enter the configured secret variable name: ${AUTHENTICATION_GITHUB_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}.

   signInPage

   Enter github to enable the GitHub provider as your Developer Hub sign-in provider.

   Optional: Consider adding the following optional fields:

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

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
           callbackUrl: <your_intermediate_service_url/handler>
           sessionDuration: { hours: 24 }
           signIn:
             resolvers:
               - resolver: usernameMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: github

   callbackUrl

   Enter 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.

   sessionDuration

   Enter the user session lifespan, in ms library format (such as '24h', '2 days'), ISO duration, or "human duration".

   signIn

   resolvers

   After successful authentication, Developer Hub resolves the user signing in 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.

   警告

   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.

   警告

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

Verification

1. To verify user and group provisioning, check the console logs.

   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:githuborg: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:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"}

2. To verify GitHub authentication:

   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 a GitHub account.