[RHDHBUGS-2722]: Restructure authentication title to JTBD outline by themr0c · Pull Request #2049 · redhat-developer/red-hat-developers-documentation-rhdh

themr0c · 2026-04-14T19:09:45Z

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s): 1.10.0
Issue: https://redhat.atlassian.net/browse/RHDHBUGS-2722
Preview: N/A

Summary

Restructure the authentication title from provider-centric (one assembly per IdP bundling secrets, auth, provisioning) to JTBD-centric (separate sections for sharing secrets, importing users, enabling authentication)
Split 4 monolithic IdP procedures (RHBK, GitHub, Azure, GitLab) into 3 focused modules each: secret sharing, user import, auth configuration
Extract LDAP secret-sharing steps into a standalone procedure
Update the get-started title's mandatory-only authentication assembly to use the new split procedures
Delete 26 old monolithic files (procedures, assemblies, snippets)

New outline

Understanding authentication and user provisioning
Enabling or disabling authentication with the guest user
Sharing a secret with your identity provider (RHBK, LDAP, GitHub, Azure, GitLab)
Importing users and groups from your identity provider (+ custom transformers)
Enabling authentication with your identity provider (RHBK, GitHub, Azure, GitLab)
Enabling authentication with external services (auxiliary IdP, service-to-service)
Enabling auto-logout for inactive users
Troubleshooting authentication issues

Test plan

All 32 titles build successfully (build-ccutil.sh: 32 passed, 0 failed)
Both affected titles verified: auth title and get-started title
No broken cross-references (ccutil reports zero Unknown ID errors)
CQA checks pass on both titles
Review new procedure content for accuracy (secrets, import, auth separation)
Verify PR preview renders correctly

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

rhdh-bot · 2026-04-14T19:11:49Z

rhdh-bot · 2026-04-14T19:12:15Z

Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-2049/ @ 4/15/2026, 6:33:50 PM

Establish the new section structure: share secrets, import users, enable auth, external services. Existing content temporarily parked under the auth section pending per-IdP splits. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Extract secrets sharing, user import, and auth config from the monolithic RHBK procedure into focused JTBD modules. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace old monolithic proc-enable-user-authentication-with-{rhbk,github,microsoft-azure} wrapper includes with the new split procedures (secret, import, auth) for each IdP. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…d snippets Delete 26 files replaced by the new JTBD-structured authentication docs: - 4 old per-IdP assemblies (RHBK, GitHub, Microsoft Azure, GitLab) - 3 old monolithic with-optional-steps procedures - 1 old monolithic GitLab procedure - 3 old mandatory-only wrapper procedures - 15 orphaned snippet files 5 snippet files retained (still referenced by new split procedures): - snip-enabling-user-authentication-with-rhbk-common-prerequisites.adoc - snip-enabling-user-authentication-with-github-common-prerequisites.adoc - snip-enabling-user-authentication-with-microsoft-azure-common-prerequisites.adoc - snip-enable-user-authentication-with-gitlab-common-prerequisites.adoc - snip-disabling-the-guest-user-step.adoc Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Hardcoded xref targets to _share-a-secret-with-your-identity-provider broke when procedures were included in the mandatory-only assembly (which uses a different context). Introduce a {secrets-context} attribute set by each parent assembly to ensure xrefs resolve correctly in both the auth title and the get-started mandatory-only assembly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Custom transformer prerequisites referenced old monolithic procedure IDs. LDAP procedure referenced RHBK auth with {parent-context} which no longer resolves correctly after the assembly restructure. Hardcode the correct target contexts for cross-assembly xrefs.

Update xref context suffixes to match the actual assembly contexts: - LDAP procedure: use enable-authentication-with-your-identity-provider - Troubleshoot catalog errors: use import-users-and-groups-from-your-identity-provider Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

themr0c · 2026-04-15T17:49:24Z

No technical review needed because it is only content reshuffle (acked by @JessicaJHee).

sonarqubecloud · 2026-04-15T18:21:59Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

deerskindoll

first batch of comments

deerskindoll · 2026-04-16T09:23:39Z

+:secrets-context: enable-authentication-in-rhdh-with-mandatory-steps-only

 [role="_abstract"]
 You can enable authentication in {product} to allow users to sign in using credentials from an external identity provider, such as {rhbk}, GitHub, or {azure-brand-name}, and provision user and group data to the software catalog.


