Chapter 13. Configuring External Authentication
By using external authentication you can derive user and user group permissions from user group membership in an external identity provider. When you use external authentication, you do not have to create these users and maintain their group membership manually on Satellite Server.
Important User and Group Account Information
All user and group accounts must be local accounts. This is to ensure that there are no authentication conflicts between local accounts on your Satellite Server and accounts in your Active Directory domain.
Your system is not affected by this conflict if your user and group accounts exist in both /etc/passwd
and /etc/group
files. For example, to check if entries for puppet
, apache
, foreman
and foreman-proxy
groups exist in both /etc/passwd
and /etc/group
files, enter the following commands:
# cat /etc/passwd | grep 'puppet\|apache\|foreman\|foreman-proxy' # cat /etc/group | grep 'puppet\|apache\|foreman\|foreman-proxy'
Scenarios for Configuring External Authentication
Red Hat Satellite supports the following general scenarios for configuring external authentication:
- Using Lightweight Directory Access Protocol (LDAP) server as an external identity provider. LDAP is a set of open protocols used to access centrally stored information over a network. With Satellite, you can manage LDAP entirely through the Satellite web UI. For more information, see Section 13.1, “Using LDAP”. Though you can use LDAP to connect to a Red Hat Identity Management or AD server, the setup does not support server discovery, cross-forest trusts, or single sign-on with Kerberos in Satellite’s web UI.
- Using a Red Hat Identity Management server as an external identity provider. Red Hat Identity Management deals with the management of individual identities, their credentials and privileges used in a networking environment. Configuration using Red Hat Identity Management cannot be completed using only the Satellite web UI and requires some interaction with the CLI. For more information see Section 13.2, “Using Red Hat Identity Management”.
- Using Active Directory (AD) integrated with Red Hat Identity Management through cross-forest Kerberos trust as an external identity provider. For more information see Section 13.3.5, “Active Directory with Cross-Forest Trust”.
- Using Red Hat Single Sign-On as an OpenID provider for external authentication to Satellite with CAC cards. For more information, see Section 13.8, “Integrating Satellite with Red Hat Single Sign-On for External Authentication”.
As well as providing access to Satellite Server, hosts provisioned with Satellite can also be integrated with Red Hat Identity Management realms. Red Hat Satellite has a realm feature that automatically manages the life cycle of any system registered to a realm or domain provider. For more information, see Section 13.7, “External Authentication for Provisioned Hosts”.
Type | Authentication | User Groups |
---|---|---|
Red Hat Identity Management | Kerberos or LDAP | Yes |
Active Directory | Kerberos or LDAP | Yes |
POSIX | LDAP | Yes |
13.1. Using LDAP
If you require Red Hat Satellite to use TLS
to establish a secure LDAP connection (LDAPS), first obtain certificates used by the LDAP server you are connecting to and mark them as trusted on the base operating system of your Satellite Server as described below. If your LDAP server uses a certificate chain with intermediate certificate authorities, all of the root and intermediate certificates in the chain must be trusted, so ensure all certificates are obtained. If you do not require secure LDAP at this time, proceed to Section 13.1.2, “Configuring Red Hat Satellite to use LDAP”.
Using SSSD Configuration
Though direct LDAP integration is covered in this section, Red Hat recommends that you use SSSD and configure it against Red Hat Identity Management, AD, or an LDAP server. SSSD improves the consistency of the authentication process. For more information about the preferred configurations, see Section 13.3, “Using Active Directory”. You can also cache the SSSD credentials and use them for LDAP authentication. For more information on SSSD, see Configuring SSSD in the Red Hat Enterprise Linux 7 System-Level Authentication Guide.
13.1.1. Configuring TLS for Secure LDAP
Use the Satellite CLI to configure TLS for secure LDAP (LDAPS).
Procedure
Obtain the Certificate from the LDAP Server.
-
If you use Active Directory Certificate Services, export the Enterprise PKI CA Certificate using the Base-64 encoded X.509 format. See How to configure Active Directory authentication with
TLS
on Satellite 6 for information on creating and exporting a CA certificate from an Active Directory server. Download the LDAP server certificate to a temporary location on the Red Hat Enterprise Linux system where the Satellite Server is installed and remove it when finished.
For example,
/tmp/example.crt
. The filename extensions.cer
and.crt
are only conventions and can refer to DER binary or PEM ASCII format certificates.
-
If you use Active Directory Certificate Services, export the Enterprise PKI CA Certificate using the Base-64 encoded X.509 format. See How to configure Active Directory authentication with
Trust the Certificate from the LDAP Server.
Red Hat Satellite Server requires the CA certificates for LDAP authentication to be individual files in
/etc/pki/tls/certs/
directory.Use the
install
command to install the imported certificate into the/etc/pki/tls/certs/
directory with the correct permissions:# install /tmp/example.crt /etc/pki/tls/certs/
Enter the following command as
root
to trust the example.crt certificate obtained from the LDAP server:# ln -s example.crt /etc/pki/tls/certs/$(openssl \ x509 -noout -hash -in \ /etc/pki/tls/certs/example.crt).0
Restart the
httpd
service:# systemctl restart httpd
13.1.2. Configuring Red Hat Satellite to use LDAP
In the Satellite web UI, configure Satellite to use LDAP.
Note that if you need single sign-on functionality with Kerberos on Satellite’s web UI, you should use Red Hat Identity Management and AD external authentication instead. See Using Red Hat Identity Management or Using Active Directory for more information on those options.
Procedure
Set the Network Information System (NIS) service boolean to true to prevent SELinux from stopping outgoing LDAP connections:
# setsebool -P nis_enabled on
- Navigate to Administer > LDAP Authentication.
- Click Create Authentication Source.
-
On the LDAP server tab, enter the LDAP server’s name, host name, port, and server type. The default port is 389, the default server type is POSIX (alternatively you can select FreeIPA or Active Directory depending on the type of authentication server). For
TLS
encrypted connections, select the LDAPS check box to enable encryption. The port should change to 636, which is the default for LDAPS. - On the Account tab, enter the account information and domain name details. See Section 13.1.3, “Description of LDAP Settings” for descriptions and examples.
- On the Attribute mappings tab, map LDAP attributes to Satellite attributes. You can map login name, first name, last name, email address, and photo attributes. See Section 13.1.4, “Example Settings for LDAP Connections” for examples.
- On the Locations tab, select locations from the left table. Selected locations are assigned to users created from the LDAP authentication source, and available after their first login.
- On the Organizations tab, select organizations from the left table. Selected organizations are assigned to users created from the LDAP authentication source, and available after their first login.
- Click Submit.
Configure new accounts for LDAP users:
- If you did not select Automatically Create Accounts In Satellite check box, see Section 5.1.1, “Creating a User” to create user accounts manually.
- If you selected the Automatically Create Accounts In Satellite check box, LDAP users can now log in to Satellite using their LDAP accounts and passwords. After they log in for the first time, the Satellite administrator has to assign roles to them manually. See Section 5.1.2, “Assigning Roles to a User” to assign user accounts appropriate roles in Satellite.
13.1.3. Description of LDAP Settings
The following table provides a description for each setting in the Account tab.
Setting | Description |
---|---|
Account | The user name of the LDAP account that has read access to the LDAP server. User name is not required if the server allows anonymous reading, otherwise use the full path to the user’s object. For example: uid=$login,cn=users,cn=accounts,dc=example,dc=com
The The variable cannot be used with external user groups from an LDAP source because Satellite needs to retrieve the group list without the user logging in. Use either an anonymous, or dedicated service user. |
Account password |
The LDAP password for the user defined in the Account username field. This field can remain blank if the Account username is using the |
Base DN | The top level domain name of the LDAP directory. |
Groups base DN | The top level domain name of the LDAP directory tree that contains groups. |
LDAP filter | A filter to restrict LDAP queries. |
Automatically Create Accounts In Satellite | If this check box is selected, Satellite creates user accounts for LDAP users when they log in to Satellite for the first time. After they log in for the first time, the Satellite administrator has to assign roles to them manually. See Section 5.1.2, “Assigning Roles to a User” to assign user accounts appropriate roles in Satellite. |
Usergroup Sync | If this option is selected, the user group membership of a user is automatically synchronized when the user logs in, which ensures the membership is always up to date. If this option is cleared, Satellite relies on a cron job to regularly synchronize group membership (every 30 minutes by default). See To Configure an External User Group: for further context. |
13.1.4. Example Settings for LDAP Connections
The following table shows example settings for different types of LDAP connections. The example below uses a dedicated service account called redhat that has bind, read, and search permissions on the user and group entries. Note that LDAP attribute names are case sensitive.
Setting | Active Directory | FreeIPA or Red Hat Identity Management | POSIX (OpenLDAP) |
---|---|---|---|
Account | DOMAIN\redhat | uid=redhat,cn=users, cn=accounts,dc=example, dc=com | uid=redhat,ou=users, dc=example,dc=com |
Account password | P@ssword | - | - |
Base DN | DC=example,DC=COM | dc=example,dc=com | dc=example,dc=com |
Groups Base DN | CN=Users,DC=example,DC=com | cn=groups,cn=accounts, dc=example,dc=com | cn=employee,ou=userclass, dc=example,dc=com |
Login name attribute | userPrincipalName | uid | uid |
First name attribute | givenName | givenName | givenName |
Last name attribute | sn | sn | sn |
Email address attribute | | | |
userPrincipalName
allows the use of whitespace in usernames. The login name attribute sAMAccountName
(which is not listed in the table above) provides backwards compatibility with legacy Microsoft systems. sAMAccountName
does not allow the use of whitespace in usernames.
13.1.5. Example LDAP Filters
As an administrator, you can create LDAP filters to restrict the access of specific users to Satellite.
User | Filter |
---|---|
User1, User3 | (memberOf=cn=Group1,cn=Users,dc=domain,dc=example) |
User2, User3 | (memberOf=cn=Group2,cn=Users,dc=domain,dc=example) |
User1, User2, User3 | (|(memberOf=cn=Group1,cn=Users,dc=domain,dc=example)(memberOf=cn=Group2,cn=Users,dc=domain,dc=example)) |
LDAP directory structure
The LDAP directory structure that the filters in the example use:
DC=Domain,DC=Example | |----- CN=Users | |----- CN=Group1 |----- CN=Group2 |----- CN=User1 |----- CN=User2 |----- CN=User3
LDAP group membership
The group membership that the filters in the example use:
Group | Members |
---|---|
Group1 | User1, User3 |
Group2 | User2, User3 |
13.2. Using Red Hat Identity Management
This section shows how to integrate Red Hat Satellite Server with a Red Hat Identity Management server and how to enable host-based access control.
You can attach Red Hat Identity Management as an external authentication source with no single sign-on support. For more information, see Section 13.1, “Using LDAP”.
Prerequisites
- The Satellite Server has to run on Red Hat Enterprise Linux 7.1 or Red Hat Enterprise Linux 6.6 or later.
- The base operating system of the Satellite Server must be enrolled in the Red Hat Identity Management domain by the Red Hat Identity Management administrator of your organization.
The examples in this chapter assume separation between Red Hat Identity Management and Satellite configuration. However, if you have administrator privileges for both servers, you can configure Red Hat Identity Management as described in Red Hat Enterprise Linux 7 Linux Domain Identity, Authentication, and Policy Guide
13.2.1. Configuring Red Hat Identity Management Authentication on Satellite Server
In the Satellite CLI, configure Red Hat Identity Management authentication by first creating a host entry on the Red Hat Identity Management server.
Procedure
On the Red Hat Identity Management server, to authenticate, enter the following command and enter your password when prompted:
# kinit admin
To verify that you have authenticated, enter the following command:
# klist
On the Red Hat Identity Management server, create a host entry for the Satellite Server and generate a one-time password, for example:
# ipa host-add --random hostname
NoteThe generated one-time password must be used on the client to complete Red Hat Identity Management-enrollment.
For more information on host configuration properties, see About Host Entry Configuration Properties in the Red Hat Enterprise Linux 7 Linux Domain Identity, Authentication, and Policy guide.
Create an HTTP service for Satellite Server, for example:
# ipa service-add servicename/hostname
For more information on managing services, see Managing Services in the Red Hat Enterprise Linux 7 Linux Domain Identity, Authentication, and Policy guide.
On Satellite Server, install the IPA client:
WarningThis command might restart Satellite services during the installation of the package. For more information about installing and updating packages on Satellite, see Section 11.5, “Managing Packages on the Base Operating System of Satellite Server”.
# satellite-maintain packages install ipa-client
On Satellite Server, enter the following command as root to configure Red Hat Identity Management-enrollment:
# ipa-client-install --password OTP
Replace OTP with the one-time password provided by the Red Hat Identity Management administrator.
If Satellite Server is running on Red Hat Enterprise Linux 7, execute the following command:
# subscription-manager repos --enable rhel-7-server-optional-rpms
The installer is dependent on packages which, on Red Hat Enterprise Linux 7, are in the optional repository
rhel-7-server-optional-rpms
. On Red Hat Enterprise Linux 6 all necessary packages are in thebase
repository.Set
foreman-ipa-authentication
to true, using the following command:# satellite-installer --foreman-ipa-authentication=true
Restart the
satellite-maintain
services:# satellite-maintain service restart
External users can now log in to Satellite using their Red Hat Identity Management credentials. They can now choose to either log in to Satellite Server directly using their username and password or take advantage of the configured Kerberos single sign-on and obtain a ticket on their client machine and be logged in automatically. The two-factor authentication with one-time password (2FA OTP) is also supported. If the user in Red Hat Identity Management is configured for 2FA, and Satellite Server is running on Red Hat Enterprise Linux 7, this user can also authenticate to Satellite with an OTP.
13.2.2. Configuring Host-Based Authentication Control
HBAC rules define which machine within the domain a Red Hat Identity Management user is allowed to access. You can configure HBAC on the Red Hat Identity Management server to prevent selected users from accessing the Satellite Server. With this approach, you can prevent Satellite from creating database entries for users that are not allowed to log in. For more information on HBAC, see Configuring Host-Based Access Control in the Red Hat Enterprise Linux 7 Linux Domain Identity, Authentication, and Policy guide.
On the Red Hat Identity Management server, configure Host-Based Authentication Control (HBAC).
Procedure
On the Red Hat Identity Management server, to authenticate, enter the following command and enter your password when prompted:
# kinit admin
To verify that you have authenticated, enter the following command:
# klist
Create HBAC service and rule on the Red Hat Identity Management server and link them together. The following examples use the PAM service name satellite-prod. Execute the following commands on the Red Hat Identity Management server:
# ipa hbacsvc-add satellite-prod # ipa hbacrule-add allow_satellite_prod # ipa hbacrule-add-service allow_satellite_prod --hbacsvcs=satellite-prod
Add the user who is to have access to the service satellite-prod, and the hostname of the Satellite Server:
# ipa hbacrule-add-user allow_satellite_prod --user=username # ipa hbacrule-add-host allow_satellite_prod --hosts=satellite.example.com
Alternatively, host groups and user groups can be added to the allowsatellite_prod_ rule.
To check the status of the rule, execute:
# ipa hbacrule-find satellite-prod # ipa hbactest --user=username --host=satellite.example.com --service=satellite-prod
- Ensure the allow_all rule is disabled on the Red Hat Identity Management server. For instructions on how to do so without disrupting other services see the How to configure HBAC rules in IdM article on the Red Hat Customer Portal.
Configure the Red Hat Identity Management integration with the Satellite Server as described in Section 13.2.1, “Configuring Red Hat Identity Management Authentication on Satellite Server”. On the Satellite Server, define the PAM service as root:
# satellite-installer --foreman-pam-service=satellite-prod
13.3. Using Active Directory
This section shows how to use direct Active Directory (AD) as an external authentication source for Satellite Server.
You can attach Active Directory as an external authentication source with no single sign-on support. For more information, see Section 13.1, “Using LDAP”.
For an example configuration, see How to configure Active Directory authentication with TLS on Satellite 6.
Direct AD integration means that Satellite Server is joined directly to the AD domain where the identity is stored. The recommended setup consists of two steps:
- Enrolling Satellite Server with the Active Directory server as described in Section 13.3.2, “Enrolling Satellite Server with the AD Server”
- Configuring direct Active Directory integration with GSS-proxy as described in Section 13.3.3, “Configuring Direct AD Integration with GSS-proxy”.
13.3.1. GSS-Proxy
The traditional process of Kerberos authentication in Apache requires the Apache process to have read access to the keytab file. GSS-Proxy allows you to implement stricter privilege separation for the Apache server by removing access to the keytab file while preserving Kerberos authentication functionality. When using AD as an external authentication source for Satellite, it is recommended to implement GSS-proxy, because the keys in the keytab file are the same as the host keys.
The AD integration requires Red Hat Satellite Server to be deployed on Red Hat Enterprise Linux 7.1 or later.
Perform the following procedures on Red Hat Enterprise Linux that acts as a base operating system for your Satellite Server. For the examples in this section EXAMPLE.ORG is the Kerberos realm for the AD domain. By completing the procedures, users that belong to the EXAMPLE.ORG realm can log in to the Satellite Server.
13.3.2. Enrolling Satellite Server with the AD Server
In the Satellite CLI, enroll Satellite Server with the Active Directory server.
Prerequisites
GSS-proxy and nfs-utils are installed.
Installing GSS-proxy and nfs-utils:
# satellite-maintain packages install gssproxy nfs-utils
Procedure
Install the required packages:
# satellite-maintain packages install sssd adcli realmd ipa-python-compat krb5-workstation samba-common-tools
Enroll Satellite Server with the AD server. You may need to have administrator permissions to perform the following command:
# realm join -v EXAMPLE.ORG
13.3.3. Configuring Direct AD Integration with GSS-proxy
In the Satellite CLI, configure the direct Active Directory integration with GSS-proxy.
Prerequisite
Satellite is enrolled with the Active Directory server.
For more information, see Section 13.3.2, “Enrolling Satellite Server with the AD Server”.
Procedure
Create the
/etc/ipa/
directory and thedefault.conf
file:# mkdir /etc/ipa # touch /etc/ipa/default.conf
To the
default.conf
file, add the following content:[global] server = unused realm = EXAMPLE.ORG
Create the
/etc/net-keytab.conf
file with the following content:[global] workgroup = EXAMPLE realm = EXAMPLE.ORG kerberos method = system keytab security = ads
Determine the effective user ID of the Apache user:
# id apache
Apache user must not have access to the keytab file.
Create the
/etc/gssproxy/00-http.conf
file with the following content:[service/HTTP] mechs = krb5 cred_store = keytab:/etc/krb5.keytab cred_store = ccache:/var/lib/gssproxy/clients/krb5cc_%U euid = ID_of_Apache_User
Create a keytab entry:
# KRB5_KTNAME=FILE:/etc/httpd/conf/http.keytab net ads keytab add HTTP -U administrator -d3 -s /etc/net-keytab.conf # chown root.apache /etc/httpd/conf/http.keytab # chmod 640 /etc/httpd/conf/http.keytab
Enable IPA authenication in Satellite:
# satellite-installer --foreman-ipa-authentication=true
Start and enable the
gssproxy
service:# systemctl restart gssproxy.service # systemctl enable gssproxy.service
Configure the Apache server to use the gssproxy service:
Create the
/etc/systemd/system/httpd.service
file with the following content:.include /lib/systemd/system/httpd.service [Service] Environment=GSS_USE_PROXY=1
Apply changes to the service:
# systemctl daemon-reload
Start and enable the
httpd
service:# systemctl restart httpd.service
Verify that SSO is working as expected.
With a running Apache server, users making HTTP requests against the server are authenticated if the client has a valid Kerberos ticket.
Retrieve the Kerberos ticket of the LDAP user, using the following command:
# kinit ldapuser
View the Kerberos ticket, using the following command:
# klist
View output from successful SSO-based authentication, using the following command:
# curl -k -u : --negotiate https://satellite.example.com/users/extlogin
This returns the following response:
<html><body>You are being <a href="https://satellite.example.com/users/4-ldapuserexample-com/edit">redirected</a>.</body></html>
13.3.4. Kerberos Configuration in Web Browsers
For information on configuring the Firefox browser see Configuring Firefox to Use Kerberos for Single Sign-On in the Red Hat Enterprise Linux System-Level Authentication guide.
If you use the Internet Explorer browser, add Satellite Server to the list of Local Intranet or Trusted sites, and turn on the Enable Integrated Windows Authentication setting. See the Internet Explorer documentation for details.
With direct AD integration, HBAC through Red Hat Identity Management is not available. As an alternative, you can use Group Policy Objects (GPO) that enable administrators to centrally manage policies in AD environments. To ensure correct GPO to PAM service mapping, use the following sssd configuration:
access_provider = ad ad_gpo_access_control = enforcing ad_gpo_map_service = +foreman
Here, foreman is the PAM service name. For more information on GPOs, please refer to the Red Hat Enterprise Linux Windows Integration Guide.
13.3.5. Active Directory with Cross-Forest Trust
Kerberos can create cross-forest trust
that defines a relationship between two otherwise separate domain forests. A domain forest is a hierarchical structure of domains; both AD and Red Hat Identity Management constitute a forest. With a trust relationship enabled between AD and Red Hat Identity Management, users of AD can access Linux hosts and services using a single set of credentials. For more information on cross-forest trusts, see Creating Cross-forest Trusts with Active Directory and Identity Management in the Red Hat Enterprise Linux Windows Integration guide.
From the Satellite point of view, the configuration process is the same as integration with Red Hat Identity Management server without cross-forest trust configured. The Satellite Server has to be enrolled in the IPM domain and integrated as described in Section 13.2, “Using Red Hat Identity Management”.
13.3.6. Configuring the Red Hat Identity Management Server to Use Cross-Forest Trust
On the Red Hat Identity Management server, configure the server to use cross-forest trust
.
Procedure
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.
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:
[nss] user_attributes=+mail, +sn, +givenname [domain/EXAMPLE] ldap_user_extra_attrs=mail, sn, givenname
13.4. Configuring External User Groups
Satellite does not associate external users with their user group automatically. You must create a user group with the same name as in the external source on Satellite. Members of the external user group then automatically become members of the Satellite 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.
Prerequisites
If you use an LDAP server, configure Satellite to use LDAP authentication. For more information see Section 13.1, “Using LDAP”.
When using external user groups from an LDAP source, you cannot use the
$login
variable as a substitute for the account user name. You must use either an anonymous or dedicated service user.- If you use a Red Hat Identity Management or AD server, configure Satellite to use Red Hat Identity Management or AD authentication. For more information, see Chapter 13, Configuring External Authentication.
- Ensure that at least one external user authenticates for the first time.
Retain a copy of the external group names you want to use. To find the group membership of external users, enter the following command:
# id username
To Configure an External User Group:
- In the Satellite 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 check box 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.
13.5. Refreshing External User Groups for LDAP
To set the LDAP source to synchronize user group membership automatically on user login, in the Auth Source page, select the Usergroup Sync option. If this option is not selected, LDAP user groups are refreshed automatically through a scheduled cron job synchronizing the LDAP Authentication source every 30 minutes by default.
If the user groups in the LDAP Authentication source change in the lapse of time between scheduled tasks, the user can be assigned to incorrect external user groups. This is corrected automatically when the scheduled task runs.
Use this procedure to refresh the LDAP source manually.
Procedure
- Navigate to Administer > Usergroups and select a user group.
- Navigate to the External Groups tab and click Refresh to the right of the required user group.
For CLI Users
Enter the following command:
# foreman-rake ldap:refresh_usergroups
13.6. Refreshing External User Groups for Red Hat Identity Management or AD
External user groups based on Red Hat Identity Management or AD are refreshed only when a group member logs in to Satellite. It is not possible to alter user membership of external user groups in the Satellite web UI, such changes are overwritten on the next group refresh.
13.7. External Authentication for Provisioned Hosts
Use this section to configure Satellite Server or Capsule Server for Red Hat Identity Management realm support, then add hosts to the Red Hat Identity Management realm group.
Prerequisites
You require the following setup to configure external authentication for provisioned hosts:
- Satellite Server that is registered to the Content Delivery Network or an external Capsule Server that is registered to Satellite Server.
- A deployed realm or domain provider such as Red Hat Identity Management.
To install and configure Red Hat Identity Management packages on Red Hat Satellite Server or Red Hat Satellite Capsule Server:
To use Red Hat Identity Management for provisioned hosts, complete the following steps to install and configure Red Hat Identity Management packages on Red Hat Satellite Server or Red Hat Satellite Capsule Server:
Install the
ipa-client
package on Satellite Server or Capsule Server:On Satellite Server, enter the following command:
# satellite-maintain packages install ipa-client
On Capsule Server, enter the following command:
# yum install ipa-client
Configure the server as a Red Hat Identity Management client:
# ipa-client-install
Create a realm proxy user,
realm-capsule
, and the relevant roles in Red Hat Identity Management:# foreman-prepare-realm admin realm-capsule
Note the principal name that returns and your Red Hat Identity Management server configuration details because you require them for the following procedure.
To configure Satellite Server or Capsule Server for Red Hat Identity Management Realm Support:
Complete the following procedure on Satellite and every Capsule that you want to use:
Copy the
/root/freeipa.keytab
file to any Capsule Server that you want to include in the same principal and realm:# scp /root/freeipa.keytab root@capsule.example.com:/etc/foreman-proxy/freeipa.keytab
Move the
/root/freeipa.keytab
file to the/etc/foreman-proxy
directory and set the ownership settings to theforeman-proxy
user:# mv /root/freeipa.keytab /etc/foreman-proxy # chown foreman-proxy:foreman-proxy /etc/foreman-proxy/freeipa.keytab
Enter the following command on all Capsules that you want to include in the realm. If you use the integrated Capsule on Satellite, enter this command on Satellite Server:
# satellite-installer --foreman-proxy-realm true \ --foreman-proxy-realm-keytab /etc/foreman-proxy/freeipa.keytab \ --foreman-proxy-realm-principal realm-capsule@EXAMPLE.COM \ --foreman-proxy-realm-provider freeipa
You can also use these options when you first configure the Red Hat Satellite Server.
Ensure that the most updated versions of the ca-certificates package is installed and trust the Red Hat Identity Management Certificate Authority:
# cp /etc/ipa/ca.crt /etc/pki/ca-trust/source/anchors/ipa.crt # update-ca-trust enable # update-ca-trust
Optional: If you configure Red Hat Identity Management on an existing Satellite Server or Capsule Server, complete the following steps to ensure that the configuration changes take effect:
Restart the foreman-proxy service:
# systemctl restart foreman-proxy
- In the Satellite web UI, navigate to Infrastructure > Capsules.
- Locate the Capsule you have configured for Red Hat Identity Management and from the list in the Actions column, select Refresh.
To create a realm for the Red Hat Identity Management-enabled Capsule
After you configure your integrated or external Capsule with Red Hat Identity Management, you must create a realm and add the Red Hat Identity Management-configured Capsule to the realm.
To create a realm, complete the following steps:
- In the Satellite web UI, navigate to Infrastructure > Realms and click Create Realm.
- In the Name field, enter a name for the realm.
- From the Realm Type list, select the type of realm.
- From the Realm Capsule list, select the Capsule Server where you have configured Red Hat Identity Management.
- Click the Locations tab and from the Locations list, select the location where you want to add the new realm.
- Click the Organizations tab and from the Organizations list, select the organization where you want to add the new realm.
- Click Submit.
Updating Host Groups with Realm Information
You must update any host groups that you want to use with the new realm information.
- Navigate to Configure > Host Groups, select the host group that you want to update, and click the Network tab.
- From the Realm list, select the realm you create as part of this procedure, and then click Submit.
Adding Hosts to a Red Hat Identity Management Host Group
Red Hat Identity Management supports the ability to set up automatic membership rules based on a system’s attributes. Red Hat Satellite’s realm feature provides administrators with the ability to map the Red Hat Satellite host groups to the Red Hat Identity Management parameter userclass
which allow administrators to configure automembership.
When nested host groups are used, they are sent to the Red Hat Identity Management server as they are displayed in the Red Hat Satellite User Interface. For example, "Parent/Child/Child".
Satellite Server or Capsule Server sends updates to the Red Hat Identity Management server, however automembership rules are only applied at initial registration.
To Add Hosts to a Red Hat Identity Management Host Group:
On the Red Hat Identity Management server, create a host group:
# ipa hostgroup-add hostgroup_name --desc=hostgroup_description
Create an
automembership
rule:# ipa automember-add --type=hostgroup hostgroup_name automember_rule
Where you can use the following options:
-
automember-add
flags the group as an automember group. -
--type=hostgroup
identifies that the target group is a host group, not a user group. -
automember_rule
adds the name you want to identify the automember rule by.
-
Define an automembership condition based on the
userclass
attribute:# ipa automember-add-condition --key=userclass --type=hostgroup --inclusive-regex=^webserver hostgroup_name ---------------------------------- Added condition(s) to "hostgroup_name" ---------------------------------- Automember Rule: automember_rule Inclusive Regex: userclass=^webserver ---------------------------- Number of conditions added 1 ----------------------------
Where you can use the following options:
-
automember-add-condition
adds regular expression conditions to identify group members. -
--key=userclass
specifies the key attribute asuserclass
. -
--type=hostgroup
identifies that the target group is a host group, not a user group. -
--inclusive-regex=
^webserver identifies matching values with a regular expression pattern. - hostgroup_name - identifies the target host group’s name.
-
When a system is added to Satellite Server’s hostgroup_name host group, it is added automatically to the Red Hat Identity Management server’s "hostgroup_name" host group. Red Hat Identity Management host groups allow for Host-Based Access Controls (HBAC), sudo policies and other Red Hat Identity Management functions.
13.8. Integrating Satellite with Red Hat Single Sign-On for External Authentication
You can configure Satellite to use Red Hat Single Sign-On as an OpenID provider for external authentication with CAC cards. You can only use CAC cards; other authentication methods are not supported.
Authentication using Red Hat Single Sign-On as an OpenID provider is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.
Prerequisites
- A working installation of Red Hat Single Sign-On server that uses HTTPS instead of HTTP.
- If the certificates or the CA are self-signed, ensure that they are added to the end-user certificate trust store.
Procedure
Install the following packages:
# satellite-maintain packages install mod_auth_openidc keycloak-httpd-client-install
On Satellite Server, install the Red Hat Single Sign-On httpd client:
# keycloak-httpd-client-install --app-name foreman-openidc \ --keycloak-server-url "RHSSO.example.com" \ --keycloak-admin-username "RHSSO_User" \ --keycloak-realm "RHSSO_Realm" \ --keycloak-admin-realm master \ --keycloak-auth-role root-admin -t openidc -l /users/extlogin --force
The above command registers a client for Satellite in Red Hat Single Sign-On.
Enable Red Hat Single Sign-On using
satellite-installer
:# satellite-installer --foreman-keycloak true \ --foreman-keycloak-app-name "foreman-openidc" \ --foreman-keycloak-realm "RHSSO_Realm"
Restart the httpd service:
# systemctl restart httpd
- In the Red Hat Single Sign-On web UI, navigate to Client and click the Satellite client.
- Ensure that the Access type setting is set to Confidential.
If you use Red Hat Single Sign-On version 7.3 or later, complete the following steps:
- Navigate to the Red Hat Single Sign-On web UI, click Clients and click the client registered with Satellite.
-
Locate the Valid redirect URI field that contains one redirect URI by default. Add a Valid redirect URI in the following form:
https://satellite.example.com/users/extlogin
. - Click Save.
Click the Mappers tab and click Create. Set the following values for the audience mapper:
- From the Mapper Type list, select Audience.
From the Included Client Audience list, select the client that you use with Satellite.
For more information about audience support, see Audience Support in the Red Hat Single Sign-On Server Administration Guide.
- Click Save.
Click the Mapper tab and click Create to add a group mapper so that you can specify authorization in Satellite based on group membership. Set the following values for the group mapper:
- From the Mapper Type list, select Group Membership.
- From the Token Claim Name list, select groups.
Set the Full group path toggle to OFF.
For more information about group mappers, see Group Mapper in the LDAP Mappers section of the Red Hat Single Sign-On Server Administration Guide.
- Click Save.
- In the Satellite web UI, navigate to Administer > Settings, and click the Authentication tab.
-
Locate the Authorize login delegation row, and in the Value column, set the value to
Yes
. -
Locate the Authorize login delegation auth source user autocreate row, and in the Value column, set the value to
External
. Locate the Login delegation logout URL row, and in the Value column, set the value to
https://satellite.example.com/users/extlogout
.For the following steps, you can retrieve the values that you require by navigating to the following URL:
RHSSO.example.com/auth/realms/RHSSO_REALM/.well-known/openid-configuration
.-
Locate the OIDC Algorithm row, and in the Value column, set the algorithm for encoding on Red Hat Single Sign-On, for example,
RS256
. -
Locate the OIDC Audience row, and in the Value column, set the value to the client ID for Red Hat Single Sign-On:
['satellite.example.com']
. -
Locate the OIDC Issuer row, and in the Value column, set the value to
RHSSO.example.com/auth/realms/RHSSO_Realm
. -
Locate the OIDC JWKs URL row, and in the Value column, set the value to
RHSSO.example.com/auth/realms/RHSSO_Realm/protocol/openid-connect/certs
. Until BZ#1792131 is resolved, you must use the Hammer CLI to set the organization and location. To retrieve the ID of the Red Hat Single Sign-On authentication source, enter the following command:
# hammer auth-source external list
Set the organization and location for the authentication source:
# hammer auth-source external update --id Authentication Source ID \ --location-ids Location ID --organization-ids Organization ID
You can now authenticate using the https://satellite.example.com/users/extlogin login URL.
For CLI Users
Install the following packages:
# satellite-maintain packages install keycloak-httpd-client-install
On Satellite Server, install the Red Hat Single Sign-On httpd client:
# keycloak-httpd-client-install --app-name foreman-openidc \ --keycloak-server-url "RHSSO.example.com" \ --keycloak-admin-username "RHSSO_User" \ --keycloak-realm "RHSSO_Realm" \ --keycloak-admin-realm master \ --keycloak-auth-role root-admin -t openidc -l /users/extlogin --force
This command creates a client for Satellite in Red Hat Single Sign-On.
Enable Red Hat Single Sign-On using
satellite-installer
:# satellite-installer --foreman-keycloak true \ --foreman-keycloak-app-name "foreman-openidc" \ --foreman-keycloak-realm "RHSSO_Realm"
Restart the httpd service:
# systemctl restart httpd
- In the Red Hat Single Sign-On web UI, navigate to Client and click the Satellite client.
- Set the Access type setting to Public.
-
In the Valid Redirect URL field, enter
urn:ietf:wg:oauth:2.0:oob
. If you use Red Hat Single Sign-On version 7.3 or later, complete the following steps:
- Navigate to the Red Hat Single Sign-On web UI, click Clients and click the client registered with Satellite.
-
Locate the Valid redirect URI field that contains one redirect URI by default. Add a Valid redirect URI in the following form:
https://satellite.example.com/users/extlogin
. - Click Save.
Click the Mappers tab and click Create. Set the following values for the audience mapper:
- From the Mapper Type list, select Audience.
From the Included Client Audience list, select the client that you use with Satellite.
For more information about audience support, see Audience Support in the Red Hat Single Sign-On Server Administration Guide.
- Click Save.
Click the Mapper tab and click Create to add a group mapper so that you can specify authorization in Satellite based on group membership. Set the following values for the group mapper:
- From the Mapper Type list, select Group Membership.
- From the Token Claim Name list, select groups.
Set the Full group path toggle to OFF.
For more information about group mappers, see Group Mapper in the LDAP Mappers section of the Red Hat Single Sign-On Server Administration Guide.
- Click Save.
On Satellite, set the login delegation to
true
so that users can authenticate using the Open IDC protocol:# hammer settings set --name authorize_login_delegation --value true
Set the login authorization to an external source:
# hammer settings set --name authorize_login_delegation_auth_source_user_autocreate --value External
Set the login delegation logout URL:
# hammer settings set --name login_delegation_logout_url \ --value https://satellite.example.com/users/extlogout
Set the algorithm for encoding on Red Hat Single Sign-On, for example,
RS256
:# hammer settings set --name oidc_algorithm --value 'RS256'
-
Open the
RHSSO.example.com/auth/realms/RHSSO_REALM/.well-known/openid-configuration
URL and note the values to populate the options in the following steps. Set the value for the Open IDC audience:
# hammer settings set --name oidc_audience \ --value "['satellite.example.com']"
Set the value for the Open IDC issuer:
# hammer settings set --name oidc_issuer \ --value "RHSSO.example.com/auth/realms/RHSSO_Realm"
Set the value for Open IDC Java Web Token (JWT):
# hammer settings set --name oidc_jwks_url \ --value "RHSSO.example.com/auth/realms/RHSSO_Realm/protocol/openid-connect/certs"
Until BZ#1792131 is resolved, you must use the Hammer CLI to set the organization and location. To set the organization and location, you must first retrieve the ID of the Red Hat Single Sign-On authentication source:
# hammer auth-source external list
Set the location and organization:
# hammer auth-source external update --id Authentication Source ID \ --location-ids Location ID --organization-ids Organization ID
To authenticate using two-factor authentication, enter the following command:
# hammer auth login oauth \ --two-factor \ --oidc-token-endpoint 'https://RHSSO.example.com/auth/realms/ssl-realm/protocol/openid-connect/token' \ --oidc-authorization-endpoint 'https://RHSSO.example.com/auth' \ --oidc-client-id 'satellite.example.com-foreman-openidc' \ --oidc-redirect-uri urn:ietf:wg:oauth:2.0:oob
The command prompts you to enter a success code. To retrieve the success code, navigate to the URL that the commands returns and provide the required information.
13.9. Disabling Red Hat Single Sign-On Authentication
If you want to disable Red Hat Single Sign-On authentication in Satellite, complete this procedure.
Procedure
Enter the following command to disable Red Hat Single Sign-On Authentication:
# satellite-installer --reset-foreman-keycloak