Update Kerberos SSO documentation for foremanctl #4543

aneta-petrova · 2025-12-16T18:25:39Z

What changes are you introducing?

Updating documentation on enabling FreeIPA-based authentication for foremanctl. This also includes publishing a foremanctl-flavored Configuring User Authentication guide.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

theforeman/foremanctl#312

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

N/A

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

Summary by Sourcery

Update Kerberos SSO and external authentication documentation to cover foremanctl and related workflows.

Documentation:

Refresh Kerberos SSO guides for FreeIPA and Active Directory to align with current foremanctl behavior and terminology.
Extend user authentication documentation with updated procedures for configuring authentication sources, enrolling servers in FreeIPA, and logging in with FreeIPA credentials, including hammer CLI usage.
Add a new procedure describing how to reset external authentication configuration for Kerberos SSO.
Update the Configuring User Authentication guide index and nightly documentation metadata to include the foremanctl-focused content.

sourcery-ai · 2025-12-16T18:25:46Z

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Updates Kerberos SSO and FreeIPA authentication documentation to incorporate foremanctl workflows, including enrollment, login, and recovery steps, and aligns the Configuring User Authentication guide and nightly metadata with the new content.

File-Level Changes

Change	Details	Files
Align Kerberos SSO and FreeIPA configuration docs with foremanctl workflows and terminology.	Adjust existing Kerberos SSO with FreeIPA assembly to reference foremanctl usage and flows. Update Active Directory Kerberos SSO, external user groups, HBAC, and authentication source modules to mention or integrate foremanctl where applicable. Clarify steps and prerequisites in FreeIPA and AD SSO setup to better match current tooling behavior.	`guides/common/assembly_configuring-kerberos-sso-with-freeipa-in-project.adoc` `guides/common/modules/con_configuring-kerberos-sso-for-active-directory-users-in-project.adoc` `guides/common/modules/proc_configuring-external-user-groups.adoc` `guides/common/modules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc` `guides/common/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc` `guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc`
Refresh enrollment and CLI login procedures to cover FreeIPA-based authentication for foremanctl and hammer.	Update enrollment instructions for joining the server to a FreeIPA domain to reflect current commands and flags relevant to foremanctl usage. Revise CLI login procedure using FreeIPA credentials, ensuring hammer usage is consistent with foremanctl-based auth flows.	`guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc` `guides/common/modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc`
Introduce recovery documentation for resetting external authentication configuration when using Kerberos SSO.	Add a new procedure module that walks through resetting external authentication configuration for Kerberos SSO scenarios. Ensure the new reset procedure is referenced by or compatible with the other Kerberos SSO documentation modules.	`guides/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc`
Wire updated modules into the main Configuring User Authentication guide and nightly documentation metadata.	Update the Configuring User Authentication guide master assembly to include or reference the refreshed Kerberos/FreeIPA and foremanctl-related modules. Adjust nightly release JSON metadata so the updated and new documentation is available in the nightly build navigation.	`guides/doc-Configuring_User_Authentication/master.adoc` `web/releases/nightly.json`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

github-actions · 2025-12-16T18:29:28Z

The PR preview for 810954c is available at theforeman-foreman-documentation-preview-pr-4543.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

sourcery-ai

Hey there - I've reviewed your changes - here's some feedback:

In the new and updated Kerberos/FreeIPA modules, double-check that references to foremanctl vs. hammer are consistently scoped (for example, in titles, prerequisites, and command snippets) so users can easily tell which tool a given step applies to.
Since you added proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc, consider linking to this procedure from the main Kerberos SSO configuration assembly and any troubleshooting sections so users can discover the reset workflow when they run into misconfiguration issues.
For the nightly.json changes, verify that the new or updated entries for the Configuring User Authentication and Kerberos/FreeIPA docs use consistent slugs/URLs and titles with the corresponding master.adoc files to avoid broken or duplicated navigation items.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the new and updated Kerberos/FreeIPA modules, double-check that references to `foremanctl` vs. `hammer` are consistently scoped (for example, in titles, prerequisites, and command snippets) so users can easily tell which tool a given step applies to.
- Since you added `proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc`, consider linking to this procedure from the main Kerberos SSO configuration assembly and any troubleshooting sections so users can discover the reset workflow when they run into misconfiguration issues.
- For the `nightly.json` changes, verify that the new or updated entries for the Configuring User Authentication and Kerberos/FreeIPA docs use consistent slugs/URLs and titles with the corresponding `master.adoc` files to avoid broken or duplicated navigation items.

