See https://docs.google.com/document/d/1hzho44sCs1Y-m4UTy2kDuZg_0jm8LNJXruJDusAQ4aI/edit

Chapter 3 - Authenticating with GitHub

S3.1 - Enabling authentication with GitHub

• AI: [Docs] refactor https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.2/html/authentication/assembly-auth-provider-github to a single procedure with 3 steps, and substeps. Rewrite the steps for consistency. Use the Azure procedure as a template.
• DONE AI: [SME]: Where goes the “dangerouslyAllowSignInWithoutUserInCatalog” option go? Se reply above
• AI [Docs] complete information with content from https://redhatquickcourses.github.io/devhub-admin/devhub-admin/1/chapter2/git-auth.html#_create_a_secret_to_store_github_app_credentials 

To authenticate users in GitHub or GitHub Enterprise, enable the GitHub authentication provider in RHDH.

Prerequisites

• You added a custom RHDH application configuration, and have sufficient permissions to modify it. See https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.2/html/administration_guide_for_red_hat_developer_hub/assembly-add-custom-app-file-openshift_admin-rhdh.
• A GitHub account, with sufficient permissions to administer your GitHub Organization, and create GitHub Apps.
• Your GitHub Organization has one ore more users, and optionally, one or more teams.

Procedure

1. To allow Developer Hub to authenticate with GitHub, complete the steps in[ Registering a GitHub App|https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app] on the GitHub website with the following values: 
2. Application name: rhdh-app-<RHDH_URL> (a unique name)
3. Homepage URL: https://<RHDH_URL>
4. Authorization callback URL: https://<RHDH_URL>/api/auth/github/handler/frame
5. Webhook URL: https://<RHDH_URL>
6. Webhook secret: <your_secret> (Provide a strong secret)
7. Under Permissions, expand Repository Permissions and ensure that you provide appropriate access (Read-Only, Read and Write etc) to the GitHub features you would like to integrate from RHDH. At a minimum, toggle the following permissions. Read-only permissions should be enough. Toggle Read and write permissions only if you are sure you will make changes via the GitHub API:
   Administration
   Commit statuses
   Contents
   Dependabot alerts
   Deployments
   Pull Requests
   Webhooks
   Toggle other permissions as per your needs.
8. Under Organization permissions, ensure that you toggle Read-only permissions for Members so that RHDH can import team and user information from GitHub.
9. Select Only on this account for the Where can this GitHub App be installed? Option.
10. Verify your form entries, and when you are satisfied click Create GitHub App.
    You will be shown your App ID and a client ID. Make note of these values for the next step.

1. Click Generate a new client secret. Copy the generated secret for the next steps.
2. Scroll down to the Private Keys section and click Generate a private key. The private key will be downloaded. Copy the generated private key certificate (it is in PEM format) to a safe location.
3. In the left sidebar menu of the generated app, select Install App, and then click Install.
4. Select All Repositories for Repository access and then click Install.

1. Add your GitHub credentials in your Developer Hub secrets.
2. Edit your Developer Hub secrets, such as secrets-rhdh.
3. Add the following key/value pairs:
4. AUTH_GITHUB_CLIENT_ID: Your GitHub client ID.
5. AUTH_GITHUB_CLIENT_SECRET: Your GitHub client secret.
6. AUTH_GITHUB_APP_ID: Your GitHub app ID.
7. AUTH_GITHUB_ORGANIZATION: Your GitHub organization.
8. AUTH_GITHUB_HOST_DOMAIN: https://github.com or your GitHub Enterprise URL.
9. AUTH_GITHUB_WEBHOOK_URL: https://<RHDH_URL>
10. AUTH_GITHUB_WEBHOOK_SECRET: The Webhook secret you created in the previous step.
11. AUTH_GITHUB_PRIVATE_KEY_FILE: Your private key certificate

1. Set up the GitHub authentication provider in your Developer Hub custom configuration.
   Edit your custom Developer Hub config map, such as app-config-rhdh.
   In the app-config-rhdh.yaml content, add the microsoft provider configuration under the root auth configuration, and enable the microsoft provider for sign-in:
   app-config-rhdh.yaml fragment
   auth:
     environment: production <1>
     providers:
       github: <2>
         production:
           clientId: ${AUTH_GITHUB_CLIENT_ID}
           clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
           enterpriseInstanceUrl: ${AUTH_GITHUB_HOST_DOMAIN} <3>
   integrations: <4>
     github:
       - host: github.com
         apps:
       - appId: ${AUTH_GITHUB_APP_ID}
         clientId: ${AUTH_GITHUB_CLIENT_ID}
         clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
         webhookUrl: ${AUTH_GITHUB_WEBHOOK_URL}
         webhookSecret: ${AUTH_GITHUB_WEBHOOK_SECRET}
         privateKey: |
           ${AUTH_GITHUB_PRIVATE_KEY_FILE}
   signInPage: github <5>
   dangerouslyAllowSignInWithoutUserInCatalog: true <6>
   <1> Marking the environment as production hides the Guest login in the RHDH home page
   <2> Add configuration for the GitHub auth provider
   <3> You might omit this line if not using GitHub Enterprise
   <4> Generic integration plugin for GitHub. This is used by various GitHub plugins to integrate with the GitHub API
   <5> To enable the GitHub provider as default sign-in provider.
   <6> To enable authentication without requiring to provision the user catalog.

Verification

• Go to the RHDH login page. Log in with the Guest user account is disabled. Log in with GitHub.

S3.2 - Provisioning users from GitHub

• AI: [Docs] content from https://redhatquickcourses.github.io/devhub-admin/devhub-admin/1/chapter2/git-auth.html#_configure_rhdh_to_import_users_and_groups_in_a_github_organization 

Prerequisites

• You enabled the GitHub authorization provider. See xref:{enabling-authentication-with-github}[Enabling authentication with GitHub].

Procedure

1. To enable GitHub Organization member discovery, add the following YAML configuration at the same indentation level as the app attribute, and below the signInPage attribute:

signInPage: github
catalog:

  providers:

    github: <1>

      providerId:

        organization: "${GITHUB_ORGANIZATION}"

        schedule:  <2>

          frequency:

            minutes: 30

          initialDelay:

            seconds: 15

          timeout:

            minutes: 15

    githubOrg:

      githubUrl: "${GITHUB_HOST_DOMAIN}"

      orgs: [ "${GITHUB_ORGANIZATION}" ]

      schedule: <2>

        frequency:

          minutes: 30

        initialDelay:

          seconds: 15

        timeout:

          minutes: 15

1. Click Save.

Verification

1. Check the console logs to verify the synchronization has been completed.
   .Successful synchronization example:
   [source,json]

   ---

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