[release-1.3] RHIDP-3969 Authenticating with GitHub (#613)

Co-authored-by: Patrick Knight <[email protected]>
Co-authored-by: Heena Manwani <[email protected]>
Co-authored-by: Fabrice Flore-Thébault <[email protected]>

Author: 4 people

assemblies/assembly-auth-provider-github.adoc

@@ -0,0 +1,13 @@
+[id="assembly-auth-provider-github"]
+= Enabling the GitHub authentication provider
+
+To authenticate users with GitHub or GitHub Enterprise:
+
+. xref:enabling-authentication-with-github[Enable the GitHub authentication provider in {product-short}].
+. xref:provisioning-users-from-github-to-the-software-catalog[Provision users from GitHub to the software catalog].
+
+include::modules/authentication/proc-enabling-authentication-with-github.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc[leveloffset=+1]
+

assemblies/assembly-authenticating-with-github.adoc

@@ -56,7 +56,7 @@ include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]
 include::assembly-authenticating-with-rhsso.adoc[leveloffset=+1]
 
 
-include::assembly-auth-provider-github.adoc[leveloffset=+1]
+include::assembly-authenticating-with-github.adoc[leveloffset=+1]
 
 
 include::assembly-authenticating-with-microsoft-azure.adoc[leveloffset=+1]

assemblies/assembly-enabling-authentication.adoc

@@ -0,0 +1,148 @@
+[id="enabling-authentication-with-github"]
+= Enabling authentication with GitHub
+
+To authenticate users with GitHub, enable the GitHub authentication provider in {product}.
+
+.Prerequisites
+* You have link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html/administration_guide_for_red_hat_developer_hub/assembly-add-custom-app-file-openshift_admin-rhdh[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
+
+.Procedure
+. To allow {product-short} 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.
+
+.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration:
++
+* *GitHub App name*: Enter a unique name identifying your GitHub App, such as __<{product}>__-__<GUID>__.
+* *Homepage URL*: Your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
+* *Authorization callback URL*: Your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`.
+* *Webhook URL*: Your {product-short} URL: `pass:c,a,q[{my-product-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 next step:
+
+* **App ID**
+* **Client ID**
+* **Client secret**
+* **Private key**
+* **Webhook secret**
+
+. To add your GitHub credentials to your {product-short} secrets, edit your {product-short} 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**.
++
+Optional: enter additional secrets. The additional secrets are not required for authentication, but for further integration with GitHub, including:
++
+`GITHUB_HOST_DOMAIN`:: Enter your GitHub host domain: `pass:c[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_SECRET`:: Enter the saved *Webhook secret*.
+
+. To set up the GitHub authentication provider in your {product-short} custom configuration, edit your custom {product-short} 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
+[source,yaml]
+----
+auth:
+  environment: production
+  providers:
+    github:
+      production:
+        clientId: ${AUTH_GITHUB_CLIENT_ID}
+        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
+signInPage: github
+----
+
+`environment: production`::
+Mark the environment as `production` to hide the Guest login in the {product-short} home page.
+
+`clientId`, `clientSecret`::
+Use the {product-short} 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 {product-short} software catalog.
++
+WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} 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
+[source,yaml]
+----
+auth:
+  environment: production
+  providers:
+    github:
+      production:
+        clientId: ${AUTH_GITHUB_CLIENT_ID}
+        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
+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 {product-short} is not the immediate receiver, such as in cases when you use one OAuth app for many {product-short} instances.
++
+.`app-config-rhdh.yaml` fragment with optional `enterpriseInstanceUrl` field
+[source,yaml,subs="+quotes"]
+----
+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
+[source,yaml,subs="+quotes"]
+----
+auth:
+  providers:
+    github:
+      production:
+        enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN}
+----
+
+--
+
+.Verification
+. Go to the {product-short} login page.
+. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled.
+. Log in with GitHub.
+

modules/authentication/proc-enabling-authentication-with-github.adoc

@@ -0,0 +1,76 @@
+[id="provisioning-users-from-github-to-the-software-catalog"]
+= Provisioning users from GitHub to the software catalog
+
+To authenticate users, {product} requires their presence in the software catalog.
+Consider configuring {product-short} to provision users from GitHub to the software catalog on schedule, rather than provisioning the users manually.
+
+.Prerequisites
+* You have xref:enabling-authentication-with-github[enabled authentication with GitHub], including the following secrets:
+** `GITHUB_HOST_DOMAIN`
+** `GITHUB_ORGANIZATION`
+
+.Procedure
+
+* To enable GitHub member discovery, edit your custom {product-short} ConfigMap, such as `app-config-rhdh`, and add the following lines to the `app-config-rhdh.yaml` content:
++
+--
+[id=githubProviderId]
+.`app-config.yaml` fragment with mandatory `github` fields
+[source,yaml]
+----
+dangerouslyAllowSignInWithoutUserInCatalog: false
+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
+----
+
+`dangerouslyAllowSignInWithoutUserInCatalog: false`::
+Allow authentication only for users present in the {product-short} software catalog.
+
+`organization`, `githubUrl`, and `orgs`::
+Use the {product-short} 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:
+[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"}
+----
+
+. Log in with a GitHub account.
+