## Individual Comments

### Comment 1
<location> `guides/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc:17` </location>
<code_context>
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
+ifdef::foremanctl[]
+# foremanctl deploy --pam-service foreman-prod
+endif::[]
</code_context>

<issue_to_address>
**issue (review_instructions):** The .Verification section for the foremanctl variant is just a placeholder and does not provide actual verification steps, so the verification instruction is not fulfilled.

The non-foremanctl path includes a concrete verification step (`--help | grep foreman-ipa-authentication` and expected values), but the foremanctl path only has the placeholder `#How can users verify this?#`.

Please add explicit verification instructions for the foremanctl scenario (for example, a command or UI check that confirms external authentication has been reset and what output or behavior to expect), or otherwise align it with the level of verification provided for the installer-based variant.

<details>
<summary>Review instructions:</summary>

**Path patterns:** `guides/common/modules/proc*.adoc`

**Instructions:**
- Verification steps are included where appropriate.

</details>
</issue_to_address>

### Comment 2
<location> `guides/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc:13` </location>
<code_context>
+[IMPORTANT]
+====
+Resetting external authentication prevents users from accessing {Project} as described in xref:configuring-kerberos-sso-with-{FreeIPA-context}-in-{project-context}[] and xref:configuring-kerberos-sso-for-active-directory-users-in-project_{context}[].
+However, some configuration files, such as configuration files for the System Security Services Daemon (SSSD), will remain modified because {Project} does not have access to the previous state of these files.
+====
+
</code_context>

<issue_to_address>
**suggestion (review_instructions):** The phrase "will remain modified" uses passive voice and could be rephrased to an active construction to meet the style requirement.

Consider rephrasing to avoid the passive construction, for example:

"However, some configuration files, such as those for the System Security Services Daemon (SSSD), stay in their modified state because {Project} does not have access to their previous state."

This keeps the meaning while avoiding passive voice.

<details>
<summary>Review instructions:</summary>

**Path patterns:** `guides/common/*.adoc,guides/common/modules/*.adoc`

**Instructions:**
Avoid passive voice in verbs.

</details>
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc

aneta-petrova · 2025-12-16T18:35:55Z

These preview links are relevant for tech review:

Configuring User Authentication, update to contain only content that's expected to work with foremanctl:

Configuring User Authentication, based on the current installer (section 12. Resetting external authentication configuration for Kerberos SSO is mostly new and needs a review):

ekohl

Not a complete read through but some things that jumped out to me.

Can we define {project-package-install} as just {package-install} for foremanctl? We already do that for everything except the satellite builds everywhere else and keeps the changes smaller.

...on/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc

adamruzicka

It reads well, but the verification part for disabling with foremanctl needs to be flushed out

...ules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc

lhellebr · 2025-12-18T15:06:16Z

guides/common/modules/con_configuring-kerberos-sso-for-active-directory-users-in-project.adoc

 * Username and password
 * Kerberos single sign-on

+ifndef::foremanctl[]


Does this mean that these are not available with foremanctl? I think that's not true.

I excluded these lines (for now) because the NOTE leads to an LDAP procedure which uses foreman-maintain. The maintain tool will be replaced by foremanctl, which means the procedure cannot yet be included in a foremanctl guide. We can include it after we know what the replacement for foreman-maintain service restart will look like and that the procedure works in the foremanctl world.

