1. Overview of authentication methods in Foreman
The authentication methods you can configure depend on the authentication source you are using. If the native authentication features provided by Foreman are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements.
Foreman includes native support for authentication with a username and password. If you require additional methods of authentication, configure your Foreman server to use an external authentication source.
| Username and password | Single sign-on (SSO) | One-time password (OTP) | Time-based one-time password (TOTP) | PIV cards | Additional details | |
|---|---|---|---|---|---|---|
Active Directory (direct integration) |
Yes |
Yes |
No |
No |
No |
Configuring Kerberos SSO for Active Directory users in Foreman |
FreeIPA |
Yes (Linux and Active Directory users) |
Yes (Linux users only) |
No |
No |
No |
2. Accessing Foreman from Foreman web UI
After Foreman has been installed and configured, you can use a browser to log in to the Foreman web UI.
2.1. Logging in to the Foreman web UI
The Foreman web UI is a browser-based user interface that you can use to manage and monitor your Foreman infrastructure. To access Foreman web UI, use your web browser to navigate to the Foreman web UI login page and enter your credentials.
-
Ensure that the Katello root CA certificate is installed in your browser. For more information, see Importing the Katello root CA certificate using Foreman web UI.
-
Access Foreman server using a web browser pointed to the fully qualified domain name:
https://foreman.example.com/
-
Enter the user name and password created during the configuration process. If a user was not created during the configuration process, the default user name is admin.
-
If you have problems logging in, you can reset the password. For more information, see Resetting the administrative user password.
2.2. Importing the Katello root CA certificate using Foreman web UI
After the first login to Foreman web UI, you might see a warning that you are using the default self-signed certificate. To ensure a successful connection, locate the root CA certificate on Foreman and import it into your browser truststore.
-
Your Foreman is installed and configured.
-
Identify the fully qualified domain name of your Foreman server:
# hostname -f
-
Access the
pubdirectory on your Foreman server using a web browser pointed to the fully qualified domain name:https://foreman.example.com/pub
-
When you access Foreman for the first time, an untrusted connection warning displays in your web browser. Accept the self-signed certificate and add the Foreman URL as a security exception to override the settings. This procedure might differ depending on the browser being used. Ensure that the Foreman URL is valid before you accept the security exception.
-
Select
katello-server-ca.crt. -
Import the certificate into your browser as a certificate authority and trust it to identify websites.
2.3. Importing the Katello root CA certificate using CLI
After the first login to Foreman web UI, you might see a warning that you are using the default self-signed certificate. To ensure a successful connection, locate the root CA certificate on Foreman and import it into your browser truststore.
-
Your Foreman is installed and configured.
-
On your Foreman server, copy the
katello-server-ca.crtfile to the machine you use to access the Foreman web UI:# scp /var/www/html/pub/katello-server-ca.crt username@hostname:remotefile
-
In the browser, import the
katello-server-ca.crtcertificate as a certificate authority and trust it to identify websites.
2.4. Resetting the administrative user password
You can reset the administrative password to randomly generated characters or set a new administrative password for a specific user. This might be useful when you forget the password, when the administrative user is deleted, or for assigning administrative privileges to a user.
-
Log in to the base operating system where your Foreman server is installed.
-
Reset the administrative user password:
-
To set a randomly generated administrative user password:
# foreman-rake permissions:reset Reset to user: admin, password: qwJxBptxb7Gfcjj5
-
To set a new administrative user password:
# foreman-rake permissions:reset username=My_User_Name password=My_New_Password
Replace
My_User_Namewith the username of the user whose password you want to reset.NoteBe aware of the following behaviors:
-
If you enter a username that does not exist, the
foreman-rakeutility creates a new administrative user with the defined password. -
If you enter a username of a user without administrative privileges, that user gains administrative privileges.
-
If you do not enter a username, the password resets for the
adminuser by default.
-
-
-
To use the new password with the Hammer CLI, add the password and username to the
~/.hammer/cli.modules.d/foreman.ymlfile on your Foreman server:# vi ~/.hammer/cli.modules.d/foreman.yml
-
Use the new password to log in to the Foreman web UI.
2.5. Setting a custom message on the Foreman web UI login page
You can change the default text on the login page to a custom message you want your users to see every time they access the page. For example, your custom message might be a warning required by your company.
-
In the Foreman web UI, navigate to Administer > Settings.
-
Select the General tab.
-
Enter your custom message in the Login page footer text field.
-
Click Submit.
-
Log out of the Foreman web UI and verify that the custom message is now displayed on the login page.
3. Configuring Kerberos SSO with FreeIPA in Foreman
FreeIPA is an open-source identity management solution that provides centralized authentication, authorization, and account management services. You can integrate Foreman with your existing FreeIPA server to enable FreeIPA users to authenticate to Foreman.
With your FreeIPA server configured as an external identity provider, users defined in FreeIPA can log in to Foreman with their FreeIPA credentials. If cross-forest trust is configured between FreeIPA and Active Directory, Active Directory users can also log in to Foreman.
FreeIPA users can log in using the following methods:
-
Username and password
-
Kerberos single sign-on
When cross-forest trust is configured between FreeIPA and Active Directory, Active Directory users can log in to Foreman with their user principal name (UPN) and password.
For information about FreeIPA, including its cross-forest trust functionality, see Red Hat Enterprise Linux 9 Planning Identity Management and Red Hat Enterprise Linux 9 Installing Identity Management.
3.1. Enrolling Foreman server in your FreeIPA domain
Create a host entry for your Foreman server system in the FreeIPA LDAP and configure the system to be a client in your FreeIPA domain.
-
An existing FreeIPA server
-
FreeIPA user account with privileges to enroll new FreeIPA hosts
-
On the FreeIPA server:
-
Create a host entry for the Foreman server system.
For more information, see Red Hat Enterprise Linux 9 Managing IdM users, groups, hosts, and access control rules.
-
Create an entry for the HTTP service for Foreman server. This enables access to the keytab file by creating a service principal for your Foreman server.
For more information on creating a service entry in FreeIPA, see Red Hat Enterprise Linux 9 Managing IdM users, groups, hosts, and access control rules.
-
-
On your Foreman server, configure the system as client in the FreeIPA domain. This includes ensuring that the system meets the necessary prerequisites, installing the necessary packages, and running the
ipa-client-installutility.For more information, see Red Hat Enterprise Linux 9 Installing Identity Management.
-
On your Foreman server, check that you are able to resolve a user defined on the FreeIPA server. For example, to check the
adminuser that FreeIPA creates by default:$ id admin
On the FreeIPA server, a user named admin who has administrative privileges on the FreeIPA server prepares a host entry for the Foreman server system:
-
Authenticate as the FreeIPA admin user:
# kinit admin
-
Optional: Verify that you have authenticated successfully:
# klist
-
Create a host entry from the command line. Specify that you want to use a random password for the enrollment.
# ipa host-add --random foreman-server.example.com -------------------------------------------------- Added host "foreman-server.example.com" -------------------------------------------------- Host name: foreman-server.example.com Random password: W5YpARl=7M.n Password: True Keytab: False Managed by: freeipa-server.example.com
-
Enable access to the keytab file by creating a service principal for your Foreman server:
# ipa service-add HTTP/foreman-server.example.com
On the Foreman server system, a user with Foreman administrative privileges enrolls the system into the FreeIPA domain:
-
Install the FreeIPA client packages:
# dnf install ipa-client
-
Configure the Foreman server system a client in FreeIPA by using the random password produced by
ipa host-addin a previous step:# ipa-client-install --password 'W5YpARl=7M.n'
-
Verify that you are able to resolve the FreeIPA
adminuser from your Foreman server:$ id admin
3.2. Configuring the FreeIPA authentication source on Foreman server
Connect your Foreman server to your FreeIPA domain by configuring FreeIPA as an authentication provider on your Foreman server.
|
Note
|
The FreeIPA and Active Directory authentication sources are mutually exclusive.
Running
|
-
Foreman server running on a system that is enrolled in the FreeIPA domain.
-
Enable access for your preferred login method:
-
To enable access to the Foreman web UI only:
# foremanctl deploy --external-authentication ipa
-
To enable access to the Foreman web UI and the Foreman API, including Hammer CLI:
# foremanctl deploy --external-authentication ipa_with_api
WarningEnabling access to both the Foreman web UI and the Foreman API poses a security risk. After the FreeIPA user enters
kinitto receive a Kerberos ticket-granting ticket (TGT), an attacker might obtain an API session. The attack is possible even if the user did not previously enter the Foreman login credentials anywhere, for example in the browser.
-
-
If your Foreman server runs in an IPv6-only network and also runs on Enterprise Linux 9.6 and earlier or Enterprise Linux 10.0, set the
lookup_family_orderoption in the[domain/freeipa-server.example.com]section of the/etc/sssd/sssd.conffile:[domain/freeipa-server.example.com] lookup_family_order = ipv6_onlyIf the DNS name of the IdM server can be translated to both an IPv4 and IPv6 address but the IPv4 address is not accessible, SSSD requires
lookup_family_orderto translate the DNS name correctly. Without the option, IdM users are unable to usekinitto authenticate to Foreman.
-
Log in to Foreman web UI by entering the credentials of a user defined in FreeIPA.
3.3. Configuring host-based access control for FreeIPA users logging in to Foreman
You can use host-based access control (HBAC) rules to manage access control within your FreeIPA domain. In FreeIPA, HBAC rules define which users can access which hosts and which services can be used to gain access.
For example, you can configure HBAC on the FreeIPA server to limit access to Foreman server only to selected users or user groups. By configuring a HBAC rule in the FreeIPA domain, you can ensure Foreman does not create database entries for users who should not have access.
-
FreeIPA user account with privileges to configure HBAC rules
-
You have enabled FreeIPA as external authentication source on your Foreman server. For more information, see Configuring the FreeIPA authentication source on Foreman server.
-
On the FreeIPA server, configure HBAC control. For more information, see Red Hat Enterprise Linux 9 Managing IdM users, groups, hosts, and access control rules.
-
Create a HBAC service for Foreman server.
-
Create a new HBAC rule to define the required access control. Add the following FreeIPA entities to the HBAC rule:
-
The HBAC service for Foreman server
-
The Foreman server host
-
The users or user groups to whom you want to grant access
-
-
Make sure the default FreeIPA
allow_allrule is disabled.
-
-
On your Foreman server, load the host-based access control rules from FreeIPA:
# foremanctl deploy --external-authentication-pam-service foreman-prod
-
Log in to the Foreman web UI as a user defined in FreeIPA.
-
If the user is included in the HBAC rule, Foreman web UI will grant access.
-
If the user is not included in the HBAC rule, Foreman web UI will not grant access.
-
On the FreeIPA server, a user with administrative privileges configures a HBAC rule to allow selected users access to Foreman server:
-
Authenticate as the user with privileges required to configure HBAC rules:
$ kinit admin
-
Optional: Verify that you have authenticated successfully:
$ klist
-
Create a new HBAC service named
foreman-prod:$ ipa hbacsvc-add foreman-prod
-
Create a new HBAC rule:
$ ipa hbacrule-add allow-foreman-prod
-
Add the following FreeIPA entities to the HBAC rule:
-
The
foreman-prodHBAC service:$ ipa hbacrule-add-service allow-foreman-prod --hbacsvcs=foreman-prod
-
The Foreman server host:
$ ipa hbacrule-add-host allow-foreman-prod --hosts=foreman.example.com
-
The users or user groups to whom you want to grant access:
$ ipa hbacrule-add-user allow-foreman-prod --user=ipa-user
-
-
Optional: Verify the status of the rule:
$ ipa hbacrule-find foreman-prod $ ipa hbactest --user=ipa-user --host=foreman.example.com --service=foreman-prod
-
Disable the default
allow_allrule:
$ ipa hbacrule-disable allow_all
On Foreman server, a Foreman administrator re-runs
foremanctl deploy
to load the host-based access control rules from FreeIPA:
# foremanctl deploy --external-authentication-pam-service foreman-prod
3.4. Configuring Hammer CLI to accept FreeIPA credentials
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.
|
Note
|
Updating Hammer configuration manually is not required on systems that have been configured with |
-
You have enabled FreeIPA access to the Foreman API. For more information, see Configuring the FreeIPA authentication source on Foreman server.
-
Open the
~/.hammer/cli.modules.d/foreman.ymlfile on your Foreman server and update the list offoremanparameters:-
To enforce session usage, enable
:use_sessions:::foreman: :use_sessions: trueWith this configuration, you will need to initiate an authentication session manually with
hammer auth login negotiate. -
Alternatively, to enforce session usage and also negotiate authentication by default:
:foreman: :default_auth_type: 'Negotiate_Auth' :use_sessions: trueWith this configuration, Hammer will negotiate authentication automatically when you enter the first
hammercommand.
-
3.5. Logging in to Hammer CLI with FreeIPA credentials
Authenticate to the Foreman Hammer CLI with your FreeIPA username and password.
-
Authenticate as a user defined in FreeIPA to obtain a Kerberos ticket-granting ticket (TGT):
$ kinit FreeIPA_user
WarningIf you enabled access to the Foreman API and the Foreman web UI when you were configuring FreeIPA as the authentication provider for Foreman, an attacker might now obtain an API session after the user receives the Kerberos TGT. The attack is possible even if the user did not previously enter the Foreman login credentials anywhere, for example in the browser.
-
If Hammer is not configured to negotiate authentication, initiate an authentication session manually:
$ hammer auth login negotiate
NoteIf you destroy the active Kerberos ticket, for example with
kdestroy, you will still be logged in to Hammer. To log out, enterhammer auth logout.
-
Use any
hammercommand to check that the system does not ask you to authenticate. For example:$ hammer host list
3.6. Logging in to the Foreman web UI with FreeIPA credentials in Mozilla Firefox
Users with valid FreeIPA login credentials can log in to the Foreman web UI from the Mozilla Firefox browser.
Use the latest stable Mozilla Firefox browser.
-
You have FreeIPA authentication configured in your Foreman environment. For more information, see Configuring Kerberos SSO with FreeIPA in Foreman.
-
The host on which you are using Mozilla Firefox is a client in the FreeIPA domain.
-
Your Mozilla Firefox is configured for Single Sign-On (SSO).
-
To log in with a Kerberos ticket granting ticket (TGT):
-
Obtain the Kerberos TGT:
$ kinit user Password for user@EXAMPLE.COM:
-
In Mozilla Firefox, go to the URL of your Foreman server.
-
You are logged in automatically.
-
-
To log in with your username and password:
-
In your browser address bar, enter the URL of your Foreman server.
-
Enter your username and password.
-
3.7. Logging in to the Foreman web UI with FreeIPA credentials in Chrome
Users with valid FreeIPA login credentials can log in to the Foreman web UI from the Chrome browser.
Use the latest stable Chrome browser.
-
You have FreeIPA authentication configured in your Foreman environment. For more information, see Configuring Kerberos SSO with FreeIPA in Foreman.
-
The host on which you are using Chrome is a client in the FreeIPA domain.
-
To use Kerberos authentication to log in:
-
Enable the Chrome browser to use Kerberos authentication:
$ google-chrome --auth-server-whitelist="*.example.com" --auth-negotiate-delegate-whitelist="*.example.com"
NoteInstead of allowlisting the whole domain, you can also allowlist a specific Foreman server.
-
Obtain the Kerberos ticket-granting ticket (TGT):
$ kinit user Password for user@EXAMPLE.COM:
-
In Chrome, go to the URL of your Foreman server.
-
You are logged in automatically.
-
-
To use username and password to log in:
-
In your browser address bar, enter the URL of your Foreman server.
-
Enter your username and password.
-
3.8. Configuring a cross-forest trust between FreeIPA and Active Directory for Foreman
If your FreeIPA deployment includes a cross-forest trust with Active Directory (AD), you must configure host-based access control (HBAC) and the System Security Services Daemon (SSSD) before AD users can log in to Foreman.
-
An existing FreeIPA server with a cross-forest trust with AD established. For more information, see Red Hat Enterprise Linux 9 Installing trust between IdM and AD.
-
On your FreeIPA server:
-
Enable HBAC:
-
Create an external group and add the AD group to it.
-
Add the new external group to a POSIX group.
-
Use the POSIX group in a HBAC rule.
-
-
-
On your FreeIPA server and all replicas in your FreeIPA topology, configure SSSD to transfer additional attributes of AD users:
-
Add the AD user attributes to the nss and domain sections in
/etc/sssd/sssd.conf. For example:[domain/EXAMPLE.com] ... krb5_store_password_if_offline = True ldap_user_extra_attrs=email:mail, lastname:sn, firstname:givenname [nss] user_attributes=+email, +firstname, +lastname [ifp] allowed_uids = ipaapi, root user_attributes=+email, +firstname, +lastname
-
Clear the SSSD cache:
-
Stop SSSD:
# systemctl stop sssd
-
Clear the cache:
# sss_cache -E
-
Start SSSD:
# systemctl start sssd
-
-
Verify the AD attributes value by using the
dbus-sendcommand on your Foreman server and on your FreeIPA server. Make sure that both outputs match.# dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserAttr string:ad-user@ad-domain array:string:email,firstname,lastname
-
4. Configuring Kerberos SSO for Active Directory users in Foreman
If the base system of your Foreman server is connected directly to Active Directory (AD), you can configure AD as an external authentication source for Foreman. Direct AD integration means that a Linux system is joined directly to the AD domain where the identity is stored.
AD users can log in using the following methods:
-
Username and password
-
Kerberos single sign-on
4.1. Joining the Foreman server system to an AD domain
The base system of your Foreman server must be joined to an Active Directory (AD) domain before you can configure the AD authentication source on your Foreman server. Use the System Security Services Daemon (SSSD) and Samba services to join the base system to the AD domain.
-
Install the following packages on Foreman server:
# dnf install adcli krb5-workstation oddjob-mkhomedir oddjob realmd samba-winbind-clients samba-winbind samba-common-tools samba-winbind-krb5-locator sssd
-
Join the system to the AD domain, specifying the required software:
# realm join AD.EXAMPLE.COM --membership-software=samba --client-software=sssd
4.2. Configuring the Active Directory authentication source on Foreman server
Enable Active Directory (AD) users to access Foreman by configuring the corresponding authentication provider on your Foreman server.
-
Define AD realm configuration in a location where Foreman expects it:
-
Create a directory named
/etc/ipa/:# mkdir /etc/ipa/
-
Create the
/etc/ipa/default.conffile with the following contents to configure the Kerberos realm for the AD domain:[global] realm = AD.EXAMPLE.COM
-
-
Configure the Apache keytab for Kerberos connections:
-
Update the
/etc/samba/smb.conffile with the following settings to configure how Samba interacts with AD:[global] workgroup = AD.EXAMPLE realm = AD.EXAMPLE.COM kerberos method = system keytab security = ads -
Add the Kerberos service principal to the keytab file at
/etc/httpd/conf/http.keytab:# KRB5_KTNAME=FILE:/etc/httpd/conf/http.keytab net ads keytab create HTTP -U Administrator -s /etc/samba/smb.conf
NoteThe
net ads keytab createcommand was introduced in Samba version 4.21.1. If your system uses an earlier version of Samba, use thenet ads keytab addcommand.
-
-
Configure the System Security Services Daemon (SSSD) on your Foreman server:
-
Configure the AD access control provider to evaluate and enforce Group Policy Object (GPO) access control rules for the
foremanPAM service. In the[domain/ad.example.com]section of your/etc/sssd/sssd.conffile, set thead_gpo_access_controlandad_gpo_map_serviceoptions as follows:[domain/ad.example.com] ad_gpo_access_control = enforcing ad_gpo_map_service = +foremanFor more information on GPOs, see How SSSD interprets GPO access control rules in Integrating RHEL systems directly with Windows Active Directory (RHEL 9).
-
If your Foreman server runs in an IPv6-only network and also runs on RHEL 9.6 and earlier or RHEL 10.0, set the
lookup_family_orderoption in the[domain/ad.example.com]section of the/etc/sssd/sssd.conffile:[domain/ad.example.com] lookup_family_order = ipv6_onlyIf the DNS name of the AD server can be translated to both an IPv4 and IPv6 address but the IPv4 address is not accessible, SSSD requires
lookup_family_orderto translate the DNS name correctly. Without the option, AD users are unable to usekinitto authenticate to Foreman. -
Restart SSSD:
# systemctl restart sssd
-
-
Enable the authentication source:
# foremanctl deploy --external-authentication ipa
-
To verify that AD users can log in to Foreman by entering their credentials, log in to Foreman web UI at https://foreman.example.com. Enter the user name in the user principal name (UPN) format, for example:
ad_user@AD.EXAMPLE.COM. -
To verify that AD users can authenticate by using Kerberos single sign-on:
-
Obtain a Kerberos ticket-granting ticket (TGT) on behalf of an AD user:
$ kinit ad_user@AD.EXAMPLE.COM
-
Verify user authentication by using your TGT:
$ curl -k -u : --negotiate https://foreman.example.com/users/extlogin
If external authentication is configured correctly, the
curlcommand redirects you tohttps://foreman.example.com/hosts:<html><body>You are being <a href="foreman.example.com/hosts">redirected</a>.</body></html>
-
-
Connecting to the AD LDAP can sometimes fail with an error such as the following appearing in the logs:
Authentication failed with status code: { "error": { "message": "ERF77-7629 [Foreman::LdapException]: Error while connecting to 'server.com' LDAP server at 'ldap.example.com' during authentication ([Net::LDAP::Error]: Connection reset by peer - SSL_connect)" } }If you see this error, verify which cipher is used for the connection:
# openssl s_client -connect ldap.example.com:636
If the
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384cipher is used, disable it on either the Foreman server side or on the AD side. TheTLS_DHE_RSA_WITH_AES_256_GCM_SHA384cipher is known to cause incompatibilities.For information on configuring system-wide cryptographic policies, see Using system-wide cryptographic policies in Red Hat Enterprise Linux 9 Security hardening.
5. Managing external user groups
When using external authentication sources, such as FreeIPA or Active Directory, you can configure group membership to control user access and permissions in Foreman. You might need to take extra configuration steps to manage group membership for user accounts defined in external authentication sources.
|
Note
|
External user groups based on FreeIPA or AD are refreshed only when a group member logs in to Foreman. It is not possible to alter user membership of external user groups in the Foreman web UI, such changes are overwritten on the next group refresh. |
5.1. Associating external users with user groups
Foreman does not associate external users with their user group automatically. To associate these external users with their user group, you must create the user group on your Foreman server.
When you create a Foreman user group with the same name as in the external source, members of the external user group automatically become members of the Foreman user group and receive the associated permissions. The configuration of external user groups depends on the type of external authentication.
To assign additional permissions to an external user, add this user to an internal user group that has no external mapping specified. Then assign the required roles to this group.
-
If you use a FreeIPA or AD server, configure Foreman to use FreeIPA or AD authentication. For more information, see Configuring authentication for Foreman users.
-
Ensure that at least one external user authenticates for the first time.
-
Retain a copy of the external group names you want to use. You can find the group membership of external users:
# id username
-
In the Foreman web UI, navigate to Administer > User Groups, and click Create User Group.
-
Specify the name of the new user group. Do not select any users to avoid adding users automatically when you refresh the external user group.
-
Click the Roles tab and select the roles you want to assign to the user group. Alternatively, select the Administrator checkbox to assign all available permissions.
-
Click the External groups tab, then click Add external user group, and select an authentication source from the Auth source drop-down menu.
Specify the exact name of the external group in the Name field.
-
Click Submit.
6. Resetting external authentication configuration for Kerberos SSO
You can disable external authentication with FreeIPA or Active Directory (AD) by resetting the configuration for the IPA authentication type.
This prevents user accounts defined in the external authentication source from accessing Foreman.
|
Important
|
Resetting external authentication prevents users from accessing Foreman with Kerberos single sign-on (SSO). However, some configuration files, such as configuration files for the System Security Services Daemon (SSSD), will remain modified because Foreman does not have access to the previous state of these files. |
-
Reset the external authentication configuration to the default state:
# foremanctl deploy --reset-external-authentication
-
Verify your external authentication configuration:
$ curl -k -u : --negotiate https://foreman.example.com/users/extlogin
If external authentication is disabled, the
curlcommand redirects you tohttps://foreman.example.com/users/login.<html><body>You are being <a href="https://foreman.example.com/users/login">redirected</a>.</body></html>