Chapter 3. Authenticating with GitHub
Chapter 3. Authenticating with GitHub To authenticate users with GitHub or GitHub Enterprise: Enable the GitHub authentication provider in Developer Hub . Provision users from GitHub to the software catalog . 3.1. Enabling authentication with GitHub To authenticate users with GitHub, enable the GitHub authentication provider in Red Hat Developer Hub. Prerequisites You have added a custom Developer Hub application configuration , and have sufficient permissions to modify it. You have sufficient permissions in GitHub to create and manage a GitHub App . Procedure 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. 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 . In the General Clients secrets section, click Generate a new client secret . In the General Private keys section, click Generate a private key . In the Install App tab, choose an account to install your GitHub App on. Save the following values for the step: App ID Client ID Client secret Private key Webhook secret To add your GitHub credentials to your Developer Hub secrets, edit your Developer Hub secrets, such as secrets-rhdh , and add the following key/value pairs: 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 USDGITHUB_HOST_DOMAIN/USDGITHUB_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 . 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: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{AUTH_GITHUB_CLIENT_SECRET} integrations: github: - host: USD{GITHUB_HOST_DOMAIN} apps: - appId: USD{AUTH_GITHUB_APP_ID} clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{GITHUB_CLIENT_SECRET} webhookUrl: USD{GITHUB_WEBHOOK_URL} webhookSecret: USD{GITHUB_WEBHOOK_SECRET} privateKey: | USD{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: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{AUTH_GITHUB_CLIENT_SECRET} integrations: github: - host: USD{GITHUB_HOST_DOMAIN} apps: - appId: USD{AUTH_GITHUB_APP_ID} clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{GITHUB_CLIENT_SECRET} webhookUrl: USD{GITHUB_WEBHOOK_URL} webhookSecret: USD{GITHUB_WEBHOOK_SECRET} privateKey: | USD{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 step. app-config-rhdh.yaml fragment with optional enterpriseInstanceUrl field auth: providers: github: production: enterpriseInstanceUrl: USD{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: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{AUTH_GITHUB_CLIENT_SECRET} <your_other_authentication_providers_configuration> integrations: github: - host: USD{GITHUB_HOST_DOMAIN} apps: - appId: USD{AUTH_GITHUB_APP_ID} clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{GITHUB_CLIENT_SECRET} webhookUrl: USD{GITHUB_WEBHOOK_URL} webhookSecret: USD{GITHUB_WEBHOOK_SECRET} privateKey: | USD{GITHUB_PRIVATE_KEY_FILE} signInPage: <your_main_authentication_provider> Verification Go to the Developer Hub login page. Your Developer Hub sign-in page displays Sign in using GitHub and the Guest user sign-in is disabled. Log in with GitHub. 3.2. Provisioning users from GitHub to the software catalog To authenticate users, Red Hat Developer Hub requires their presence in the software catalog. Consider configuring Developer Hub to provision users from GitHub to the software catalog on schedule, rather than provisioning the users manually. Prerequisites You have enabled authentication with GitHub , including the following secrets: GITHUB_HOST_DOMAIN GITHUB_ORGANIZATION Procedure To enable GitHub member discovery, 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.yaml fragment with mandatory github fields dangerouslyAllowSignInWithoutUserInCatalog: false catalog: providers: github: providerId: organization: "USD{GITHUB_ORGANIZATION}" schedule: frequency: minutes: 30 initialDelay: seconds: 15 timeout: minutes: 15 githubOrg: githubUrl: "USD{GITHUB_HOST_DOMAIN}" orgs: [ "USD{GITHUB_ORGANIZATION}" ] schedule: frequency: minutes: 30 initialDelay: seconds: 15 timeout: minutes: 15 dangerouslyAllowSignInWithoutUserInCatalog: false Allow authentication only for users present in the Developer Hub software catalog. 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 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"} Log in with a GitHub account.
auth: environment: production providers: github: production: clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{AUTH_GITHUB_CLIENT_SECRET} integrations: github: - host: USD{GITHUB_HOST_DOMAIN} apps: - appId: USD{AUTH_GITHUB_APP_ID} clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{GITHUB_CLIENT_SECRET} webhookUrl: USD{GITHUB_WEBHOOK_URL} webhookSecret: USD{GITHUB_WEBHOOK_SECRET} privateKey: | USD{GITHUB_PRIVATE_KEY_FILE} signInPage: github auth: environment: production providers: github: production: clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{AUTH_GITHUB_CLIENT_SECRET} integrations: github: - host: USD{GITHUB_HOST_DOMAIN} apps: - appId: USD{AUTH_GITHUB_APP_ID} clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{GITHUB_CLIENT_SECRET} webhookUrl: USD{GITHUB_WEBHOOK_URL} webhookSecret: USD{GITHUB_WEBHOOK_SECRET} privateKey: | USD{GITHUB_PRIVATE_KEY_FILE} signInPage: github dangerouslyAllowSignInWithoutUserInCatalog: true auth: providers: github: production: callbackUrl: <your_intermediate_service_url/handler> auth: providers: github: production: enterpriseInstanceUrl: USD{GITHUB_HOST_DOMAIN} auth: environment: production providers: github: production: clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{AUTH_GITHUB_CLIENT_SECRET} <your_other_authentication_providers_configuration> integrations: github: - host: USD{GITHUB_HOST_DOMAIN} apps: - appId: USD{AUTH_GITHUB_APP_ID} clientId: USD{AUTH_GITHUB_CLIENT_ID} clientSecret: USD{GITHUB_CLIENT_SECRET} webhookUrl: USD{GITHUB_WEBHOOK_URL} webhookSecret: USD{GITHUB_WEBHOOK_SECRET} privateKey: | USD{GITHUB_PRIVATE_KEY_FILE} signInPage: <your_main_authentication_provider> dangerouslyAllowSignInWithoutUserInCatalog: false catalog: providers: github: providerId: organization: "USD{GITHUB_ORGANIZATION}" schedule: frequency: minutes: 30 initialDelay: seconds: 15 timeout: minutes: 15 githubOrg: githubUrl: "USD{GITHUB_HOST_DOMAIN}" orgs: [ "USD{GITHUB_ORGANIZATION}" ] schedule: frequency: minutes: 30 initialDelay: seconds: 15 timeout: minutes: 15 {"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"}