The other link leads to an AD procedure, which is being exposed in this PR. However, modifying the NOTE to include two links for a pre-foremanctl version of the guide and one link for the post-foremanctl version would take some rewriting. I don't think it's worth it right now -- we can just include the whole NOTE again after we verify that the LDAP procedure is safe for foremanctl.

guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc

guides/common/modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc

guides/doc-Configuring_User_Authentication/master.adoc

aneta-petrova · 2025-12-18T20:19:53Z

These preview links are relevant for tech review:

Configuring User Authentication, update to contain only content that's expected to work with foremanctl:
* https://theforeman-foreman-documentation-preview-pr-4543.surge.sh/nightly/Configuring_User_Authentication/index-foremanctl-katello.html

* https://theforeman-foreman-documentation-preview-pr-4543.surge.sh/nightly/Configuring_User_Authentication/index-foremanctl-satellite.html
Configuring User Authentication, based on the current installer (section 12. Resetting external authentication configuration for Kerberos SSO is mostly new and needs a review):
* https://theforeman-foreman-documentation-preview-pr-4543.surge.sh/nightly/Configuring_User_Authentication/index-katello.html

* https://theforeman-foreman-documentation-preview-pr-4543.surge.sh/nightly/Configuring_User_Authentication/index-satellite.html

A few threads are still open (for visibility due to open questions not related to the documentation update or just interesting information being shared) but other than that, I think I've implemented all the feedback so far. Which means these guides are ready for re-review.

...ules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc

...on/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc

aneta-petrova · 2026-01-05T13:40:17Z

Hello @adamruzicka @lhellebr @maximiliankolb, do you have any further comments or suggestions? If not, can you please consider acking this PR?

adamruzicka

One pedantic comment, otherwise it reads well

...ules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc

adamruzicka

Reads well

guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc

lhellebr · 2026-01-06T09:48:54Z

One clarifying comment, otherwise LGTM

maximiliankolb

A few minor suggestions on style. I cannot comment on the tech at all.

...ules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc

Lennonka

Just a few nitpicks.

guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc

aneta-petrova · 2026-01-15T12:30:38Z

All suggestions have been applied, @maximiliankolb and/or @Lennonka, can you please re-review?

maximiliankolb

LGTM style-wise.

Lennonka

LGTM, thanks!

Update IPA Kerberos auth source for foremanctl Update AD external auth source for foremanctl Update procedure on resetting external auth Move reset to its own module Update ext auth reset with additional details Drop equal signs Define project-package-install for foremanctl Clarify auth sources affected by auth config reset Update PAM service option Add ext auth overview to foremanctl Configuring User Auth Clarify that auth source are mutually exclusive Add verification step for resetting Kerberos SSO Apply suggestions from style review Co-authored-by: Maximilian Kolb <[email protected]> Call out a f-ctl prereq explicitly Ensure standalone Hammer scenario is covered Drop an internal comment about why a prereq is here Reference --add-feature hammer Apply easy fixes from style review Co-authored-by: Lena Ansorgová <[email protected]> Co-authored-by: Maximilian Kolb <[email protected]> Move stdout outside of a command block

aneta-petrova · 2026-01-16T11:24:30Z

Squashing some commits so that we can add two separate commits to master when merging. No changes to the diff.

pr-processor bot added the Not yet reviewed label Dec 16, 2025

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Dec 16, 2025

aneta-petrova marked this pull request as ready for review December 16, 2025 18:32

sourcery-ai bot reviewed Dec 16, 2025

View reviewed changes

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc Show resolved Hide resolved

pr-processor bot removed the Not yet reviewed label Dec 16, 2025

aneta-petrova force-pushed the foremanctl-kerberos-auth branch from ff45f7c to b752f34 Compare December 16, 2025 18:41

ekohl reviewed Dec 17, 2025

View reviewed changes

...on/modules/proc_configuring-the-active-directory-authentication-source-on-projectserver.adoc Outdated Show resolved Hide resolved

adamruzicka suggested changes Dec 17, 2025

View reviewed changes

