Update Kerberos SSO documentation for foremanctl #4543
Conversation
Reviewer's guide (collapsed on small PRs)Reviewer's GuideUpdates 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
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
github-actions
bot
added
Needs tech review
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
- In the new and updated Kerberos/FreeIPA modules, double-check that references to
foremanctlvs.hammerare 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.jsonchanges, verify that the new or updated entries for the Configuring User Authentication and Kerberos/FreeIPA docs use consistent slugs/URLs and titles with the correspondingmaster.adocfiles 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>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
Show resolved
Hide resolved
|
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): |
aneta-petrova
force-pushed
the
foremanctl-kerberos-auth
branch
from
ff45f7c to
b752f34
Compare
ekohl
left a comment
ekohl
left a comment
There was a problem hiding this comment.
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
Outdated
Show resolved
Hide resolved
adamruzicka
left a comment
adamruzicka
left a comment
There was a problem hiding this comment.
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
Outdated
Show resolved
Hide resolved
| ifdef::foremanctl[] | ||
| #How can users verify this?# | ||
| endif::[] |
There was a problem hiding this comment.
Not sure if output of foremanctl is stable enough to do something like we do with the old installer. The following is a bit of a poor man's solution, but it should work.
$ curl -k -u : --negotiate https://foreman.example.com/users/extlogin
<html><body>You are being <a href="https://foreman.example.com/users/login">redirected</a>.</body></html>
There was a problem hiding this comment.
Considering that the ext auth options are expected to be mutually exclusive, and thus users or foremanctl itself should check if there is an ext auth source already configured, it would be great if we had a more user-friendly way of checking the current configuration. Can something like that be implemented?
And on a similar note: What will happen if users try to configure an external auth source in a situation where a different one is already configured? I was hoping foremanctl deploy --external-authentication could display a warning in this case. Alternatively, I might have to write a prerequisite for each of the configuration procedures but that would certainly be a lot more error-prone than the tool displaying a message.
There was a problem hiding this comment.
thus users or foremanctl itself should check if there is an ext auth source already configured
I still haven't had my morning coffee so I might be a bit slower. Why should they need to check?
An alternative would be checking settings, but that doesn't tell the whole story as large chunk of the configuration takes place outside of foreman.
## Should be true when external-authentication is ipa or ipa_with_api
# hammer setting info --name authorize_login_delegation | grep -e Name -e Value
Name: authorize_login_delegation
Value: true
## Should be true when external-authentication is ipa_with_api
# hammer setting info --name authorize_login_delegation_api | grep -e Name -e Value
Name: authorize_login_delegation_api
Value: false
What will happen if users try to configure an external auth source in a situation where a different one is already configured?
The current model is that external authentication either is or is not configured. Whether you use ipa or ipa_with_api just changes how, but you can't really have multiple external auth sources configured at the same time. Much like the old installer, foremanctl works in a "make it so" way, so if they try to configure an external auth source in any way, it will happen, replacing what was there before.
There was a problem hiding this comment.
thus users or foremanctl itself should check if there is an ext auth source already configured
I still haven't had my morning coffee so I might be a bit slower. Why should they need to check?
If I configure the ipa_with_api source, forget about it, and then configure ipa, what will happen?
Similarly, in the future, if I configure the hypothetical oidc source, forget about it, and then configure ipa, what will happen?
Will the configuration get overwritten without a warning? Or will foremanctl refuse to perform the action because it will notice that an authentication source is already configured?
There was a problem hiding this comment.
Much like the old installer, foremanctl works in a "make it so" way, so if they try to configure an external auth source in any way, it will happen, replacing what was there before.
And this is the answer to the question I clarified above :) If foremanctl doesn't notify the users about any previously used configuration, I lean towards thinking that it should. Or, if that's not possible, that we should have a user-friendly way of checking for any currently used auth source.
There was a problem hiding this comment.
Not sure if output of foremanctl is stable enough to do something like we do with the old installer. The following is a bit of a poor man's solution, but it should work.
$ curl -k -u : --negotiate https://foreman.example.com/users/extlogin <html><body>You are being <a href="https://foreman.example.com/users/login">redirected</a>.</body></html>
I was trying to find out what the message looks like when external authentication is not configured (because this is a section on resetting the ext auth source). However, I still got the You are being redirected message. This is on a server that has never had ext auth configured.
So now I wonder what I'm doing wrong. What should the message look like on a system where ext auth has been reset?
There was a problem hiding this comment.
What I really don't like about the current state of foremanctl is that it doesn't show me current configuration. Old satellite-installer --help would show me what arguments are default/last => going to be used if I don't specify them. I think the correct way to resolve this would be to add this functionality to foremanctl.
@ekohl Is this something you could/should define as a feature to be implemented?
However, it's out of scope of this PR. I think it's nice to add the IDM verification procedure as proposed by Adam, especially since such a thing is in the AD section.
No action yet, I'm trying to get more clarification on this (see my previous comment above).
Also, documentation definitely has to specify that AD and IDM are mutually exclusive - I'm surprised it's not there yet. That is IMO also the right place to note that any previous configuration will be overswritten.
Added.
There was a problem hiding this comment.
So now I wonder what I'm doing wrong. What should the message look like on a system where ext auth has been reset?
Nothing, there is no difference between external auth being reset and external auth never being set up in the first place. If external auth is set up, this would either pass and redirect you to /hosts or fail and then you'd get 401. If external auth is not set up (or was reset) you'll get a redirect to the login page (/users/login).
There was a problem hiding this comment.
Oh! I was looking at the verification step for configuring (pre-foremanctl) AD integration and I completely missed that the difference is /users/login vs /hosts! Now I get it, thanks.
There was a problem hiding this comment.
However, it's out of scope of this PR. I think it's nice to add the IDM verification procedure as proposed by Adam, especially since such a thing is in the AD section.
No action yet, I'm trying to get more clarification on this (see my previous comment above).
Added now.
pr-processor
bot
added
the
Waiting on contributor
aneta-petrova
removed
the
Waiting on contributor
| * Username and password | ||
| * Kerberos single sign-on | ||
|
|
||
| ifndef::foremanctl[] |
There was a problem hiding this comment.
Does this mean that these are not available with foremanctl? I think that's not true.
There was a problem hiding this comment.
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
Outdated
Show resolved
Hide resolved
| The attack is possible even if the user did not previously enter the {Project} login credentials anywhere, for example in the browser. | ||
| ==== | ||
| ifndef::foremanctl[] | ||
| . If Hammer is not configured to negotiate authentication, initiate an authentication session manually: |
There was a problem hiding this comment.
Should we leave a guide to setup Hammer manually, in case the user doesn't want to use --add-feature hammer?
There was a problem hiding this comment.
On the docs side, there is a strong preference towards documenting only one way to accomplish a user's goal -- the most user-friendly one. Based on that, my answer would be no. Let me know if I'm missing something.
There was a problem hiding this comment.
Hammer may be installed on non-Satellite hosts. That is, on hosts without foremanctl.
| endif::[] | ||
|
|
||
| ifndef::foremanctl[] | ||
| include::common/modules/ref_overview-of-authentication-methods-in-foreman.adoc[leveloffset=+1] |
There was a problem hiding this comment.
I don't understand changes in this whole file. Does it mean that with foremanctl, we drop many parts of docs including overview? LDAP? Why? Some of those things have nothing to do with either foreman-installer or foremanctl.
There was a problem hiding this comment.
The overview includes procedures, which have not yet been verified for foremanctl. I have now readded it, but only with links to the IPA and AD sections.
LDAP uses foreman-maintain (to restart services). This will also be replaced by foremanctl.
The idea for using the foremanctl conditionals is to start with an empty guide (basically everything hidden behind ifndef::foremanctl[] and then expose the things that we verify in the foremanctl world. That's why this PR starts with hiding everything (okay, that could have been a separate PR... I should probably make sure I don't squash commits when merging), and then re-includes only the things that are related to Kerberos authentication.
There was a problem hiding this comment.
Got it, I didn't know we were this organized with docs migration to foremanctl!
Move reset to its own module Update ext auth reset with additional details
aneta-petrova
force-pushed
the
foremanctl-kerberos-auth
branch
from
b0073ce to
b4e1a67
Compare
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. |
| ---- | ||
| # {foreman-installer} --foreman-pam-service {project-context}-prod | ||
| ifdef::foremanctl[] | ||
| # foremanctl deploy --external-authentication-pam-service foreman-prod |
There was a problem hiding this comment.
--external-authentication-pam-service only makes sense in combination with --external authentication so this part presumes that --external-authentication has been specified previously, otherwise it wouldn't work.
| `foremanctl deploy` | ||
| endif::[] | ||
| ifndef::foremanctl[] | ||
| {foreman-installer} |
There was a problem hiding this comment.
| {foreman-installer} | |
| `{foreman-installer}` |
| <html><body>You are being <a href="_{foreman-example-com}_/hosts">redirected</a>.</body></html> | ||
| ---- | ||
| + | ||
| When external authentication is configured correctly, the `curl` command redirects you to `{foreman-example-com}/hosts`. |
There was a problem hiding this comment.
| When external authentication is configured correctly, the `curl` command redirects you to `{foreman-example-com}/hosts`. | |
| When external authentication is configured correctly, the `curl` command redirects you to `\https://{foreman-example-com}/hosts`. |
The backslash prevents asciidoctor to render a link to the "example.com" domain which does not exist. Similar to:
guides/common/modules/proc_creating-custom-alternate-content-sources-by-using-web-ui.adoc
13:For example, if your base URL is `\https://{server-example-com}` and your subpaths are `rhel10/` and `rhel9/`, then {Project} will search `\https://{server-example-com}/rhel10/` an [... 1 more match]
| <html><body>You are being <a href="https://_{foreman-example-com}_/users/login">redirected</a>.</body></html> | ||
| ---- | ||
| + | ||
| When external authentication is disabled, the `curl` command redirects you to `{foreman-example-com}/users/login`. |
5 participants
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
Please cherry-pick my commits into:
Summary by Sourcery
Update Kerberos SSO and external authentication documentation to cover foremanctl and related workflows.
Documentation: