Realm procedure has redundant steps

[ekohl]

I'm looking at the realm procedure:

foreman-documentation/guides/common/modules/con_configuring-project-to-manage-the-lifecycle-of-a-host-registered-to-a-freeipa-realm.adoc

Lines 65 to 83 in 3259af8

	+
	You can also use these options when you first configure the {ProjectServer}.
	. Ensure that the most updated versions of the ca-certificates package is installed and trust the {FreeIPA} Certificate Authority:
	+
	[options="nowrap", subs="+quotes,verbatim,attributes"]
	----
	# cp /etc/ipa/ca.crt /etc/pki/ca-trust/source/anchors/ipa.crt
	# update-ca-trust enable
	# update-ca-trust
	----
	. Optional: If you configure {FreeIPA} on an existing {ProjectServer} or {SmartProxyServer}, complete the following steps to ensure that the configuration changes take effect:
	.. Restart the *foreman-proxy* service:
	+
	[options="nowrap", subs="+quotes,verbatim,attributes"]
	----
	# systemctl restart foreman-proxy
	----
	.. In the {ProjectWebUI}, navigate to *Infrastructure* > *{SmartProxies}*.
	.. Locate the {SmartProxy} you have configured for {FreeIPA} and from the list in the *Actions* column, select *Refresh*.

Here I have two questions.

Why does it need to trust the CA certificate in this way? I'd imagine it's either required by the installer already so it should happen before the installer command. I'd also wonder if ipa-client-install doesn't already do this.

The second part shouldn't be needed. The installer refreshes all features of the Foreman Proxy and restart the service as needed. It may have been needed in the past or if the CA hadn't been trusted, but if that's needed you should do it prior to running the installer.

Some references:

• ipa-client-install comes from the ipa-client package, included in EL. On Debian this is shipped in the freeipa-client package.
• foreman-prepare-realm is https://github.com/theforeman/smart-proxy/blob/develop/sbin/foreman-prepare-realm
• foreman-prepare-realm writes out freeipa.keytab in the current working directory. The documentation assumes it's in /root/freeipa.keytab but if the user isn't in /root then that assumption is false
• The smart-proxy module uses HTTPS with GSSAPI and can only use the system trust store. It doesn't have a configuration option to use an explicit path: https://github.com/theforeman/smart-proxy/blob/develop/modules/realm_freeipa/provider.rb

[ekohl]

Another thing: I just noted we have 3 places where we configure IPA enrollment:

$ rg ipa-client
guides/common/modules/con_configuring-project-with-external-idm-dns.adoc
26:When you are using the realm enrollment feature of {Project}, where provisioned hosts are enrolled automatically to IdM, the `ipa-client-install` script creates DNS records for the client.

guides/common/modules/con_configuring-project-to-manage-the-lifecycle-of-a-host-registered-to-a-freeipa-realm.adoc
17:. Install the `ipa-client` package on {ProjectServer} or {SmartProxyServer}:
21:# {project-package-install} ipa-client
27:# ipa-client-install

guides/common/modules/proc_configuring-dynamic-dns-update-with-gss-tsig-authentication.adoc
47:. On the base operating system of either the {Project} or {SmartProxy} that is managing the DNS service for your deployment, install the `ipa-client` package:
51:# {project-package-install} ipa-client
58:# ipa-client-install

guides/common/modules/proc_configuring-freeipa-authentication-on-server.adoc
56:# {project-package-install} ipa-client
62:# ipa-client-install --password _OTP_

It's all slightly different. I can also imagine we want to somehow make this more consistent, possibly also improve it on the engineering side.

[asteflova]

The steps you mention might be inconsistent because FreeIPA/Identity Management (IdM) supports multiple ways for installing a client: manual, automated, OTP, ... Users can also deploy an IdM server itself in multiple configurations based on their environment (integrated CA, external CA, probably others...) which might also affect the exact step to install a client.

In addition to all that, even more important is that installing a FreeIPA/IdM client is not just about running ipa-client-install. There are certain prerequisites and considerations -- those are described in the IdM docs.

And yes, the behavior of ipa-client-install itself has also changed over the years and -- quite understandably -- noone on the Foreman docs team can be expected to keep up with the development of another product.

In my opinion, the solution is not to make the IdM client installation steps consistent on the Foreman docs side. I think we should avoid calling ipa-client-install (or ipa-server-install for that matter) explicitly in Foreman docs.

A related issue is that the current procedures documented on the Foreman side can work well as testing procedures, but not as something we can confidently recommend users to do. In #3015, I'm exploring ways for redirecting users to the IdM documentation for the full process while keeping the simplified testing procedure in an example box. I'm working with the IdM team to review and test these changes. If it eventually gets merged like this, it might help with updating the realm procedure too.

BTW, I'm seeing similar issues in the other procedures for external authentication too (Active Directory, Keycloak). I have PRs opened for all of these too, but admittedly, the progress has been slow because cross-product scenarios are difficult to test and coordinate with the other teams.

[ekohl]

The reason I looked at this was that @Griffin-Sullivan was asking about the realm feature.

There are also other aspects that I think are questionable. For example, sharing the keytab between multiple machines doesn't sound like a good practice. To me it's always better if every machine has its own identity so that you can be sure about its lifecycle. If it gets compromised, only a single thing to rotate. If the machine is decomissioned, you're sure it can be removed.

But you're right, it needs someone with cross-product experience to weigh in.