From c824980418ce336659b59282cf4558a993ef9f81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 8 Jul 2025 12:36:27 +0200 Subject: [PATCH 01/10] RHIDP-7975 Enabling authentication procedures with mandatory steps only Used variable names defined in the default config Added '_mod-docs-content-type' attribute definition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault Co-authored-by: Jessica He --- ...hentication-with-mandatory-steps-only.adoc | 20 +++++++ ...-authentication-and-user-provisioning.adoc | 6 +- ...bling-user-authentication-with-github.adoc | 51 ++++++++++------- ...r-authentication-with-microsoft-azure.adoc | 57 +++++++++++-------- ...nabling-user-authentication-with-rhbk.adoc | 40 ++++++------- .../master.adoc | 2 + 6 files changed, 111 insertions(+), 65 deletions(-) create mode 100644 assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc 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..52ec6afb50 --- /dev/null +++ b/assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +:only-default-steps: + +[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.adoc[leveloffset=+1] + + +include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1] + + +include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.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 b2f864608e..6ebd3351a2 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc @@ -29,10 +29,12 @@ To explore {product-short} features in a non-production environment, you can: * To use {product-short} without external IdP, enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all {product-short} features. -* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. This setting bypasses the check requiring a user to be in the catalog but still enforces authentication. +* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. +This setting bypasses the check requiring a user to be in the catalog but still enforces authentication. ==== [IMPORTANT] ==== -{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. As a result, deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion. +{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. +As a result, deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion. ==== diff --git a/modules/authentication/proc-enabling-user-authentication-with-github.adoc b/modules/authentication/proc-enabling-user-authentication-with-github.adoc index a86fca6716..2602012dfa 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-github.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-github.adoc @@ -6,9 +6,9 @@ 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 {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. -* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App]. +* You have enough 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 @@ -47,22 +47,23 @@ Select `Only on this account`. . To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#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`:: +`GITHUB_CLIENT_ID`:: Enter the saved **Client ID**. -`AUTHENTICATION_GITHUB_CLIENT_SECRET`:: +`GITHUB_CLIENT_SECRET`:: Enter the saved **Client Secret**. -`AUTHENTICATION_GITHUB_HOST_DOMAIN`:: +`GITHUB_URL`:: Enter the GitHub host domain: `github.com`. -`AUTHENTICATION_GITHUB_ORGANIZATION`:: +`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. + -.`dynamic-plugins.yaml` file fragment +`dynamic-plugins.yaml` file fragment: ++ [source,yaml] ---- plugins: @@ -81,8 +82,8 @@ catalog: providers: githubOrg: id: githuborg - githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}" - orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ] + githubUrl: "${GITHUB_URL}" + orgs: [ "${GITHUB_ORG}" ] schedule: frequency: minutes: 30 @@ -97,10 +98,10 @@ Enter a stable identifier for this provider, such as `githuborg`. Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts. `githubUrl`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_HOST_DOMAIN}`. +Enter the configured secret variable name: `$\{GITHUB_URL}`. `orgs`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_ORGANIZATION}`. +Enter the configured secret variable name: `$\{GITHUB_ORG}`. `schedule.frequency`:: Enter your schedule frequency, in the cron, ISO duration, or "human duration" format. @@ -123,8 +124,8 @@ auth: providers: github: production: - clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID} - clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET} + clientId: ${GITHUB_CLIENT_ID} + clientSecret: ${GITHUB_CLIENT_SECRET} signInPage: github ---- @@ -132,14 +133,15 @@ signInPage: github Enter `production` to disable the Guest login option in the {product-short} login page. `clientId`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_ID}`. +Enter the configured secret variable name: `$\{GITHUB_CLIENT_ID}`. `clientSecret`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_SECRET}`. +Enter the configured secret variable name: `$\{GITHUB_CLIENT_SECRET}`. `signInPage`:: Enter `github` to enable the GitHub provider as your {product-short} sign-in provider. +ifndef::only-default-steps[] Optional: Consider adding the following optional fields: .`{my-app-config-file}` file fragment including optional fields to enable authentication with GitHub @@ -150,8 +152,8 @@ auth: providers: github: production: - clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID} - clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET} + clientId: ${GITHUB_CLIENT_ID} + clientSecret: ${GITHUB_CLIENT_SECRET} callbackUrl: ____ sessionDuration: { hours: 24 } signIn: @@ -178,7 +180,10 @@ Enter the resolver list to override the default resolver: `usernameMatchingUserE + The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. + -WARNING: In production mode, only configure one resolver to ensure users are securely matched. +[WARNING] +==== +In production mode, only configure one resolver to ensure users are securely matched. +==== `resolver`:::: Enter the sign-in resolver name. @@ -191,13 +196,18 @@ Available resolvers: `dangerouslyAllowSignInWithoutUserInCatalog: true`:::: Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. + -WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. +[WARNING] +==== +Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. +==== +endif::[] -- .Verification . To verify user and group provisioning, check the console logs. + -.Successful synchronization example: +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"} @@ -210,6 +220,5 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh .. Log in with a GitHub account. .Additional resources - * {integrating-with-github-book-link}[{integrating-with-github-book-title}] diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 3332ae82fe..24f817ff01 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -9,7 +9,7 @@ To authenticate users with {azure-brand-name}, configure the {azure-short} authe * 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 {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to modify it. * Your {product-short} backend can access the following hosts: @@ -82,10 +82,10 @@ Enter your saved *Application (client) ID*. `AUTHENTICATION_AZURE_CLIENT_SECRET`:: Enter your saved *Application (client) secret*. -. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`). +. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`) in your `dynamic-plugins.yaml` +file. This plugin ingests {azure-short} users and groups to the {product-short} software catalog. + -.`dynamic-plugins.yaml` file fragment [source,yaml] ---- plugins: @@ -124,13 +124,13 @@ Enter `\https://graph.microsoft.com/v1.0` to define the MSGraph API endpoint the You might change this parameter to use a different version, such as the link:https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-beta#call-the-beta-endpoint[beta endpoint]. `tenandId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_TENANT_ID}`. `clientId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_CLIENT_ID}`. `clientSecret`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_SECRET}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_CLIENT_SECRET}`. `schedule`:: @@ -145,12 +145,12 @@ In a large organization, user provisioning might take a long time, therefore avo `initialDelay`::: Enter the schedule initial delay in the ISO duration or human duration format. +ifndef::only-default-steps[] Optional: Consider adding the following optional `microsoftGraphOrg.providerId` fields: [id=authority] `authority`:: -Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL], -when different from the default: `\https://login.microsoftonline.com`. +Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL], when different from the default: `\https://login.microsoftonline.com`. + .`{my-app-config-file}` fragment with optional `queryMode` field [source,yaml] @@ -164,7 +164,7 @@ catalog: [id=queryMode] `queryMode: basic | advanced`:: -Enter `advanced` when the default `basic` query mode is not sufficient for your queries to the Microsoft Graph API. +Enter `advanced` when the default `basic` query mode is insufficient for your queries to the Microsoft Graph API. See link:https://learn.microsoft.com/en-us/graph/aad-advanced-queries[{azure-brand-name} advanced queries]. + .`{my-app-config-file}` fragment with optional `queryMode` field @@ -184,7 +184,8 @@ Only one relationship can be expanded in a single request. See https://learn.microsoft.com/en-us/graph/query-parameters#expand-parameter[Microsoft Graph query expand parameter]. This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] or xref:userFilter[`user.filter`]. + -.`{my-app-config-file}` fragment with optional `user.expand` field +`{my-app-config-file}` fragment with optional `user.expand` field: ++ [source,yaml] ---- catalog: @@ -201,7 +202,8 @@ To filter users. See link:https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties[Microsoft Graph API] and link:https://learn.microsoft.com/en-us/graph/query-parameters#filter-parameter[Microsoft Graph API query filter parameters syntax]. This parameter and xref:userGroupMemberFilter[`userGroupMember.filter`] are mutually exclusive, only one can be specified. + -.`{my-app-config-file}` fragment with optional `user.filter` field +`{my-app-config-file}` fragment with optional `user.filter` field: ++ [source,yaml] ---- catalog: @@ -217,7 +219,8 @@ catalog: {product-short} loads photos by default. Enter `false` to avoid loading user photos. + -.`{my-app-config-file}` fragment with optional `user.loadPhotos` field +`{my-app-config-file}` fragment with optional `user.loadPhotos` field: ++ [source,yaml] ---- catalog: @@ -232,7 +235,8 @@ catalog: `user.select`:: Enter the link:https://learn.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource type] list to retrieve. + -.`{my-app-config-file}` fragment with optional `user.select` field +`{my-app-config-file}` fragment with optional `user.select` field: ++ [source,yaml] ---- catalog: @@ -249,7 +253,8 @@ To use group membership to get users. To filter groups and fetch their members. This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. + -.`{my-app-config-file}` fragment with optional `userGroupMember.filter` field +`{my-app-config-file}` fragment with optional `userGroupMember.filter` field: ++ [source,yaml] ---- catalog: @@ -266,7 +271,8 @@ To use group membership to get users. To search for groups and fetch their members. This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. + -.`{my-app-config-file}` fragment with optional `userGroupMember.search` field +`{my-app-config-file}` fragment with optional `userGroupMember.search` field: ++ [source,yaml] ---- catalog: @@ -284,7 +290,8 @@ Only one relationship can be expanded in a single request. See link:https://learn.microsoft.com/en-us/graph/query-parameters#expand-parameter[Customize Microsoft Graph responses with query parameters]. This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] instead of xref:userFilter[`user.filter`]. + -.`{my-app-config-file}` fragment with optional `group.expand` field +`{my-app-config-file}` fragment with optional `group.expand` field: ++ [source,yaml] ---- catalog: @@ -300,7 +307,8 @@ catalog: To filter groups. See link:https://learn.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0#properties[Microsoft Graph API query group syntax]. + -.`{my-app-config-file}` fragment with optional `group.filter` field +`{my-app-config-file}` fragment with optional `group.filter` field: ++ [source,yaml] ---- catalog: @@ -316,7 +324,8 @@ catalog: To search for groups. See link:https://learn.microsoft.com/en-us/graph/search-query-parameter[Microsoft Graph API query search parameter]. + -.`{my-app-config-file}` fragment with optional `group.search` field +`{my-app-config-file}` fragment with optional `group.search` field: ++ [source,yaml] ---- catalog: @@ -342,6 +351,7 @@ catalog: select: ['id', 'displayName', 'description'] ---- -- +endif::[] . To set up the {azure-short} authentication provider, add the `auth.providers.microsoft` section to your `{my-app-config-file}` file content: + @@ -364,14 +374,14 @@ signInPage: microsoft Enter `production` to disable the **Guest** login option in the {product-short} login page. `clientId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_CLIENT_ID}`. `clientSecret`:: Enter the configured secret variable name: -`${AUTHENTICATION_AZURE_CLIENT_SECRET}`. +`$\{AUTHENTICATION_AZURE_CLIENT_SECRET}`. `tenantId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_TENANT_ID}`. `signInPage`:: Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider. @@ -399,9 +409,10 @@ auth: `additionalScopes`:: Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. -The default and mandatory value lists: `'openid', 'offline_access', 'profile', 'email', 'User.Read'`. +The default and mandatory value lists: `openid`, `offline_access`, `profile`, `email`, and `User.Read`. ++ +`{my-app-config-file}` file fragment with optional `additionalScopes` field: + -.`{my-app-config-file}` file fragment with optional `additionalScopes` field [source,yaml,subs="+quotes,+attributes"] ---- auth: diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index 2259e4870e..913aac9574 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -29,13 +29,13 @@ Save the value for the next step: . To add your {rhsso} credentials to {product-short}, add the following key/value pairs to {configuring-dynamic-plugins-book-link}#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_OIDC_CLIENT_ID`:: +`KEYCLOAK_CLIENT_ID`:: Enter the saved **Client ID**. -`AUTHENTICATION_OIDC_CLIENT_SECRET`:: +`KEYCLOAK_CLIENT_SECRET`:: Enter the saved **Client Secret**. -`AUTHENTICATION_OIDC_METADATA_URL`:: +`KEYCLOAK_BASE_URL`:: Enter the saved **{rhbk} realm base URL**. . Enable the Keycloak organization plugin (`backstage-plugin-catalog-backend-module-keycloak-dynamic`). @@ -62,21 +62,21 @@ catalog: providers: keycloakOrg: default: - baseUrl: ${AUTHENTICATION_OIDC_METADATA_URL} - clientId: ${AUTHENTICATION_OIDC_CLIENT_ID} - clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET} + baseUrl: ${KEYCLOAK_BASE_URL} + clientId: ${KEYCLOAK_CLIENT_ID} + clientSecret: ${KEYCLOAK_CLIENT_SECRET} realm: master loginRealm: master ---- `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`. @@ -84,6 +84,7 @@ Enter the realm name to provision users, such as `master`. `loginRealm`:: Enter the realm name to authenticate users, such as `master`. +ifndef::only-default-steps[] .. Optional: Consider adding optional fields: `userQuerySize`:: @@ -158,6 +159,7 @@ catalog: schedule: initialDelay: { seconds: 15} ---- +endif::[] . 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: @@ -171,9 +173,9 @@ auth: providers: oidc: production: - metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL} - clientId: ${AUTHENTICATION_OIDC_CLIENT_ID} - clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET} + metadataUrl: ${KEYCLOAK_BASE_URL} + clientId: ${KEYCLOAK_CLIENT_ID} + clientSecret: ${KEYCLOAK_CLIENT_SECRET} prompt: auto signInPage: oidc ---- @@ -207,7 +209,7 @@ auth: providers: oidc: production: - callbackUrl: ${AUTHENTICATION_OIDC_CALLBACK_URL} + callbackUrl: ${KEYCLOAK_CALLBACK_URL} ---- `tokenEndpointAuthMethod`:: @@ -220,7 +222,7 @@ auth: providers: oidc: production: - tokenEndpointAuthMethod: ${AUTHENTICATION_OIDC_TOKEN_ENDPOINT_METHOD} + tokenEndpointAuthMethod: ${KEYCLOAK_TOKEN_ENDPOINT_METHOD} ---- `tokenSignedResponseAlg`:: @@ -233,7 +235,7 @@ auth: providers: oidc: production: - tokenSignedResponseAlg: ${AUTHENTICATION_OIDC_SIGNED_RESPONSE_ALG} + tokenSignedResponseAlg: ${KEYCLOAK_SIGNED_RESPONSE_ALG} ---- `additionalScopes`:: @@ -246,7 +248,7 @@ auth: providers: oidc: production: - additionalScopes: ${AUTHENTICATION_OIDC_SCOPE} + additionalScopes: ${KEYCLOAK_SCOPE} ---- `signIn`:: @@ -303,9 +305,9 @@ auth: providers: oidc: production: - metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL} - clientId: ${AUTHENTICATION_OIDC_CLIENT_ID} - clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET} + metadataUrl: ${KEYCLOAK_BASE_URL} + clientId: ${KEYCLOAK_CLIENT_ID} + clientSecret: ${KEYCLOAK_CLIENT_SECRET} signIn: resolvers: - resolver: oidcSubClaimMatchingKeycloakUserID diff --git a/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc b/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc index c0c66a8943..134b25612f 100644 --- a/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc +++ b/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc @@ -3,8 +3,10 @@ include::artifacts/attributes.adoc[] :subtitle: Prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production. :abstract: Prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production. :context: setting-up-and-configuring-your-first-rhdh-instance +:only-default-steps: [id="{context}"] = {title} {abstract} +include::assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc[leveloffset=+1] From 3239f3ad85be32e0c1c64c241bea079c2e8aea96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 22 Sep 2025 17:24:50 +0200 Subject: [PATCH 02/10] Work on consistency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- ...proc-enabling-user-authentication-with-github.adoc | 11 ++--------- ...ling-user-authentication-with-microsoft-azure.adoc | 10 ++++------ .../proc-enabling-user-authentication-with-rhbk.adoc | 11 ++++------- 3 files changed, 10 insertions(+), 22 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-github.adoc b/modules/authentication/proc-enabling-user-authentication-with-github.adoc index 0e13a751a5..3bbd1d91fe 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-github.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-github.adoc @@ -73,9 +73,7 @@ plugins: . To provision GitHub users and groups to the {product-short} software catalog, add the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: + --- [id=githubProviderId] -.`{my-app-config-file}` fragment with mandatory `catalog.providers.githubOrg` fields [source,yaml] ---- catalog: @@ -111,12 +109,9 @@ Enter your schedule timeout, in the ISO duration or "human duration" format. `schedule.initialDelay`:: Enter your schedule initial delay, in the ISO duration or "human duration" format. --- . To set up the GitHub authentication provider, add the `auth.providers.github` section to your `{my-app-config-file}` file: + --- -.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub [source,yaml] ---- auth: @@ -142,11 +137,10 @@ Enter the configured secret variable name: `$\{GITHUB_CLIENT_SECRET}`. Enter `github` to enable the GitHub provider as your {product-short} sign-in provider. + Optional: Consider adding optional fields. -ifeval::[{optional-steps} == 'disable'] +ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] -ifeval::[{optional-steps} == 'enable'] -+ +ifeval::["{optional-steps}" == "enable"] [source,yaml,subs="+quotes"] ---- auth: @@ -203,7 +197,6 @@ Configure the sign-in resolver to bypass the user provisioning requirement in th Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. ==== endif::[] --- .Verification . To verify user and group provisioning, check the console logs. diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index c50f33e604..4eb4d8f3c6 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -98,7 +98,6 @@ include::{docdir}/artifacts/snip-technology-preview.adoc[] . To provision {azure-short} users and groups to the {product-short} software catalog, add the `catalog.providers.microsoftGraphOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: + [id=microsoftGraphOrgProviderId] -.`{my-app-config-file}` fragment with mandatory `microsoftGraphOrg` fields [source,yaml] ---- catalog: @@ -145,10 +144,10 @@ In a large organization, user provisioning might take a long time, therefore avo Enter the schedule initial delay in the ISO duration or human duration format. + Optional: Consider adding optional fields. -ifeval::[{optional-steps} == 'disable'] +ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] -ifeval::[{optional-steps} == 'enable'] +ifeval::["{optional-steps}" == "enable"] [id=authority] `authority`:: Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL], when different from the default: `\https://login.microsoftonline.com`. @@ -384,11 +383,10 @@ Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_TENANT_ID}`. Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider. + Optional: Consider adding optional fields. -ifeval::[{optional-steps} == 'disable'] +ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] -ifeval::[{optional-steps} == 'enable'] - +ifeval::["{optional-steps}" == "enable"] `domainHint`:: Optional for single-tenant applications. You can reduce login friction for users with accounts in multiple tenants by automatically filtering out accounts from other tenants. diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index 5844042d61..77d7f7518e 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -83,10 +83,10 @@ Enter the realm name to provision users, such as `master`. Enter the realm name to authenticate users, such as `master`. + Optional: Consider adding optional fields. -ifeval::[{optional-steps} == 'disable'] +ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] -ifeval::[{optional-steps} == 'enable'] +ifeval::["{optional-steps}" == "enable"] `userQuerySize`:: Enter the user count to query simultaneously. Default value: `100`. @@ -162,10 +162,7 @@ catalog: endif::[] . 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: - -.. Add mandatory fields: + -.`{my-app-config-file}` fragment with mandatory fields to enable authentication with {rhbk} [source,yaml] ---- auth: @@ -198,10 +195,10 @@ If `prompt: auto` is not set, the identity provider defaults to `prompt: none`, ==== + Optional: Consider adding optional fields. -ifeval::[{optional-steps} == 'disable'] +ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] -ifeval::[{optional-steps} == 'enable'] +ifeval::["{optional-steps}" == "enable"] `callbackUrl`:: {rhbk} callback URL. + From d799c827fb0a0fd2898a29e411dfda5b888313f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 23 Sep 2025 14:51:50 +0200 Subject: [PATCH 03/10] Fixed more vale alerts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- .../config/vocabularies/RHDH/accept.txt | 5 +++ .vale.ini | 1 + ...-authentication-and-user-provisioning.adoc | 8 ++-- ...est-user-on-a-helm-based-installation.adoc | 5 +-- ...ser-on-an-operator-based-installation.adoc | 5 +-- ...ers-from-rhbk-to-the-software-catalog.adoc | 15 ++++---- ...bling-user-authentication-with-github.adoc | 6 +-- ...r-authentication-with-microsoft-azure.adoc | 38 ++++--------------- ...nabling-user-authentication-with-rhbk.adoc | 36 ++++++------------ 9 files changed, 44 insertions(+), 75 deletions(-) diff --git a/.vale-styles/config/vocabularies/RHDH/accept.txt b/.vale-styles/config/vocabularies/RHDH/accept.txt index 907ac9240c..b6c171fff1 100644 --- a/.vale-styles/config/vocabularies/RHDH/accept.txt +++ b/.vale-styles/config/vocabularies/RHDH/accept.txt @@ -1 +1,6 @@ +cron +Entra +IdP +Operator +MSGraph scaffolder diff --git a/.vale.ini b/.vale.ini index 3993bb9a9a..424c5c03e7 100644 --- a/.vale.ini +++ b/.vale.ini @@ -23,3 +23,4 @@ BasedOnStyles = RedHat,DeveloperHub,AsciiDocDITA AsciiDocDITA.AttributeReference = NO AsciiDocDITA.ShortDescription = NO AsciiDocDITA.CrossReference = NO +AsciiDocDITA.ConditionalCode = NO diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc index 6ebd3351a2..4111666703 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc @@ -2,7 +2,7 @@ = Understanding authentication and user provisioning -This module provides an overview of how authentication and user provisioning function within {product}. +This is an overview of how authentication and user provisioning function within {product}. Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step. Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data. @@ -21,7 +21,7 @@ Configuring authentication and user provisioning is critical for several reasons * It secures your {product-short} instance by ensuring only authenticated users can gain access. * It enables authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP. * Provisioning user and group data to the catalog is necessary for various catalog features that rely on understanding entity ownership and relationships between users, groups, and software components. -Without this provisioning step, features like displaying who owns a component in the catalog may not function correctly. +Without this provisioning step, features such as displaying who owns a catalog entity might not function correctly. [TIP] ==== @@ -36,5 +36,7 @@ This setting bypasses the check requiring a user to be in the catalog but still [IMPORTANT] ==== {product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. -As a result, deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion. +As a result, +deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, +since {product-short} will create those entities again during the next import. ==== diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc index c4240c0d80..c23a6d09ba 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc @@ -6,13 +6,12 @@ On a Helm-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features. .Prerequisites -* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. * You {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[use the {product} Helm chart to run {product-short}]. .Procedure -* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[configure your {product} Helm Chart] with following content: +* To enable the guest user in your {product-short} custom configuration, configure your {product} Helm Chart with following content: + -.{product} Helm Chart configuration fragment [source,yaml] ---- upstream: diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc index a0d9175dce..8479d63500 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc @@ -6,13 +6,12 @@ After an Operator-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features. .Prerequisites -* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. * You {configuring-book-link}#using-the-operator-to-run-rhdh-with-your-custom-configurationn[use the {product} Operator to run {product-short}]. .Procedure -* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#provisioning-your-custom-configuration[edit your {product-short} application configuration] with following content: +* To enable the guest user in your {product-short} custom configuration, edit `{my-app-config-file}`, your {product-short} application configuration file with following content: + -.`{my-app-config-file}` fragment [source,yaml] ---- auth: diff --git a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc index 5fcf00d7c3..d99ef3fafd 100644 --- a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc +++ b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc @@ -3,7 +3,8 @@ [id="creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog"] = Creating a custom transformer to provision users from {rhbk-brand-name} ({rhbk}) to the software catalog -To customize how {rhbk} users and groups are mapped to {product} entities, you can create a backend module that uses the `keycloakTransformerExtensionPoint` to provide custom user and group transformers for the Keycloak backend. +To customize how {product} provision users and groups to {product} software catalog entities, +you can create a backend module that uses the `keycloakTransformerExtensionPoint` to offer custom user and group transformers for the Keycloak backend. .Prerequisites * You have xref:enabling-user-authentication-with-rhbk[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog]. @@ -14,9 +15,8 @@ To customize how {rhbk} users and groups are mapped to {product} entities, you c . Add your custom user and group transformers to the `keycloakTransformerExtensionPoint`. + -The following is an example of how the backend module can be defined: +The following is an example `plugins/____/src/module.ts` file defining the backend module: + -.`plugins/____/src/module.ts` [source,javascript] ---- import { @@ -63,7 +63,7 @@ export const keycloakBackendModuleTransformer = createBackendModule({ + [IMPORTANT] ==== -The module's `pluginId` must be set to `catalog` to match the `pluginId` of the `keycloak-backend`; otherwise, the module fails to initialize. +Set the module's `pluginId` to `catalog` to match the `pluginId` of the `keycloak-backend`; otherwise, the module fails to initialize. ==== . Install this new backend module into your {product-short} backend. @@ -76,16 +76,17 @@ backend.add(import(backstage-plugin-catalog-backend-module-keycloak-transformer) .Verification * {product-short} imports the users and groups each time when started. -Check the console logs to verify that the synchronization is completed. +Check the console logs to verify the synchronization result. ++ +Successful synchronization example: + -.Successful synchronization example: [source,json] ---- {"class":"KeycloakOrgEntityProvider","level":"info","message":"Read 3 Keycloak users and 2 Keycloak groups in 1.5 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"} {"class":"KeycloakOrgEntityProvider","level":"info","message":"Committed 3 Keycloak users and 2 Keycloak groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"} ---- -* After the first import is complete, navigate to the *Catalog* page and select **User** to view the list of users. +* After the first import is complete, go to the *Catalog* page and select **User** to view the list of users. * When you select a user, you see the information imported from {rhbk}. diff --git a/modules/authentication/proc-enabling-user-authentication-with-github.adoc b/modules/authentication/proc-enabling-user-authentication-with-github.adoc index 3bbd1d91fe..486fccd3ad 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-github.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-github.adoc @@ -45,7 +45,7 @@ Select `Only on this account`. * **Client secret** . To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#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. +You can use these secrets in the {product-short} configuration files by using their environment variable name. `GITHUB_CLIENT_ID`:: Enter the saved **Client ID**. @@ -60,7 +60,7 @@ Enter the GitHub host domain: `github.com`. 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. +This plugin imports GitHub users and groups to the {product-short} software catalog. + `dynamic-plugins.yaml` file fragment: + @@ -93,7 +93,7 @@ catalog: `id`:: Enter a stable identifier for this provider, such as `githuborg`. -Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts. +Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities or conflicts. `githubUrl`:: Enter the configured secret variable name: `$\{GITHUB_URL}`. diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 4eb4d8f3c6..c5719c0b76 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -9,7 +9,7 @@ To authenticate users with {azure-brand-name}, configure the {azure-short} authe * 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 {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. * Your {product-short} backend can access the following hosts: @@ -17,7 +17,7 @@ Alternatively, you can ask your {azure-short} administrator to prepare the requi 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. +For retrieving organization data, including user and group data, to import into the {product-short} catalog. .Procedure :my-product-app-name-in-azure: @@ -25,7 +25,7 @@ For retrieving organization data, including user and group data, to be ingested .. Sign in to the link:https://entra.microsoft.com/[Microsoft Entra admin center]. -.. Optional: 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. +.. Optional: If you have access to many 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: @@ -61,7 +61,7 @@ Delegated Permissions:: `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. +Optional: Enter optional custom scopes for the Microsoft Graph API that you define both here and in your `{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*. @@ -84,7 +84,7 @@ Enter your saved *Application (client) secret*. . Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`) in your `dynamic-plugins.yaml` file. -This plugin ingests {azure-short} users and groups to the {product-short} software catalog. +This plugin imports {azure-short} users and groups to the {product-short} software catalog. + [source,yaml] ---- @@ -152,7 +152,6 @@ ifeval::["{optional-steps}" == "enable"] `authority`:: Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL], when different from the default: `\https://login.microsoftonline.com`. + -.`{my-app-config-file}` fragment with optional `queryMode` field [source,yaml] ---- catalog: @@ -167,7 +166,6 @@ catalog: Enter `advanced` when the default `basic` query mode is insufficient for your queries to the Microsoft Graph API. See link:https://learn.microsoft.com/en-us/graph/aad-advanced-queries[{azure-brand-name} advanced queries]. + -.`{my-app-config-file}` fragment with optional `queryMode` field [source,yaml] ---- catalog: @@ -184,8 +182,6 @@ Only one relationship can be expanded in a single request. See https://learn.microsoft.com/en-us/graph/query-parameters#expand-parameter[Microsoft Graph query expand parameter]. This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] or xref:userFilter[`user.filter`]. + -`{my-app-config-file}` fragment with optional `user.expand` field: -+ [source,yaml] ---- catalog: @@ -202,8 +198,6 @@ To filter users. See link:https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties[Microsoft Graph API] and link:https://learn.microsoft.com/en-us/graph/query-parameters#filter-parameter[Microsoft Graph API query filter parameters syntax]. This parameter and xref:userGroupMemberFilter[`userGroupMember.filter`] are mutually exclusive, only one can be specified. + -`{my-app-config-file}` fragment with optional `user.filter` field: -+ [source,yaml] ---- catalog: @@ -219,8 +213,6 @@ catalog: {product-short} loads photos by default. Enter `false` to avoid loading user photos. + -`{my-app-config-file}` fragment with optional `user.loadPhotos` field: -+ [source,yaml] ---- catalog: @@ -235,8 +227,6 @@ catalog: `user.select`:: Enter the link:https://learn.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource type] list to retrieve. + -`{my-app-config-file}` fragment with optional `user.select` field: -+ [source,yaml] ---- catalog: @@ -253,8 +243,6 @@ To use group membership to get users. To filter groups and fetch their members. This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. + -`{my-app-config-file}` fragment with optional `userGroupMember.filter` field: -+ [source,yaml] ---- catalog: @@ -271,8 +259,6 @@ To use group membership to get users. To search for groups and fetch their members. This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. + -`{my-app-config-file}` fragment with optional `userGroupMember.search` field: -+ [source,yaml] ---- catalog: @@ -290,8 +276,6 @@ Only one relationship can be expanded in a single request. See link:https://learn.microsoft.com/en-us/graph/query-parameters#expand-parameter[Customize Microsoft Graph responses with query parameters]. This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] instead of xref:userFilter[`user.filter`]. + -`{my-app-config-file}` fragment with optional `group.expand` field: -+ [source,yaml] ---- catalog: @@ -307,8 +291,6 @@ catalog: To filter groups. See link:https://learn.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0#properties[Microsoft Graph API query group syntax]. + -`{my-app-config-file}` fragment with optional `group.filter` field: -+ [source,yaml] ---- catalog: @@ -324,8 +306,6 @@ catalog: To search for groups. See link:https://learn.microsoft.com/en-us/graph/search-query-parameter[Microsoft Graph API query search parameter]. + -`{my-app-config-file}` fragment with optional `group.search` field: -+ [source,yaml] ---- catalog: @@ -394,7 +374,6 @@ If you want to use this parameter for a single-tenant application, uncomment and If your application registration is multi-tenant, leave this parameter blank. For more information, see link:https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/home-realm-discovery-policy[Home Realm Discovery]. + -.`{my-app-config-file}` file fragment with optional `domainHint` field [source,yaml,subs="+quotes,+attributes"] ---- auth: @@ -410,8 +389,6 @@ Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. The default and mandatory value lists: `openid`, `offline_access`, `profile`, `email`, and `User.Read`. + -`{my-app-config-file}` file fragment with optional `additionalScopes` field: -+ [source,yaml,subs="+quotes,+attributes"] ---- auth: @@ -427,7 +404,6 @@ auth: Lifespan of the user session. Enter a duration in `ms` library (such as '24h', '2 days'), ISO duration, or "human duration" format. + -.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field [source,yaml,subs="+quotes"] ---- auth: @@ -450,7 +426,6 @@ The authentication provider tries each sign-in resolver in order until it succee + WARNING: In production mode, only configure one resolver to ensure users are securely matched. + -.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog [source,yaml] ---- auth: @@ -489,7 +464,8 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh .Verification . To verify user and group provisioning, check the console logs for `MicrosoftGraphOrgEntityProvider` events. + -.Successful synchronization example: +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" diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index 77d7f7518e..d1397957c7 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -5,8 +5,8 @@ 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 {configuring-book-link}[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. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. +* You have enough 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 @@ -19,7 +19,7 @@ Save the value for the next step: .. To register your {product-short} in {rhbk}, in the created realm, {rhbk-docs-link}/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: `pass:c,a,q[{my-product-url}/api/auth/oidc/handler/frame]`. -... Navigate to the **Credentials** tab and copy the **Client secret**. +... Go to the **Credentials** tab and copy the **Client secret**. ... Save the values for the next step: * **Client ID** * **Client Secret** @@ -27,7 +27,7 @@ Save the value for the next step: .. To prepare for the verification steps, in the same realm, get the credential information for an existing user or {rhbk-docs-link}/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 {configuring-dynamic-plugins-book-link}#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. +You can use these secrets in the {product-short} configuration files by using their environment variable name. + `KEYCLOAK_CLIENT_ID`:: Enter the saved **Client ID**. @@ -38,11 +38,10 @@ Enter the saved **Client Secret**. `KEYCLOAK_BASE_URL`:: Enter the saved **{rhbk} realm base URL**. -. Enable the Keycloak organization plugin (`backstage-plugin-catalog-backend-module-keycloak-dynamic`). +. Enable the Keycloak organization plugin (`backstage-plugin-catalog-backend-module-keycloak-dynamic`) in your `dynamic-plugins.yaml` file. The plugin is named after {rhbk} upstream project. -This plugin ingests {rhbk} users and groups to the {product-short} software catalog. +This plugin imports {rhbk} users and groups to the {product-short} software catalog. + -.`dynamic-plugins.yaml` file fragment [source,yaml] ---- plugins: @@ -53,7 +52,6 @@ plugins: . To provision {rhbk} users and groups to the {product-short} software catalog, add the `catalog.providers.keycloakOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: + [id=keycloakOrgProviderId] -.`{my-app-config-file}` fragment with mandatory `keycloakOrg` fields [source,yaml] ---- catalog: @@ -68,13 +66,13 @@ catalog: ---- `baseUrl`:: -Enter your {rhbk} server URL, defined in the previous steps.]. +Enter your {rhbk} server URL, defined earlier. `clientId`:: -Enter your {product-short} application client ID in {rhbk}, defined in the previous steps. +Enter your {product-short} application client ID in {rhbk}, defined earlier. `clientSecret`:: -Enter your {product-short} application client secret in {rhbk}, defined in the previous steps. +Enter your {product-short} application client secret in {rhbk}, defined earlier. `realm`:: Enter the realm name to provision users, such as `master`. @@ -91,7 +89,6 @@ ifeval::["{optional-steps}" == "enable"] Enter the user count to query simultaneously. Default value: `100`. + -.`{my-app-config-file}` fragment with optional `userQuerySize` field [source,yaml] ---- catalog: @@ -105,7 +102,6 @@ catalog: Enter the group count to query simultaneously. Default value: `100`. + -.`{my-app-config-file}` fragment with optional `groupQuerySize` field [source,yaml] ---- catalog: @@ -119,7 +115,6 @@ catalog: Enter the schedule frequency. Supports cron, ISO duration, and "human duration" as used in code. + -.`{my-app-config-file}` fragment with optional `schedule.frequency` field [source,yaml] ---- catalog: @@ -134,7 +129,6 @@ catalog: Enter the timeout for the user provisioning job. Supports ISO duration and "human duration" as used in code. + -.`{my-app-config-file}` fragment with optional `schedule.timeout` field [source,yaml] ---- catalog: @@ -149,7 +143,6 @@ catalog: Enter the initial delay to wait for before starting the user provisioning job. Supports ISO duration and "human duration" as used in code. + -.`{my-app-config-file}` fragment with optional `schedule.initialDelay` field [source,yaml] ---- catalog: @@ -202,7 +195,6 @@ ifeval::["{optional-steps}" == "enable"] `callbackUrl`:: {rhbk} callback URL. + -.`{my-app-config-file}` fragment with optional `callbackURL` field [source,yaml] ---- auth: @@ -215,7 +207,6 @@ auth: `tokenEndpointAuthMethod`:: Token endpoint authentication method. + -.`{my-app-config-file}` fragment with optional `tokenEndpointAuthMethod` field [source,yaml] ---- auth: @@ -228,7 +219,6 @@ auth: `tokenSignedResponseAlg`:: Token signed response algorithm. + -.`{my-app-config-file}` fragment with optional `tokenSignedResponseAlg` field [source,yaml] ---- auth: @@ -241,7 +231,6 @@ auth: `additionalScopes`:: Enter additional {rhbk} scopes to request for during the authentication flow. + -.`{my-app-config-file}` fragment with optional `additionalScopes` field [source,yaml] ---- auth: @@ -277,7 +266,6 @@ The authentication provider tries each sign-in resolver in order until it succee + WARNING: In production mode, only configure one resolver to ensure users are securely matched. + -.`{my-app-config-file}` fragment with optional `resolvers` list [source,yaml] ---- auth: @@ -297,7 +285,6 @@ Configure the sign-in resolver to bypass the user provisioning requirement in th + WARNING: Use this option to explore {product-short} features, but do not use it in production. + -.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog [source,yaml] ---- auth: @@ -319,7 +306,6 @@ signInPage: oidc Lifespan of the user session. Enter a duration in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code. + -.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field [source,yaml,subs="+quotes"] ---- auth: @@ -334,7 +320,6 @@ auth: `backstageTokenExpiration`::: To modify the {product-short} token expiration from its default value of one hour, note that this refers to the validity of short-term cryptographic tokens, not the session duration. The expiration value must be set between 10 minutes and 24 hours. + -.`{my-app-config-file}` fragment with optional `auth.backstageTokenExpiration` field [source,yaml,subs="+quotes"] ---- auth: @@ -355,7 +340,8 @@ endif::[] . To verify user and group provisioning, check the console logs. + -.Successful synchronization example: +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" From 05b665c8229412aa878cf49d4287a21b5c55f87d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Thu, 25 Sep 2025 08:41:58 +0200 Subject: [PATCH 04/10] Apply suggestion from @JessicaJHee Co-authored-by: Jessica He --- .../con-understanding-authentication-and-user-provisioning.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc index 4111666703..bbf924f156 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc @@ -2,7 +2,7 @@ = Understanding authentication and user provisioning -This is an overview of how authentication and user provisioning function within {product}. +This is an overview of how authentication and user provisioning work in {product}. Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step. Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data. From 699d05705ca08e5fef429beb7989886fc70d4a33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 29 Sep 2025 14:26:34 +0200 Subject: [PATCH 05/10] MsGraph plugin is now GA, no longer tech preview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- .../proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index c5719c0b76..ac59106549 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -92,8 +92,6 @@ plugins: - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic' disabled: false ---- -+ -include::{docdir}/artifacts/snip-technology-preview.adoc[] . To provision {azure-short} users and groups to the {product-short} software catalog, add the `catalog.providers.microsoftGraphOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: + From 7f4b24a753c51d3caa3bb3320b02725df308a306 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 29 Sep 2025 14:32:03 +0200 Subject: [PATCH 06/10] Rephrased MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- assemblies/assembly-authenticating-with-the-guest-user.adoc | 3 +-- ...tiong-with-the-guest-user-on-a-helm-based-installation.adoc | 2 +- ...-with-the-guest-user-on-an-operator-based-installation.adoc | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/assemblies/assembly-authenticating-with-the-guest-user.adoc b/assemblies/assembly-authenticating-with-the-guest-user.adoc index f6da71658a..4ee7c0ee98 100644 --- a/assemblies/assembly-authenticating-with-the-guest-user.adoc +++ b/assemblies/assembly-authenticating-with-the-guest-user.adoc @@ -3,8 +3,7 @@ [id="authenticating-with-the-guest-user_{context}"] = Authenticating with the Guest user -To explore {product-short} features, you can skip configuring authentication and authorization. -You can configure {product-short} to log in as a Guest user and access {product-short} features. +For trial or non-production environments, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features. include::modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc[leveloffset=+1] diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc index c23a6d09ba..fc8b141325 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc @@ -3,7 +3,7 @@ [id="authenticating-with-the-guest-user-on-a-helm-based-installation_{context}"] = Authenticating with the Guest user on a Helm-based installation -On a Helm-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features. +For trial or non-production environments installed by using the {product} Helm chart, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features. .Prerequisites * You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc index 8479d63500..62838056b2 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc @@ -3,7 +3,7 @@ [id="authenticating-with-the-guest-user-on-an-operator-based-installation_{context}"] = Authenticating with the Guest user on an Operator-based installation -After an Operator-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features. +For trial or non-production environments installed by using the {product} Operator, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features. .Prerequisites * You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. From 4b2faabdea9dd6c9742a835f986db60a3e0d4e67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Mon, 29 Sep 2025 14:35:45 +0200 Subject: [PATCH 07/10] Follow logical order MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabrice Flore-Thébault --- .../proc-enabling-user-authentication-with-github.adoc | 2 +- ...proc-enabling-user-authentication-with-microsoft-azure.adoc | 2 +- .../proc-enabling-user-authentication-with-rhbk.adoc | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-github.adoc b/modules/authentication/proc-enabling-user-authentication-with-github.adoc index 486fccd3ad..cd3c02aefe 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-github.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-github.adoc @@ -3,7 +3,7 @@ [id="enabling-user-authentication-with-github"] = Enabling user authentication with GitHub -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. +To authenticate users with GitHub, provision the users and groups from GitHub to the {product-short} software catalog, and configure the GitHub authentication provider in {product}. .Prerequisites * You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index ac59106549..3136c3af48 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -3,7 +3,7 @@ [id="enabling-user-authentication-with-microsoft-azure"] = Enabling user authentication with {azure-brand-name} -To authenticate users with {azure-brand-name}, configure the {azure-short} authentication provider in {product} and provision the users and groups from {azure-short} to the {product-short} software catalog. +To authenticate users with {azure-brand-name}, provision the users and groups from {azure-short} to the {product-short} software catalog, and configure the {azure-short} authentication provider in {product}. .Prerequisites * You have the permission to register an application in {azure-short}. diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index d1397957c7..fd4aff7e61 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -2,7 +2,8 @@ [id="enabling-user-authentication-with-rhbk"] = Enabling user authentication with {rhbk-brand-name} ({rhbk}) -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. +To authenticate users with {rhbk-brand-name} ({rhbk}), +provision the users and groups from {rhbk} to the {product-short} software catalog, and configure the OpenID Connect (OIDC) authentication provider in {product}. .Prerequisites * You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. From f244aacf1549857ec0b5b042f98d217112553815 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 30 Sep 2025 10:20:46 +0200 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Jana Vrbkova --- ...ng-authentication-and-user-provisioning.adoc | 11 +++++++---- ...guest-user-on-a-helm-based-installation.adoc | 2 +- ...-user-on-an-operator-based-installation.adoc | 2 +- ...users-from-rhbk-to-the-software-catalog.adoc | 4 ++-- ...nabling-user-authentication-with-github.adoc | 10 +++++----- ...ser-authentication-with-microsoft-azure.adoc | 17 +++++++++++------ ...-enabling-user-authentication-with-rhbk.adoc | 8 ++++---- 7 files changed, 31 insertions(+), 23 deletions(-) diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc index bbf924f156..9c7ff4413a 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc @@ -2,8 +2,7 @@ = Understanding authentication and user provisioning -This is an overview of how authentication and user provisioning work in {product}. -Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step. +Learn about the authentication process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step. Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data. To fully enable catalog features, provision user and group data from the Identity Provider to the {product-short} software catalog. @@ -18,10 +17,14 @@ On successful authentication, the {product-short} authentication plugin, configu Configuring authentication and user provisioning is critical for several reasons. -* It secures your {product-short} instance by ensuring only authenticated users can gain access. -* It enables authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP. +* Securing your {product-short} instance by ensuring only authenticated users can gain access. +* Enabling authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP. * Provisioning user and group data to the catalog is necessary for various catalog features that rely on understanding entity ownership and relationships between users, groups, and software components. ++ +[IMPORTANT] +==== Without this provisioning step, features such as displaying who owns a catalog entity might not function correctly. +==== [TIP] ==== diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc index fc8b141325..809b51390d 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc @@ -10,7 +10,7 @@ For trial or non-production environments installed by using the {product} Helm c * You {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[use the {product} Helm chart to run {product-short}]. .Procedure -* To enable the guest user in your {product-short} custom configuration, configure your {product} Helm Chart with following content: +* Add following content to your {product} Helm Chart: + [source,yaml] ---- diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc index 62838056b2..50ddfe5aba 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc @@ -10,7 +10,7 @@ For trial or non-production environments installed by using the {product} Operat * You {configuring-book-link}#using-the-operator-to-run-rhdh-with-your-custom-configurationn[use the {product} Operator to run {product-short}]. .Procedure -* To enable the guest user in your {product-short} custom configuration, edit `{my-app-config-file}`, your {product-short} application configuration file with following content: +* Add the following content to the `{my-app-config-file}` file: + [source,yaml] ---- diff --git a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc index d99ef3fafd..659e51ab43 100644 --- a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc +++ b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc @@ -3,8 +3,8 @@ [id="creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog"] = Creating a custom transformer to provision users from {rhbk-brand-name} ({rhbk}) to the software catalog -To customize how {product} provision users and groups to {product} software catalog entities, -you can create a backend module that uses the `keycloakTransformerExtensionPoint` to offer custom user and group transformers for the Keycloak backend. +Customize how {product} provisions users and groups to {product} software catalog entities, +by creating a backend module that uses the `keycloakTransformerExtensionPoint` to offer custom user and group transformers for the Keycloak backend. .Prerequisites * You have xref:enabling-user-authentication-with-rhbk[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog]. diff --git a/modules/authentication/proc-enabling-user-authentication-with-github.adoc b/modules/authentication/proc-enabling-user-authentication-with-github.adoc index cd3c02aefe..4743a717f6 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-github.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-github.adoc @@ -3,7 +3,7 @@ [id="enabling-user-authentication-with-github"] = Enabling user authentication with GitHub -To authenticate users with GitHub, provision the users and groups from GitHub to the {product-short} software catalog, and configure the GitHub authentication provider in {product}. +Authenticate users with GitHub by provisioning the users and groups from GitHub to the {product-short} software catalog, and configuring the GitHub authentication provider in {product}. .Prerequisites * You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. @@ -71,7 +71,7 @@ plugins: disabled: false ---- -. To provision GitHub users and groups to the {product-short} software catalog, add the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: +. Provision GitHub users and groups to the {product-short} software catalog by adding the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: + [id=githubProviderId] [source,yaml] @@ -178,7 +178,7 @@ The authentication provider tries each sign-in resolver in order until it succee + [WARNING] ==== -In production mode, only configure one resolver to ensure users are securely matched. +Make sure users are securely matched in production mode, by configuring only one resolver. ==== `resolver`:::: @@ -194,12 +194,12 @@ Configure the sign-in resolver to bypass the user provisioning requirement in th + [WARNING] ==== -Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. +Do not use `dangerouslyAllowSignInWithoutUserInCatalog` in production. Use this configuration only to explore {product-short} features. ==== endif::[] .Verification -. To verify user and group provisioning, check the console logs. +. Verify user and group provisioning by checking the console logs. + Successful synchronization example: + diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 3136c3af48..9b3454ae56 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -3,7 +3,7 @@ [id="enabling-user-authentication-with-microsoft-azure"] = Enabling user authentication with {azure-brand-name} -To authenticate users with {azure-brand-name}, provision the users and groups from {azure-short} to the {product-short} software catalog, and configure the {azure-short} authentication provider in {product}. +Authenticate users with {azure-brand-name} by provisioning the users and groups from {azure-short} to the {product-short} software catalog, and configuring the {azure-short} authentication provider in {product}. .Prerequisites * You have the permission to register an application in {azure-short}. @@ -14,10 +14,10 @@ Alternatively, you can ask your {azure-short} administrator to prepare the requi * 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. +The {azure-brand-name} authorization server, which enables the authentication flow. `graph.microsoft.com`:: -For retrieving organization data, including user and group data, to import into the {product-short} catalog. +The server for retrieving organization data, including user and group data, to import into the {product-short} catalog. .Procedure :my-product-app-name-in-azure: @@ -148,7 +148,7 @@ endif::[] ifeval::["{optional-steps}" == "enable"] [id=authority] `authority`:: -Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL], when different from the default: `\https://login.microsoftonline.com`. +Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL] if it is different from the default: `\https://login.microsoftonline.com`. + [source,yaml] ---- @@ -360,7 +360,7 @@ Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_TENANT_ID}`. `signInPage`:: Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider. + -Optional: Consider adding optional fields. +Optional: Add optional fields. ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] @@ -385,7 +385,12 @@ auth: `additionalScopes`:: Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. -The default and mandatory value lists: `openid`, `offline_access`, `profile`, `email`, and `User.Read`. +The default and mandatory value lists following scopes: +* `openid` +* `offline_access` +* `profile` +* `email` +* `User.Read` + [source,yaml,subs="+quotes,+attributes"] ---- diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index fd4aff7e61..bcdc083738 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -2,8 +2,8 @@ [id="enabling-user-authentication-with-rhbk"] = Enabling user authentication with {rhbk-brand-name} ({rhbk}) -To authenticate users with {rhbk-brand-name} ({rhbk}), -provision the users and groups from {rhbk} to the {product-short} software catalog, and configure the OpenID Connect (OIDC) authentication provider in {product}. +Authenticate users with {rhbk-brand-name} ({rhbk}), +by provisioning the users and groups from {rhbk} to the {product-short} software catalog, and configuring the OpenID Connect (OIDC) authentication provider in {product}. .Prerequisites * You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. @@ -81,7 +81,7 @@ Enter the realm name to provision users, such as `master`. `loginRealm`:: Enter the realm name to authenticate users, such as `master`. + -Optional: Consider adding optional fields. +Optional: Add optional fields. ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] @@ -188,7 +188,7 @@ To allow the identity provider to automatically determine whether to prompt for 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. ==== + -Optional: Consider adding optional fields. +Optional: Add optional fields. ifeval::["{optional-steps}" == "disable"] See {configuring-book-link}[{configuring-book-title}]. endif::[] From f89b1881af652a1b7b3479fd1c53391d9d3a161d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 30 Sep 2025 10:22:45 +0200 Subject: [PATCH 09/10] Update modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc --- .../proc-enabling-user-authentication-with-rhbk.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index bcdc083738..0af0c3a8f2 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -265,7 +265,10 @@ Matches the preferred username with the user entity name. + The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. + -WARNING: In production mode, only configure one resolver to ensure users are securely matched. +[WARNING] +==== +In production mode, only configure one resolver to ensure users are securely matched. +==== + [source,yaml] ---- From 43f40e0c4b2368280bab74365a961b13c6953bc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 30 Sep 2025 10:25:13 +0200 Subject: [PATCH 10/10] Update modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc --- .../proc-enabling-user-authentication-with-rhbk.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index 0af0c3a8f2..fefdc4bb7f 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -287,7 +287,10 @@ auth: `dangerouslyAllowSignInWithoutUserInCatalog: true`:::: Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. + -WARNING: Use this option to explore {product-short} features, but do not use it in production. +[WARNING] +==== +Use this option to explore {product-short} features, but do not use it in production. +==== + [source,yaml] ----