RHIDP-7975 Enabling authentication procedures with mandatory steps only

assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc

@@ -0,0 +1,18 @@
+[id='enabling-authentication-with-mandatory-steps-only']
+= Enabling authentication in {product} (with mandatory steps only)
+
+
+include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1]
+
+
+include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps-only.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps-only.adoc[leveloffset=+1]
+
+
+include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only.adoc[leveloffset=+1]
+

modules/authentication/con-understanding-authentication-and-user-provisioning.adoc

@@ -9,7 +9,7 @@ Catalog provider plugins handle this task asynchronously.
 These plugins query the Identity Provider (IdP) for relevant user and group information, and create or update corresponding entities in the {product-short} catalog.
 Scheduled provisioning ensures that the catalog accurately reflects the users and groups in your organization.
 
-When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:enabling-user-authentication-with-github[GitHub], or xref:enabling-user-authentication-with-microsoft-azure[{azure-brand-name}].
+When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as {rhbk-brand-name} ({rhbk}), GitHub, or {azure-brand-name}.
 This external IdP is responsible for authenticating the user.
 
 On successful authentication, the {product-short} authentication plugin, configured in your `{my-app-config-file}` file, processes the response from the IdP, resolves the identity in the {product-short} software catalog, and establishes a user session within {product-short}.

modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps-only.adoc

@@ -0,0 +1,117 @@
+[id="enabling-user-authentication-with-github-with-mandatory-steps-only"]
+= Enabling user authentication with GitHub (with mandatory steps only)
+
+To authenticate users with GitHub, configure the GitHub authentication provider in {product} and provision the users and groups from GitHub to the {product-short} software catalog.
+
+.Prerequisites
+* You link:{configuring-book-url}[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].
+Alternatively, you can ask your GitHub administrator to prepare the required 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 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 `authenticating-with-rhdh-__<GUID>__`.
+
+Homepage URL::
+Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
+
+Authorization callback URL::
+Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/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`.
+
+.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*.
+
+.. In the *Install App* tab, choose an account to install your GitHub App on.
+
+.. Save the following values for the next step:
+
+* **Client ID**
+* **Client secret**
+
+. To add your GitHub credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets].
+You can use these secrets in the {product-short} 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**.
+
+`GITHUB_URL`::
+Enter the GitHub host domain: `github.com`.
+
+`GITHUB_ORG`::
+Enter your GitHub organization name, such as `__<your_github_organization_name>__`.
+
+. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`).
+This plugin ingests GitHub users and groups to the {product-short} software catalog.
+With the default configuration, the plugin runs every hour and uses your `GITHUB_URL` and `GITHUB_ORG` variables.
++
+.`dynamic-plugins.yaml` file fragment
+[source,yaml]
+----
+plugins:
+  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
+    disabled: false
+----
+
+. To set up the GitHub authentication provider, add the `auth.providers.github` section to the `{my-app-config-file}` file content:
++
+.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub
+[source,yaml]
+----
+auth:
+  environment: production
+  providers:
+    github:
+      production:
+        clientId: ${GITHUB_CLIENT_ID}
+        clientSecret: ${GITHUB_CLIENT_SECRET}
+signInPage: github
+----
+
+`environment`::
+Enter `production` to disable the Guest login option in the {product-short} login page.
+
+`clientId`::
+Enter the configured secret variable name: `${GITHUB_CLIENT_ID}`.
+
+`clientSecret`::
+Enter the configured secret variable name: `${GITHUB_CLIENT_SECRET}`.
+
+`signInPage`::
+Enter `github` to enable the GitHub provider as your {product-short} sign-in provider.
+
+.Verification
+. To verify user and group provisioning, check the console logs.
++
+.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: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"}
+----
+
+. To verify GitHub authentication:
+.. 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 a GitHub account.
+
+.Additional resources
+* link:{integrating-with-github-book-url}[{integrating-with-github-book-title}].
+* link:{authentication-book-url}#enabling-user-authentication-with-github[Enabling user authentication with GitHub (with optional steps)].
+

modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only.adoc

