Skip to content

Commit 8c1014f

Browse files
aneta-petrovaaneta-petrova
committed
Update Kerberos SSO FreeIPA/AD docs for foremanctl
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 <mail@maximilian-kolb.de> 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á <zuansorg@redhat.com> Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de> Move stdout outside of a command block
1 parent 5cecbe9 commit 8c1014f

11 files changed

Lines changed: 152 additions & 25 deletions

‎guides/common/attributes-foremanctl-satellite.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
include::attributes-satellite.adoc[]
2+
3+
:project-package-install: {package-install}

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,18 @@
44
= Configuring Hammer CLI to accept {FreeIPA} credentials
55

66
[role="_abstract"]
7+
ifndef::foremanctl[]
78
To enable users to authenticate to the Hammer CLI by using their {FreeIPA} credentials, update Hammer configuration.
9+
endif::[]
10+
ifdef::foremanctl[]
11+
If you want to enable users to authenticate to the Hammer CLI by using their {FreeIPA} credentials from a system with standalone Hammer installed, update Hammer configuration on that system.
12+
13+
[NOTE]
14+
====
15+
Updating Hammer configuration manually is not required on systems that have been configured with `foremanctl`.
16+
Running `foremanctl --add-feature hammer` updates the Hammer configuration as necessary.
17+
====
18+
endif::[]
819

920
.Prerequisites
1021
* You have enabled {FreeIPA} access to the {Project} API.

‎guides/common/modules/proc_configuring-host-based-access-control-for-freeipa-users-logging-in-to-project.adoc‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ By configuring a HBAC rule in the {FreeIPA} domain, you can ensure {Project} doe
1212

1313
.Prerequisites
1414
* {FreeIPA} user account with privileges to configure HBAC rules
15+
ifdef::foremanctl[]
16+
* You have enabled {FreeIPA} as external authentication source on your {ProjectServer}.
17+
For more information, see xref:configuring-the-freeipa-authentication-source-on-projectserver_{context}[].
18+
endif::[]
1519

1620
.Procedure
1721
. On the {FreeIPA} server, configure HBAC control.
@@ -32,7 +36,12 @@ endif::[]
3236
+
3337
[options="nowrap", subs="+quotes,verbatim,attributes"]
3438
----
39+
ifdef::foremanctl[]
40+
# foremanctl deploy --external-authentication-pam-service foreman-prod
41+
endif::[]
42+
ifndef::foremanctl[]
3543
# {foreman-installer} --foreman-pam-service foreman-prod
44+
endif::[]
3645
----
3746