Suggested change

You can enable authentication in {product} to allow users to sign in using credentials from an external identity provider, such as {rhbk}, GitHub, or {azure-brand-name}, and provision user and group data to the software catalog.

Enable authentication in {product} to allow users to sign in using credentials from an external identity provider, such as {rhbk}, GitHub, or {azure-brand-name}, and provision user and group data to the software catalog.

deerskindoll · 2026-04-16T09:25:02Z

+In production more, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.
 ====
+
+. To disable the guest login option, in the `{my-app-config-file}` file, set the authentication environment to `production`:


is this an optional step?

deerskindoll · 2026-04-16T09:25:20Z

 [WARNING]
 ====
-In production mode, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.
+In production more, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.


Suggested change

In production more, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.

In production mode, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.

deerskindoll · 2026-04-16T09:26:06Z

+
+.Procedure
+
+. Enable the GitHub authentication provider, by adding the GitHub authentication provider section to your `{my-app-config-file}` file:


Suggested change

. Enable the GitHub authentication provider, by adding the GitHub authentication provider section to your `{my-app-config-file}` file:

. Add a GitHub authentication provider section to your `{my-app-config-file}` file:

deerskindoll · 2026-04-16T09:26:38Z

+. To verify GitHub authentication:
+.. Go to the {product-short} login page.
+.. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled.
+.. Log in with a GitHub account.


Suggested change

. To verify GitHub authentication:

.. Go to the {product-short} login page.

.. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled.

.. Log in with a GitHub account.

. Go to the {product-short} login page.

. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled.

. Log in with a GitHub account.

deerskindoll · 2026-04-16T09:37:11Z

+Enter your schedule initial delay, in the ISO duration or "human duration" format.
+
+.Verification
+* To verify user and group provisioning, check the console logs.


Suggested change

* To verify user and group provisioning, check the console logs.

* Check user and group provisioning in the console logs.

deerskindoll · 2026-04-16T09:38:28Z

+
+.Procedure
+
+. Enable provisioning for GitLab users and groups to the {product-short} software catalog by adding the provider section to your {product-very-short} `{my-app-config-file}` file:


Suggested change

. Enable provisioning for GitLab users and groups to the {product-short} software catalog by adding the provider section to your {product-very-short} `{my-app-config-file}` file:

. Add a GitLab provider section to your {product-very-short} `{my-app-config-file}` file:

deerskindoll · 2026-04-16T09:44:34Z

+Set to `true` to include users who do not occupy a paid seat. This setting applies only to GitLab SaaS.
+
+`schedule.initialDelay`::
+Enter your schedule initial delay, in the ISO duration or "human duration" format.


Suggested change

Enter your schedule initial delay, in the ISO duration or "human duration" format.

Enter your schedule initial delay, in the ISO duration or `HumanDuration` format.

deerskindoll · 2026-04-16T09:45:05Z

+Enter your schedule initial delay, in the ISO duration or "human duration" format.
+
+`schedule.frequency`::
+Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.


Suggested change

Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.

Enter your schedule frequency, in the cron, ISO duration, or `HumanDuration` format.

deerskindoll · 2026-04-16T09:45:34Z

+Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
+
+`schedule.timeout`::
+Enter your schedule timeout, in the ISO duration or "human duration" format.


Suggested change

Enter your schedule timeout, in the ISO duration or "human duration" format.

Enter your schedule timeout, in the ISO duration or `HumanDuration` format.

themr0c temporarily deployed to internal April 14, 2026 19:09 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 14, 2026 19:10 — with GitHub Actions Inactive

themr0c requested a review from JessicaJHee April 14, 2026 19:10

themr0c added Peer review needed 📖 Technical review needed 🔩 Test all the procedures labels Apr 14, 2026

themr0c force-pushed the rhdhbugs-2722-jtbd-authentication branch from 4ff81b6 to 154b1a4 Compare April 15, 2026 12:11

themr0c temporarily deployed to internal April 15, 2026 12:12 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 15, 2026 14:46 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 15, 2026 16:30 — with GitHub Actions Inactive

themr0c and others added 10 commits April 15, 2026 18:51

feat: split RHBK auth procedure into secret, import, and auth modules