@@ -0,0 +1,148 @@
+[id="enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only"]
+= Enabling user authentication with {azure-brand-name} (with mandatory steps only)
+
+To authenticate users with {azure-brand-name}, provision the users and groups from {azure-short} to the {product-short} software catalog and enable the {azure-short} authentication provider in {product-short}.
+
+.Prerequisites
+* You have the permission to register an application in {azure-short}.
+Alternatively, you can ask your {azure-short} administrator to prepare the required {azure-short} application.
+
+* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+
+* Your {product-short} backend can access the following hosts:
+
+`login.microsoftonline.com`::
+This is the {azure-brand-name} authorization server, which enables the authentication flow.
+
+`graph.microsoft.com`::
+For retrieving organization data, including user and group data, to be ingested into the {product-short} catalog.
+
+.Procedure
+:my-product-app-name-in-azure: <Authenticating with {product-short}>
+. To allow {product-short} to authenticate with {azure-short}, link:https://learn.microsoft.com/en-us/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=aspnetcore#register-an-app-by-using-the-azure-portal[Register an app by using the {azure-short} portal].
+
+.. Sign in to the link:https://entra.microsoft.com/[Microsoft Entra admin center].
+
+.. If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu.
+
+.. Browse to *Applications > App registrations*, and create a **New registration** with the configuration:
+
+Name::
+Enter a name to identify your application in {azure-short}, such as __{my-product-app-name-in-azure}__.
+
+Supported account types::
+Select *Accounts in this organizational directory only*.
+
+Redirect URI::
+
+Select a platform:::
+Select *Web*.
+
+URL:::
+Enter the backend authentication URI set in {product-short}: `pass:c,a,q[{my-product-url}/api/auth/microsoft/handler/frame]`
+
+.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > API permissions* page, *Add a Permission*, *Microsoft Graph*, select the following permissions:
+
+Application Permissions::
+`GroupMember.Read.All`:::
+`User.Read.All`:::
+Enter permissions that enable provisioning user and groups to the {product-short} software catalog.
++
+Optional: *Grant admin consent* for these permissions.
+Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access {product-short}.
+
+Delegated Permissions::
+`User.Read`:::
+`email`:::
+`offline_access`:::
+`openid`:::
+`profile`:::
+Enter permissions that enable authenticating users.
++
+Optional: Enter optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file.
+
+
+.. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > Certificates & secrets* page, in the *Client secrets* tab, create a *New client secret*.
+
+.. Save the following values for the next step:
+- **Directory (tenant) ID**
+- **Application (client) ID**
+- **Application (client) Secret ID**
+
+. To add your {azure-short} credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]:
+
+`MICROSOFT_TENANT_ID`::
+Enter your saved *Directory (tenant) ID*.
+
+`MICROSOFT_CLIENT_ID`::
+Enter your saved *Application (client) ID*.
+
+`MICROSOFT_CLIENT_SECRET`::
+Enter your saved *Application (client) secret*.
+
+. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`).
+This plugin ingests {azure-short} users and groups to the {product-short} software catalog.
+With the default configuration, the plugin runs every hour and uses your `MICROSOFT_TENANT_ID`, `MICROSOFT_CLIENT_ID`, and `MICROSOFT_CLIENT_SECRET` variables.
++
+.`dynamic-plugins.yaml` file fragment
+[source,yaml]
+----
+plugins:
+  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic'
+    disabled: false
+----
++
+include::{docdir}/artifacts/snip-technology-preview.adoc[]
+
+. To set up the {azure-short} authentication provider, add the `auth.providers.microsoft` section to your `{my-app-config-file}` file content:
++
+--
+.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with {azure-short}
+[source,yaml,subs="+quotes,+attributes"]
+----
+auth:
+  environment: production
+  providers:
+    microsoft:
+      production:
+        clientId: ${MICROSOFT_CLIENT_ID}
+        clientSecret: ${MICROSOFT_CLIENT_SECRET}
+        tenantId: ${MICROSOFT_TENANT_ID}
+signInPage: microsoft
+----
+
+`environment`::
+Enter `production` to disable the **Guest** login option in the {product-short} login page.
+
+`clientId`::
+Enter the configured secret variable name:  `${MICROSOFT_CLIENT_ID}`.
+
+`clientSecret`::
+Enter the configured secret variable name:
+`${MICROSOFT_CLIENT_SECRET}`.
+
+`tenantId`::
+Enter the configured secret variable name: `${MICROSOFT_TENANT_ID}`.
+
+`signInPage`::
+Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider.
+--
+
+.Verification
+. To verify user and group provisioning, check the console logs for `MicrosoftGraphOrgEntityProvider` events.
++
+.Successful synchronization example:
+[source]
+----
+2025-06-23T13:37:55.804Z catalog info Read 9 msgraph users and 3 msgraph groups in 1.5 seconds. Committing... class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"
+
+2025-06-23T13:37:55.811Z catalog info Committed 9 msgraph users and 3 msgraph groups in 0.0 seconds. class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"
+----
+
+. To verify {azure-short} user authentication:
+.. Go to the {product-short} login page.
+.. Your {product-short} sign-in page displays *Sign in using Microsoft* and the Guest user sign-in is disabled.
+.. Log in with an {azure-short} account.
+
+.Additional resources
+* link:{authentication-book-url}#enabling-user-authentication-with-microsoft-azure[Enabling user authentication with {azure-brand-name} (with optional steps)].