...ules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc Outdated Show resolved Hide resolved

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc Show resolved Hide resolved

pr-processor bot added the Waiting on contributor Requires an action from the author label Dec 17, 2025

aneta-petrova removed the Waiting on contributor Requires an action from the author label Dec 17, 2025

lhellebr reviewed Dec 18, 2025

View reviewed changes

guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc Outdated Show resolved Hide resolved

lhellebr reviewed Dec 18, 2025

View reviewed changes

guides/common/modules/proc_logging-in-to-hammer-cli-with-freeipa-credentials.adoc Show resolved Hide resolved

lhellebr reviewed Dec 18, 2025

View reviewed changes

guides/doc-Configuring_User_Authentication/master.adoc Show resolved Hide resolved

Add foremanctl-flavored Configuring User Authentication

c5f79ab

aneta-petrova force-pushed the foremanctl-kerberos-auth branch from b0073ce to b4e1a67 Compare December 18, 2025 19:03

lhellebr reviewed Dec 19, 2025

View reviewed changes

...ules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc Show resolved Hide resolved

maximiliankolb reviewed Dec 19, 2025

View reviewed changes

aneta-petrova force-pushed the foremanctl-kerberos-auth branch from ce28e1d to 34dcea9 Compare January 2, 2026 09:18

aneta-petrova added the Waiting for code Requires merge of related code in another repository before it can be merged label Jan 2, 2026

adamruzicka reviewed Jan 5, 2026

View reviewed changes

...ules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc Outdated Show resolved Hide resolved

aneta-petrova added tech review done No issues from the technical perspective and removed Needs tech review Requires a review from the technical perspective labels Jan 6, 2026

adamruzicka approved these changes Jan 6, 2026

View reviewed changes

lhellebr reviewed Jan 6, 2026

View reviewed changes

guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc Outdated Show resolved Hide resolved

aneta-petrova added testing done No issues from the functional perspective and removed Needs testing Requires functional testing labels Jan 6, 2026

maximiliankolb reviewed Jan 7, 2026

View reviewed changes

Lennonka requested changes Jan 12, 2026

View reviewed changes

guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc Outdated Show resolved Hide resolved

...es/common/modules/proc_resetting-external-authentication-configuration-for-kerberos-sso.adoc Outdated Show resolved Hide resolved

pr-processor bot added Waiting on contributor Requires an action from the author Needs re-review and removed Waiting on contributor Requires an action from the author labels Jan 12, 2026

aneta-petrova force-pushed the foremanctl-kerberos-auth branch from 871a886 to cba9b96 Compare January 15, 2026 12:25

pr-processor bot removed the Needs re-review label Jan 15, 2026

maximiliankolb approved these changes Jan 15, 2026

View reviewed changes

maximiliankolb added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Jan 15, 2026

aneta-petrova mentioned this pull request Jan 15, 2026

Kerberos-based authentication theforeman/foremanctl#312

Open

7 tasks

Lennonka approved these changes Jan 15, 2026

View reviewed changes

aneta-petrova force-pushed the foremanctl-kerberos-auth branch from cba9b96 to 810954c Compare January 16, 2026 11:22

Update Kerberos SSO documentation for foremanctl #4543

Are you sure you want to change the base?

Update Kerberos SSO documentation for foremanctl #4543

Conversation

aneta-petrova commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Summary by Sourcery

Uh oh!

sourcery-ai bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

github-actions bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aneta-petrova commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ekohl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamruzicka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lhellebr Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

aneta-petrova Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Dec 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Jan 5, 2026

Uh oh!

adamruzicka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamruzicka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lhellebr commented Jan 6, 2026

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lennonka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Jan 15, 2026

Uh oh!

aneta-petrova commented Dec 16, 2025 •

edited

Loading

sourcery-ai bot commented Dec 16, 2025 •

edited

Loading

github-actions bot commented Dec 16, 2025 •

edited

Loading

aneta-petrova commented Dec 16, 2025 •

edited

Loading