444ae3d

Extract secrets sharing, user import, and auth config from the monolithic RHBK procedure into focused JTBD modules. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: split GitHub auth procedure into secret, import, and auth modules

78d4adf

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: split Azure auth procedure into secret, import, and auth modules

548a56d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: split GitLab auth procedure into secret, import, and auth modules

345a644

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: extract LDAP secret sharing into dedicated procedure

7225040

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

themr0c force-pushed the rhdhbugs-2722-jtbd-authentication branch from 5e564f5 to 3793412 Compare April 15, 2026 16:52

themr0c temporarily deployed to internal April 15, 2026 16:53 — with GitHub Actions Inactive

Merge branch 'main' into rhdhbugs-2722-jtbd-authentication

bcf0c89

themr0c temporarily deployed to internal April 15, 2026 16:59 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 15, 2026 17:09 — with GitHub Actions Inactive

Merge branch 'main' into rhdhbugs-2722-jtbd-authentication

abe8821

themr0c temporarily deployed to internal April 15, 2026 17:12 — with GitHub Actions Inactive

themr0c removed the Technical review needed 🔩 Test all the procedures label Apr 15, 2026

themr0c removed the request for review from JessicaJHee April 15, 2026 17:48

Merge branch 'main' into rhdhbugs-2722-jtbd-authentication

27bfd07

themr0c temporarily deployed to internal April 15, 2026 17:49 — with GitHub Actions Inactive

deerskindoll self-assigned this Apr 15, 2026

Merge branch 'main' into rhdhbugs-2722-jtbd-authentication

26d15f6

themr0c temporarily deployed to internal April 15, 2026 18:06 — with GitHub Actions Inactive

themr0c temporarily deployed to internal April 15, 2026 18:07 — with GitHub Actions Inactive

Merge branch 'main' into rhdhbugs-2722-jtbd-authentication

bbb48d9

themr0c temporarily deployed to internal April 15, 2026 18:21 — with GitHub Actions Inactive

deerskindoll reviewed Apr 16, 2026

View reviewed changes

	You can enable authentication in {product} to allow users to sign in using credentials from an external identity provider, such as {rhbk}, GitHub, or {azure-brand-name}, and provision user and group data to the software catalog.
	Enable authentication in {product} to allow users to sign in using credentials from an external identity provider, such as {rhbk}, GitHub, or {azure-brand-name}, and provision user and group data to the software catalog.

	In production more, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.
	In production mode, do not enable `dangerouslyAllowSignInWithoutUserInCatalog`.


		.Procedure

		. Enable the GitHub authentication provider, by adding the GitHub authentication provider section to your `{my-app-config-file}` file:

	. Enable the GitHub authentication provider, by adding the GitHub authentication provider section to your `{my-app-config-file}` file:
	. Add a GitHub authentication provider section to your `{my-app-config-file}` file:

	* To verify user and group provisioning, check the console logs.
	* Check user and group provisioning in the console logs.


		.Procedure

		. Enable provisioning for GitLab users and groups to the {product-short} software catalog by adding the provider section to your {product-very-short} `{my-app-config-file}` file:

	. Enable provisioning for GitLab users and groups to the {product-short} software catalog by adding the provider section to your {product-very-short} `{my-app-config-file}` file:
	. Add a GitLab provider section to your {product-very-short} `{my-app-config-file}` file:

	Enter your schedule initial delay, in the ISO duration or "human duration" format.
	Enter your schedule initial delay, in the ISO duration or `HumanDuration` format.

	Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
	Enter your schedule frequency, in the cron, ISO duration, or `HumanDuration` format.

	Enter your schedule timeout, in the ISO duration or "human duration" format.
	Enter your schedule timeout, in the ISO duration or `HumanDuration` format.

Conversation

themr0c commented Apr 14, 2026

Summary

New outline

Test plan

Uh oh!

rhdh-bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Content Quality Assessment Results

CQA Report

Summary

Uh oh!

rhdh-bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

themr0c commented Apr 15, 2026

Uh oh!

sonarqubecloud bot commented Apr 15, 2026

Quality Gate passed

Uh oh!

deerskindoll left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rhdh-bot commented Apr 14, 2026 •

edited

Loading

rhdh-bot commented Apr 14, 2026 •

edited

Loading