diff --git a/assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc b/assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc new file mode 100644 index 0000000000..d0df03c037 --- /dev/null +++ b/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] + diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc index 415f8100fc..89daaa4906 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/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}. diff --git a/modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps-only.adoc b/modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps-only.adoc new file mode 100644 index 0000000000..27eea15598 --- /dev/null +++ b/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-____`. + +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 `____`. + +. 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)]. + diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-mandatory-steps-only.adoc new file mode 100644 index 0000000000..bc9572d6d5 --- /dev/null +++ b/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: +. 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)]. diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps-only.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps-only.adoc new file mode 100644 index 0000000000..54f7a249b8 --- /dev/null +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk-with-mandatory-steps-only.adoc @@ -0,0 +1,114 @@ +[id="enabling-user-authentication-with-rhbk-with-mandatory-steps-only"] += Enabling user authentication with {rhbk-brand-name} ({rhbk}) (with mandatory steps only) + +To authenticate users with {rhbk-brand-name} ({rhbk}), enable and configure the OpenID Connect (OIDC) authentication provider in {product} and provision the users and groups from {rhbk} 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 {rhsso} to create and manage a realm and a client. +Alternatively, your {rhbk} administrator can prepare in {rhbk} the required realm and client for you. + +.Procedure +. To allow {product-short} to authenticate with {rhbk}, complete the steps in {rhbk}: +.. link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[Create a realm]. +link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[Create a user for verification]. +.. link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-secure-the-first-application[Register {product-short} as a client in {rhbk}]. + +.. Use an existing realm, or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/getting_started_guide/getting-started-zip-#getting-started-zip-create-a-realm[create a realm], with a distinctive **Name** such as ____. +Save the value for the next step: +* **{rhbk} realm base URL**, such as: ____/realms/____. + +.. To register your {product-short} in {rhbk}, in the created realm, link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html-single/getting_started_guide/index#getting-started-zip-secure-the-first-application[secure the first application], with: +... **Client ID**: A distinctive client ID, such as __<{product-very-short}>__. +... **Valid redirect URIs**: Set to the OIDC handler URL: `https://____/api/auth/oidc/handler/frame`. +... Navigate to the **Credentials** tab and copy the **Client secret**. +... Save the values for the next step: +* **Client ID** +* **Client Secret** + +.. To prepare for the verification steps, in the same realm, get the credential information for an existing user or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html-single/getting_started_guide/index#getting-started-zip-create-a-user[create a user]. +Save the user credential information for the verification steps. + +. To add your {rhsso} 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. ++ +`KEYCLOAK_BASE_URL`:: +Enter the saved **{rhbk} realm base URL**. + +`KEYCLOAK_CLIENT_ID`:: +Enter the saved **Client ID**. + +`KEYCLOAK_CLIENT_SECRET`:: +Enter the saved **Client Secret**. + +`KEYCLOAK_LOGIN_REALM`:: +Enter the saved **{rhbk} login realm**. + +`KEYCLOAK_REALM`:: +Enter the saved **{rhbk} realm**. + +. Enable the Keycloak organization plugin (`backstage-plugin-catalog-backend-module-keycloak-dynamic`). +The plugin is named after {rhbk} upstream project. +This plugin ingests {rhbk} users and groups to the {product-short} software catalog. +With the default configuration, the plugin runs every hour and uses your `KEYCLOAK_`-prefixed variables. ++ +.`dynamic-plugins.yaml` file fragment +[source,yaml] +---- +plugins: + - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-keycloak-dynamic' + disabled: false +---- + +. To set up the {rhbk} 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 `{my-app-config-file}` content: ++ +.`{my-app-config-file}` fragment with mandatory fields to enable authentication with {rhbk} +[source,yaml] +---- +auth: + environment: production + providers: + oidc: + production: + metadataUrl: ${KEYCLOAK_BASE_URL} + clientId: ${KEYCLOAK_CLIENT_ID} + clientSecret: ${KEYCLOAK_CLIENT_SECRET} + prompt: auto +signInPage: oidc +---- + +`environment: production`:: +Mark the environment as `production` to hide the Guest login in the {product-short} home page. + +`metadataUrl`, `clientId`, `clientSecret`:: +To configure the OIDC provider with your secrets. + +`sigInPage: oidc`:: +To enable the OIDC provider as default sign-in provider. + +`prompt: auto`:: +To allow the identity provider to automatically determine whether to prompt for credentials or bypass the login redirect if an active {rhsso} session exists. ++ +[NOTE] +==== +If `prompt: auto` is not set, the identity provider defaults to `prompt: none`, which assumes that you are already logged in and rejects sign-in requests without an active session. +==== + +.Verification +. To verify user and group provisioning, check the console logs. ++ +.Successful synchronization example: +[source] +---- +2025-06-27T16:02:34.647Z catalog info Read 5 Keycloak users and 3 Keycloak groups in 0.4 seconds. Committing... class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01" + +2025-06-27T16:02:34.650Z catalog info Committed 5 Keycloak users and 3 Keycloak groups in 0.0 seconds. class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01" +---- + +. To verify {rhbk} user authentication: +.. Go to the {product-short} login page. +.. Your {product-short} sign-in page displays *Sign in using OIDC* and the Guest user sign-in is disabled. +.. Log in with OIDC by using the saved **Username** and **Password** values. + +.Additional resources +* link:{authentication-book-url}#enabling-user-authentication-with-rhbk[Enabling user authentication with {rhbk} (with optional steps)]. diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index a7cc277599..8c207bdaae 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -69,13 +69,13 @@ catalog: ---- `baseUrl`:: -Enter your {rhbk} server URL, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}]. +Enter your {rhbk} server URL, defined in the previous steps.]. `clientId`:: -Enter your {product-short} application client ID in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}]. +Enter your {product-short} application client ID in {rhbk}, defined in the previous steps. `clientSecret`:: -Enter your {product-short} application client secret in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}]. +Enter your {product-short} application client secret in {rhbk}, defined in the previous steps. `realm`:: Enter the realm name to provision users, such as `master`. diff --git a/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc b/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc index 49146153cf..f8f76a3576 100644 --- a/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc +++ b/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc @@ -8,3 +8,9 @@ include::artifacts/attributes.adoc[] {abstract} +// Authentication +include::assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc[leveloffset=+1] + +// Git provider +include::modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc[leveloffset=+1] +