3847
.Verification
@@ -109,10 +118,22 @@ $ ipa hbactest --user=_ipa-user_ --host=_{foreman-example-com}_ --service={proje
109118
$ ipa hbacrule-disable allow_all
110119
----
111120
112-
On {ProjectServer}, a {Project} administrator re-runs {foreman-installer} to load the host-based access control rules from {FreeIPA}:
121+
On {ProjectServer}, a {Project} administrator re-runs
122+
ifdef::foremanctl[]
123+
`foremanctl deploy`
124+
endif::[]
125+
ifndef::foremanctl[]
126+
`{foreman-installer}`
127+
endif::[]
128+
to load the host-based access control rules from {FreeIPA}:
113129
114130
[options="nowrap", subs="+quotes,verbatim,attributes"]
115131
----
116-
# {foreman-installer} --foreman-pam-service {project-context}-prod
132+
ifdef::foremanctl[]
133+
# foremanctl deploy --external-authentication-pam-service foreman-prod
134+
endif::[]
135+
ifndef::foremanctl[]
136+
# {foreman-installer} --foreman-pam-service foreman-prod
137+
endif::[]
117138
----
118139
====

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

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ For more information on direct AD integration, see link:https://docs.redhat.com/
2929
endif::[]
3030

3131
.Procedure
32-
. Define AD realm configuration in a location where {foreman-installer} expects it:
32+
. Define AD realm configuration in a location where {Project} expects it:
3333
.. Create a directory named `/etc/ipa/`:
3434
+
3535
[options="nowrap", subs="+quotes,verbatim,attributes"]
@@ -103,7 +103,12 @@ Without the option, AD users are unable to use `kinit` to authenticate to {Proje
103103
+
104104
[options="nowrap", subs="+quotes,verbatim,attributes"]
105105
----
106+
ifdef::foremanctl[]
107+
# foremanctl deploy --external-authentication ipa
108+
endif::[]
109+
ifndef::foremanctl[]
106110
# {foreman-installer} --foreman-ipa-authentication true
111+
endif::[]
107112
----
108113

109114
.Verification
@@ -120,10 +125,16 @@ $ kinit _ad_user_@_AD.EXAMPLE.COM_
120125
+
121126
[options="nowrap", subs="+quotes,verbatim,attributes"]
122127
----
123-
$ curl -k -u : --negotiate https://{foreman-example-com}/users/extlogin
124-
125-
<html><body>You are being <a href="{foreman-example-com}/hosts">redirected</a>.</body></html>
128+
$ curl -k -u : --negotiate https://_{foreman-example-com}_/users/extlogin
126129
----
130+
+
131+
If external authentication is configured correctly, the `curl` command redirects you to `\https://{foreman-example-com}/hosts`:
132+
+
133+
[options="nowrap", subs="+quotes,verbatim,attributes"]
134+
----
135+
<html><body>You are being <a href="_{foreman-example-com}_/hosts">redirected</a>.</body></html>
136+
----
137+
127138

128139
.Troubleshooting
129140
* Connecting to the AD LDAP can sometimes fail with an error such as the following appearing in the logs:
@@ -151,7 +162,8 @@ ifdef::foreman-el,katello[]
151162
For information on configuring system-wide cryptographic policies, see link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening[Using system-wide cryptographic policies] in _{RHEL}{nbsp}9 Security hardening_.
152163
endif::[]
153164

154-
ifndef::orcharhino[]
155165
.Additional resources
166+
ifndef::orcharhino[]
156167
* https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_authentication_and_authorization_in_rhel/configuring_applications_for_sso#Configuring_Firefox_to_use_Kerberos_for_SSO[Configuring Firefox to use Kerberos for single sign-on in _{RHEL}{nbsp}9 Configuring authentication and authorization in RHEL_]
157168
endif::[]
169+
* xref:resetting-external-authentication-configuration-for-kerberos-sso[]

‎guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
[role="_abstract"]
77
Connect your {ProjectServer} to your {FreeIPA} domain by configuring {FreeIPA} as an authentication provider on your {ProjectServer}.
88

9+
include::snip_ext-auth-mutually-exclusive.adoc[]
10+
911
.Prerequisites
1012
* {ProjectServer} running on a system that is enrolled in the {FreeIPA} domain.
1113

@@ -15,16 +17,26 @@ Connect your {ProjectServer} to your {FreeIPA} domain by configuring {FreeIPA} a
1517
+
1618
[options="nowrap", subs="+quotes,verbatim,attributes"]
1719
----
20+
ifdef::foremanctl[]
21+
# foremanctl deploy --external-authentication ipa
22+
endif::[]
23+
ifndef::foremanctl[]
1824
# {foreman-installer} \
1925
--foreman-ipa-authentication true
26+
endif::[]
2027
----
2128
* To enable access to the {ProjectWebUI} and the {Project} API, including Hammer CLI:
2229
+
2330
[options="nowrap", subs="+quotes,verbatim,attributes"]
2431
----
32+
ifdef::foremanctl[]
33+
# foremanctl deploy --external-authentication ipa_with_api
34+
endif::[]
35+
ifndef::foremanctl[]
2536
# {foreman-installer} \
2637
--foreman-ipa-authentication-api true \
2738
--foreman-ipa-authentication true
39+
endif::[]
2840
----
2941
+
3042
[WARNING]
@@ -33,13 +45,6 @@ Enabling access to both the {ProjectWebUI} and the {Project} API poses a securit
3345
After the {FreeIPA} user enters `kinit` to receive a Kerberos ticket-granting ticket (TGT), an attacker might obtain an API session.
3446
The attack is possible even if the user did not previously enter the {Project} login credentials anywhere, for example in the browser.
3547
====
36-
* To disable external authentication with {FreeIPA}, reset the options.
37-
For example, to disable access to the {Project} API and Hammer CLI:
38-
+
39-
[options="nowrap", subs="+quotes,verbatim,attributes"]
40-
----
41-
# {foreman-installer} --reset-foreman-ipa-authentication-api
42-
----
4348
. If your {ProjectServer} runs in an IPv6-only network and also runs on {EL}{nbsp}9.6 and earlier or {EL}{nbsp}10.0, set the `lookup_family_order` option in the `[domain/_{freeipaserver-example-com}_]` section of the `/etc/sssd/sssd.conf` file:
4449
+
4550
[source, ini, options="nowrap", subs="+quotes,verbatim,attributes"]
@@ -54,3 +59,6 @@ Without the option, IdM users are unable to use `kinit` to authenticate to {Proj
5459

5560
.Verification
5661
* Log in to {ProjectWebUI} by entering the credentials of a user defined in {FreeIPA}.
62+
63+
.Additional resources
64+
* xref:resetting-external-authentication-configuration-for-kerberos-sso[]

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,6 @@ ifndef::orcharhino[]
3030
For more information, see link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux//9/html-single/installing_identity_management/index#assembly_installing-an-idm-client_installing-identity-management[{RHEL}{nbsp}9 Installing Identity Management].
3131
endif::[]
3232
ifdef::foreman-deb[]
33-
+
3433
. Ensure that the hostname is set to the fully qualified domain name (FQDN); the short name is not sufficient:
3534
+
3635
[options="nowrap", subs="+quotes,verbatim,attributes"]

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

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,11 @@
66
[role="_abstract"]
77
Authenticate to the {Project} Hammer CLI with your {FreeIPA} username and password.
88

9+
ifndef::foremanctl[]
910
.Prerequisites
1011
* You have configured Hammer CLI to accept {FreeIPA} credentials.
11-
ifeval::["{context}" == "{project-context}"]
1212
See xref:configuring-hammer-cli-to-accept-{FreeIPA-context}-credentials_{context}[].
1313
endif::[]
14-
ifeval::["{context}" != "{project-context}"]
15-
ifndef::orcharhino[]
16-
For more information, see {InstallingServerDocURL}configuring-hammer-cli-to-accept-{FreeIPA-context}-credentials_{context}[Configuring Hammer CLI to accept {FreeIPA} credentials] in _{InstallingServerDocTitle}_.
17-
endif::[]
18-
endif::[]
1914

2015
.Procedure
2116
. Authenticate as a user defined in {FreeIPA} to obtain a Kerberos ticket-granting ticket (TGT):

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="resetting-external-authentication-configuration-for-kerberos-sso"]
4+
= Resetting external authentication configuration for Kerberos SSO
5+
6+
[role="_abstract"]
7+
You can disable external authentication with {FreeIPA} or Active Directory (AD) by resetting the configuration for the `IPA` authentication type.
8+
This prevents user accounts defined in the external authentication source from accessing {Project}.
9+
10+
[IMPORTANT]
11+
====
12+
Resetting external authentication prevents users from accessing {Project} with Kerberos single sign-on (SSO).
13+
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.
14+
====
15+
16+
.Procedure
17+
* Reset the external authentication configuration to the default state:
18+
ifdef::foremanctl[]
19+
+
20+
[options="nowrap", subs="+quotes,verbatim,attributes"]
21+
----
22+
# foremanctl deploy --reset-external-authentication
23+
----
24+
endif::[]
25+
ifndef::foremanctl[]
26+
** To disable access to {ProjectWebUI}:
27+
+
28+
[options="nowrap", subs="+quotes,verbatim,attributes"]
29+
----
30+
# {foreman-installer} --reset-foreman-ipa-authentication
31+
----
32+
** To disable access to {ProjectWebUI}, {Project} API, and Hammer CLI:
33+
+
34+
[options="nowrap", subs="+quotes,verbatim,attributes"]
35+
----
36+
# {foreman-installer} --reset-foreman-ipa-authentication-api
37+
----
38+
endif::[]
39+
40+
.Verification
41+
ifdef::foremanctl[]
42+
* Verify your external authentication configuration:
43+
+
44+
[options="nowrap", subs="+quotes,verbatim,attributes"]
45+
----
46+
$ curl -k -u : --negotiate https://_{foreman-example-com}_/users/extlogin
47+
----
48+
+
49+
If external authentication is disabled, the `curl` command redirects you to `\https://{foreman-example-com}/users/login`.
50+
+
51+
[options="nowrap", subs="+quotes,verbatim,attributes"]
52+
----
53+
<html><body>You are being <a href="https://_{foreman-example-com}_/users/login">redirected</a>.</body></html>
54+
----
55+
endif::[]
56+
ifndef::foremanctl[]
57+
* Display the value for the `foreman-ipa-authentication` and `foreman-ipa-authentication-api` configuration options:
58+
+
59+
[options="nowrap", subs="+quotes,verbatim,attributes"]
60+
----
61+
# {foreman-installer} --help | grep foreman-ipa-authentication
62+
----
63+
+
64+
The expected value for disabled external authentication is `false`.
65+
endif::[]

‎guides/common/modules/snip_ext-auth-mutually-exclusive.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[NOTE]
2+
====
3+
The {FreeIPA} and Active{nbsp}Directory authentication sources are mutually exclusive.
4+
Running
5+
ifdef::foremanctl[]
6+
`foremanctl deploy --external-authentication`
7+
endif::[]
8+
ifndef::foremanctl[]
9+
`{foreman-installer} --foreman-ipa-authentication` or `{foreman-installer} --foreman-ipa-authentication-api`
10+
endif::[]
11+
overwrites any previously defined configuration for these authentication sources.
12+
====

‎guides/common/modules/snip_table-authentication-methods.adoc‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,24 +71,26 @@ ifndef::satellite[]
7171
|No
7272
endif::[]
7373
|xref:configuring-kerberos-sso-with-{FreeIPA-context}-in-{project-context}[]
74-
ifndef::foreman-deb,satellite[]
74+
ifndef::foremanctl,foreman-deb,satellite[]
7575
|{Keycloak-quarkus}|Yes|Yes|Yes|Yes
7676
ifndef::satellite[]
7777
|Yes
7878
endif::[]
7979
|xref:configuring-sso-and-2fa-with-keycloak-wildfly-in-project_keycloak-wildfly[]
8080
endif::[]
81-
ifndef::foreman-deb[]
81+
ifndef::foremanctl,foreman-deb[]
8282
|{Keycloak-wildfly}|Yes|Yes|Yes|Yes
8383
ifndef::satellite[]
8484
|Yes
8585
endif::[]
8686
|xref:configuring-sso-and-2fa-with-keycloak-wildfly-in-project_keycloak-wildfly[]
8787
endif::[]
88+
ifndef::foremanctl[]
8889
|LDAP|Yes|No|No|No
8990
ifndef::satellite[]
9091
|No
9192
endif::[]
9293
|xref:configuring-an-ldap-server-as-an-external-identity-provider-for-project_{context}[]
94+
endif::[]
9395
|====
9496
endif::[]

0 commit comments

Comments
 (0)