Feature #30174
open
Improve SSO docs
Description
The current SSO docs fall short in many ways:
The Manual calls it "External Authentication", but in the source everything appears to be called SSO. This makes finding the docs harder than necessary.
The manual for External Authentication is written in a style of multiple concatenated tutorials. It does not seem to clearly explain which options for SSO exist, which assumptions Foreman makes for each SSO option, or the detailed configuration settings for them.
Generally it seems to follow a "Do X, Y, Z, and then magic happens" pattern. This makes the documentation very hard to consume, especially when trying to do something different from the tutorials (ex: integrating a different SSO source, which might be compatible with existing support in Foreman).
Section "5.7.5 Populate users and attributes" appears to have formatting issues. Also it somewhat shows which REMOTE_xxx variables Foreman understands, but with no explanation whatsoever.
IMO, the docs for SSO should explain:
- Which technologies Foreman supports for external auth
- Which settings are available for each (not just "in the installer, its this parameter")
- Known good providers
Thanks!
Updated by Melanie Corr about 4 years ago
Does the following chapter go any way to addressing the issues raised here:
PS: I have filed an issue with the docs team with the tech preview still appearing upstream.
Updated by Chris Hofstaedtler about 4 years ago
Melanie Corr wrote:
Does the following chapter go any way to addressing the issues raised here:
I find this still to be extremely confusing; it's again in tutorial form. Also it talks a lot about "local" user accounts and /etc/passwd and none of that seems to matter at all in Foreman 1.24, so I don't understand why this is in the docs?
There's no mention of REMOTE_USER etc, too.
All these docs seem to be written for two narrow use cases: Active Directory, or Keycloak. If one wants to do something else, they don't help at all.
Updated by Rahul Bajaj about 4 years ago
Chris Hofstaedtler wrote:
Melanie Corr wrote:
Does the following chapter go any way to addressing the issues raised here:
I find this still to be extremely confusing; it's again in tutorial form. Also it talks a lot about "local" user accounts and /etc/passwd and none of that seems to matter at all in Foreman 1.24, so I don't understand why this is in the docs?
I agree, I need to put some more efforts to explain it in a better way :)
There's no mention of REMOTE_USER etc, too.
Yes, give me some time, I will try to open a PR and explain things in a much detailed manner.
All these docs seem to be written for two narrow use cases: Active Directory, or Keycloak. If one wants to do something else, they don't help at all.
I have not mentioned Active Directory afaik but you are correct, I have tested the entire scenario for Keycloak. Although, I have implemented the feature according to the respective specs, therefore, I think it should work for other providers like Auth0 too (haven't tested it though).
Updated by Rahul Bajaj about 4 years ago
I am actually a little confused too. Because the setup for this feature is a little heavy (in the sense there are more number of steps). Since this feature involves both settings on the keycloak (OpenID provider) side and also on the Foreman server side. If you are using Hammer, it also needs separate settings.
I think a few screen shots would be of great help, so I am going to add them as well.