RHIDP-7975 Enabling authentication procedures with mandatory steps only

Used variable names defined in the default config
Added '_mod-docs-content-type' attribute definition

Signed-off-by: Fabrice Flore-Thébault <[email protected]>
Co-authored-by: Jessica He <[email protected]>

Author: themr0c

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]
+

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.
 ====

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 `__<your_github_organization_name>__`.
 
 . Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`).
 This plugin ingests GitHub users and groups to the {product-short} software catalog.
 +
-.`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,23 +124,24 @@ auth:
   providers:
     github:
       production:
-        clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
-        clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
+        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: `${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: __<your_intermediate_service_url/handler>__
         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}]
 

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: