Chapter 4. Configuring Identity Management (External Authentication) with CloudForms
You can configure CloudForms to use system authentication methods such as Red Hat Identity Management (IdM) or IPA, Red Hat Single Sign-On (SSO), or Active Directory (AD).
This method uses apache
(httpd
) modules with web browsers to control authentication to CloudForms. It is the recommended authentication method to connect CloudForms with most identity management services.
4.1. Configuring Authentication with IPA
You can configure CloudForms to use IPA with the External Authentication (httpd) option in CloudForms.
When external authentication is enabled, users can log in to the CloudForms appliance using their IPA server credentials. The appliance creates user accounts automatically and imports relevant information from the IPA server.
The appliance contains IPA client software for connecting to IPA servers, but it is not configured by default. External authentication is enabled by configuring it with the appliance console and enabling it the web interface.
Disabling external authentication and returning to internal database authentication also requires steps in both the appliance console and the web user interface.
4.1.1. External Authentication Requirements
- For an appliance to leverage an IPA server on the network, both the appliance and the IPA server must have their clocks synchronized or Kerberos and LDAP authentication fail.
- The IPA server must be known by DNS and accessible by name. If DNS is not configured accordingly, the hosts files need to be updated to reflect both IPA server and the appliance on both virtual machines.
- For users to log in to the appliance using IPA server credentials, they must be members of at least one group on the IPA server which is also defined in the appliance. Navigate to the settings menu, then → → to administer groups.
4.1.2. Configuring the Appliance for External Authentication
To configure the appliance for external authentication, set up authentication using the appliance console, then select the External Authentication option in the web user interface.
Using the appliance console:
-
Log in to the appliance console using the user name
admin
. The summary screen displays:
External Auth: not configured
- Press Enter.
- Select Configure External Authentication (httpd).
- Enter the fully qualified host name of the IPA server, for example ipaserver.test.company.com.
- Enter the IPA server domain, for example test.company.com.
- Enter the IPA server realm, for example TEST.COMPANY.COM.
- Enter the IPA server principal, for example admin.
- Enter the password of the IPA server principal.
-
Enter
y
to proceed.
If any of the following conditions are true, configuration fails:
- The IPA server is not reachable by its FQDN
- The IPA server cannot reach the appliance by its FQDN
- The time is not synchronized between the appliance and the IPA server
- The IPA server admin password is entered incorrectly
Alternatively, you can configure external authentication using the appliance_console_cli
command instead of using the appliance console menu:
Example 4.1. Configuring External Authentication
$ ssh root@appliance.test.company.com [appliance]# /bin/appliance_console_cli --host appliance.test.company.com \ --ipaserver ipaserver.test.company.com \ --iparealm TEST.COMPANY.COM \ --ipaprincipal admin \ --ipapassword smartvm1
Finish configuring external authentication using the web user interface:
- Log in to the web user interface as an administrative user.
- Navigate to the settings menu, then → → → → or use the hosting provider of the virtual machine to synchronize the appliance’s time with an NTP server.
- From the settings menu, select Configuration.
- Select your server in the Settings accordion.
- Select the Authentication tab.
- Select a Session Timeout if required.
- Select External (httpd) in the Mode list.
- Select Enable Single Sign-On to allow single sign-on using Kerberos tickets from client machines that authenticate to the same IPA server as the appliance.
- In the Role Settings area, select Get User Groups from External Authentication (https).
- Click Save.
4.1.3. Reverting to Internal Database Authentication
To revert to internal database authentication, first configure authentication using the web user interface, then using the appliance console.
Using the web user interface:
- From the settings menu, select Configuration.
- Select your server in the Settings accordion.
- Select the Authentication tab.
- Select Database in the Mode list.
- Click Save.
Using the appliance console:
-
Log in to the appliance console using the user name
admin
. The summary screen displays:
External Auth: Id.server.FQDN
-
Press
Enter
. - Select Configure External Authentication (httpd). The currently configured IPA server host name and domain are displayed.
-
Enter
y
to remove configuration details for the IPA client.
Example 4.2. Reverting to Internal Database Authentication
$ ssh root@appliance.test.company.com [appliance]# /bin/appliance_console_cli --uninstall-ipa
4.1.4. Optional Configuration Using the Appliance Console CLI
In addition to using the appliance console, external authentication can optionally be configured and reverted using the appliance console command line interface.
Appliance console CLI command and relevant options include:
/bin/appliance_console_cli --host <appliance_fqdn> --ipaserver <ipa_server_fqdn> --iparealm <realm_of_ipa_server> --ipaprincipal <ipa_server_principal> --ipapassword <ipa_server_password> --uninstall-ipa4.5
- --host
-
Updates the host name of the appliance. If you performed this step using the console and made the necessary updates made to
/etc/hosts
if DNS is not properly configured, you can omit the--host
option. - --iparealm
-
If omitted, the
iparealm
is based on the domain name of theipaserver
. - --ipaprincipal
- If omitted, defaults to admin.
4.2. Configuring Authentication with Active Directory
This procedure outlines how to configure CloudForms to authenticate against an existing Active Directory (AD) configuration using external HTTP authentication. This provides Active Directory users access to the CloudForms appliance user interface, as well as the REST API.
4.2.1. Connecting CloudForms to an Active Directory Domain
To use an Active Directory domain to authenticate users to CloudForms, configure the following on CloudForms:
- Connect to the CloudForms appliance using SSH.
Run
realm discover
to determine what Active Directory realms are available:# realm discover example.com type: kerberos realm-name: EXAMPLE.COM domain-name: example.com configured: kerberos-member server-software: active-directory client-software: sssd required-package: oddjob required-package: oddjob-mkhomedir required-package: sssd required-package: adcli required-package: samba-common login-formats: %U@example.com login-policy: allow-realm-logins
Using the above information for your realm, join the Active Directory realm with a user that has enough permissions to be able to browse the directory:
# realm join example.com -U user Password for user: ******
Allow all realm users to log in using
realm permit
:# realm permit --all
Edit the
/etc/sssd/sssd.conf
file with your Active Directory domain details. Refer to the following example for formatting:[domain/example.com] ad_domain = example.com krb5_realm = EXAMPLE.COM realmd_tags = manages-system joined-with-samba cache_credentials = True id_provider = ad krb5_store_password_if_offline = True default_shell = /bin/bash ldap_id_mapping = True use_fully_qualified_names = True fallback_homedir = /home/%d/%u access_provider = ad ldap_user_extra_attrs = mail, givenname, sn, displayname, domainname [sssd] domains = example.com config_file_version = 2 services = nss, pam, ifp default_domain_suffix = example.com [nss] homedir_substring = /home [pam] default_domain_suffix = example.com [ifp] default_domain_suffix = example.com allowed_uids = apache, root user_attributes = +mail, +givenname, +sn, +displayname, +domainname
Restart and enable the
sssd
service:# systemctl restart sssd # systemctl enable sssd
Make sure the Kerberos keytab created by
realm join
above is readable by Apache:# chgrp apache /etc/krb5.keytab # chmod 640 /etc/krb5.keytab
Copy the following
httpd
configuration files into the correct respective directories with the following commands:# TEMPLATE_DIR="/opt/rh/cfme-appliance/TEMPLATE" # cp ${TEMPLATE_DIR}/etc/pam.d/httpd-auth /etc/pam.d/httpd-auth # cp ${TEMPLATE_DIR}/etc/httpd/conf.d/manageiq-remote-user.conf /etc/httpd/conf.d/ # cp ${TEMPLATE_DIR}/etc/httpd/conf.d/manageiq-external-auth.conf.erb /etc/httpd/conf.d/manageiq-external-auth.conf
Edit the
/etc/httpd/conf.d/manageiq-external-auth.conf
file to point to the Kerberos domain hosted by your Active Directory domain by adding or editing the lines forKrbAuthRealms
,Krb5KeyTab
andKrbServiceName
for your environment:<Location /dashboard/kerberos_authenticate> AuthType Kerberos AuthName "Kerberos Login" KrbMethodNegotiate On KrbMethodK5Passwd Off KrbAuthRealms example.com Krb5KeyTab /etc/krb5.keytab KrbServiceName Any Require pam-account httpd-auth ErrorDocument 401 /proxy_pages/invalid_sso_credentials.js </Location>
Set the following SELinux booleans:
# setsebool -P allow_httpd_mod_auth_pam on # setsebool -P httpd_dbus_sssd on
Restart and enable the
httpd
service:# systemctl restart httpd # systemctl enable httpd
Complete authentication setup by configuring the following on each appliance with the user_interface
or web_services
server roles enabled.
From the CloudForms user interface:
- Log in to the user interface as an administrative user.
- Navigate to the settings menu, then → .
- Select a Session Timeout if required.
- Select External (httpd) as the authentication Mode.
- Select Enable Single Sign-On to allow single sign-on using Kerberos tickets from client machines that authenticate to the same Active Directory domain as the appliance.
- In the Role Settings area, select Get User Groups from External Authentication (httpd).
- Click Save.
Make sure the user’s Active Directory groups for the appliance are created and appropriate roles assigned to those groups. See Roles in General Configuration for more information.
CloudForms is now configured to use authentication from your Active Directory domain.
4.2.2. Mapping Active Directory Users to CloudForms User Roles
This section provides instructions for mapping your existing Active Directory (AD) groups to user account roles in CloudForms.
This is done by assigning a CloudForms role to an AD group. When an AD user who is a part of that AD group attempts to log in to CloudForms, they get that role assigned automatically and inherit the permissions from that role. As a result, all users in that AD group will then be assigned the CloudForms role(s) associated with that group.
After configuring CloudForms to connect to an Active Directory domain in Section 4.2.1, “Connecting CloudForms to an Active Directory Domain”, complete the following steps:
- From the settings menu, select Configuration.
- Click the Access Control accordion, then click Groups.
-
Click
(Configuration), and
(Add a new Group) to create a group.
- In Group Information, select Look Up External Authentication Groups to find a list of groups assigned to a specific user in Active Directory.
In User to Look Up, enter the user name for a user in your AD group.
- Click Retrieve to look up details for the user in Active Directory and pull group information for the user. As a result, the AD groups will appear in the LDAP Groups for User drop-down list.
From the list in LDAP Groups for User, select the group you want to associate a CloudForms role with; for example, the
cloudforms
group.- Select a Role to map to the group.
- Select a Project/Tenant to map to the group.
- Click Add.
Any user who is part of cloudforms
AD group can now log in to CloudForms with their AD username and password, and they will automatically inherit the permissions for the role you assigned earlier.
To confirm this is configured correctly, log in to the CloudForms user interface with a user in the cloudforms
AD group.
To grant an additional user access to the CloudForms server, create the user in Active Directory, then add that user to the cloudforms
AD group. When that user attempts to log in to CloudForms, they will automatically inherit the correct permissions for the group.
4.3. Configuring Federated Authentication with SAML
This procedure outlines how to manually configure an appliance to use SAML for federation authentication.
To enable external authentication using SAML, complete the following steps to configure your HTTP server, then your CloudForms appliance.
The current SAML implementation only secures the CloudForms appliance’s web user interface with SAML. The REST API and self service user interface do not currently support SAML.
SAML Requirements
The following is required in order to enable SAML authentication to the appliance:
- A CloudForms appliance
- A SAML identity provider (e.g. Red Hat Single Sign-On 7.0 or later)
4.3.1. Configuring Authentication with SAML and Red Hat Single Sign-On (RH-SSO)
While other SAML identity providers can be used with CloudForms, this example procedure covers using Red Hat Single Sign-On (RH-SSO) 7.0, which is implemented using the Apache HTTP server’s mod_auth_mellon
module.
For more information about Red Hat Single Sign-On (RH-SSO), see the Red Hat Single Sign-On documentation.
4.3.1.1. Configuring the HTTP Server for SAML Authentication with Red Hat Single Sign-On (RH-SSO)
The Apache HTTP server first must be configured to work with SAML authentication. All SAML-related certificates and keys are accessed from /etc/httpd/saml2/
.
Log into the CloudForms appliance as root using SSH, and create the
/etc/httpd/saml2/
directory:# mkdir -p /etc/httpd/saml2
Copy the
httpd
remote user and SAML template configuration files to the appliance:# TEMPLATE_DIR="/opt/rh/cfme-appliance/TEMPLATE" # cp ${TEMPLATE_DIR}/etc/httpd/conf.d/manageiq-remote-user.conf /etc/httpd/conf.d/ # cp ${TEMPLATE_DIR}/etc/httpd/conf.d/manageiq-external-auth-saml.conf /etc/httpd/conf.d/
NoteThe following are notable SAML configuration defaults in the
manageiq-external-auth-saml.conf
file:Identity Provider Files (i.e. Red Hat SSO)
-
Metadata File:
/etc/httpd/saml2/idp-metadata.xml
-
Metadata File:
Service Provider Files (i.e.
mod_auth_mellon
)-
Private Key File:
/etc/httpd/saml2/miqsp-key.key
-
Certificate File:
/etc/httpd/saml2/miqsp-cert.cert
-
Metadata File:
/etc/httpd/saml2/miqsp-metadata.xml
-
Private Key File:
Other
mod_auth_mellon
parameters, such as endpoints and protected URLs, must not be modified as the appliance expects them to be defined as such.Generate the service provider files on the appliance using the Apache HTTP server’s
mod_auth_mellon
commandmellon_create_metadata.sh
:# cd /etc/httpd/saml2 # /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh https://<miq-appliance> https://<miq-appliance>/saml2
The
mellon_create_metadata.sh
script creates file names based on the appliance URL.NoteIf your appliance is behind a load balancer or uses a virtual IP address, use the hostname associated with the VIP. For example:
# /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh https://my-haproxy-ka https://my-haproxy-ka/saml2
Rename the files created by the
mellon_create_metadata.sh
script to match the expected file names from themanageiq-external-auth-saml.conf
file:# mv https_<miq-appliance>.key miqsp-key.key # mv https_<miq-appliance>.cert miqsp-cert.cert # mv https_<miq-appliance>.xml miqsp-metadata.xml
Now that the service provider’s
metadata.xml
file has been generated, the service provider definition can be defined in the SAML identity provider. For Red Hat SSO, a realm can be created for one or more appliances with individual clients defined one per appliance, where the client ID is specified as the URL of the appliance.To add a client in the Red Hat SSO CloudForms realm:
-
Select and import the
miqsp-metadata.xml
file created formod_auth_mellon
. -
Set the client ID as
https://<miq-appliance>
. -
Set the client protocol as
saml
.
-
Select and import the
Update the client definition for the appliance in Red Hat SSO with the following:
Setting Value Name ID Format
username
Valid Redirect URIs
Assertion Consumer Service POST Binding URL
Logout Service Redirect Binding URL
Obtain the identity provider’s
idp-metadata.xml
metadata file as follows:# cd /etc/httpd/saml2 # curl -s -o idp-metadata.xml \ http://<redhatSSO-server>:8080/auth/realms/<miq-realm>/protocol/saml/descriptor
In CloudForms, the following change is necessary to the
idp-metadata.xml
file for SAML logout to work betweenmod_auth_mellon
and Red Hat SSO:# vi idp-metadata.xml ... <SingleLogoutService < Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" --- > Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location= ...
Restart the HTTP server on the appliance:
# systemctl restart httpd
4.3.1.2. Configuring SAML Authentication in the CloudForms User Interface
After configuring the HTTP server for SAML, update the CloudForms appliance so that user interface can be accessed using SAML authentication.
- From the settings menu, select Configuration.
- Select your server in the Settings accordion.
- Select the Authentication tab.
- Select a Session Timeout to set the period of inactivity before a user is logged out of the console.
- Set the mode to External (httpd).
- Check Enable SAML. This enables the SAML login button on the appliance login screen, then redirects to the SAML protected page for authentication, and supports the SAML logout process.
-
Check Enable Single Sign-On. With this option enabled, initial access to the appliance’s user interface redirects to the SAML identity provider authentication screen. Logging out from the appliance returns the user to the appliance login screen, allowing them to log in as
admin
unless Disable Local Login is also checked. -
Optional: Check Disable Local Login to disable the
admin
login to appliance and only allow SAML based authentication. Note that if there are issues with the identity provider or you requireadmin
access to the appliance, you cannot log in through the appliance login screen until you re-enable local login as described in Section 4.3.3, “Re-enabling Local Login (Optional)”. - Check Get User Groups from External Authentication (httpd).
- Click Save.
Ensure the user’s groups are created on the appliance and appropriate roles are assigned to those groups. See SAML Assertions in Section 4.3.2, “SAML Assertions” for more information on the parameters used by the CloudForms appliance.
For example, to configure user groups from your SAML identity provider to work with CloudForms:
-
In your SAML identity provider, specify your existing user groups in similar format to the following:
REMOTE_USER_GROUPS=Administrators;CloudAdministrators;Users
- On your CloudForms appliance, create the equivalent groups. See Creating a User Group in General Configuration.
- On your CloudForms appliance, assign EVM roles to the groups. See Creating a Role in General Configuration.
Complete the above steps on each appliance in the settings menu, then navigate to
→ .You can now log into your CloudForms appliance using your SAML credentials.
4.3.2. SAML Assertions
To authenticate to the CloudForms appliance using SAML, the following remote user parameters are looked at by the appliance upon a successful login and redirect from the identity provider. These parameters are used by the appliance to obtain group authentication information.
HTTP Environment | SAML Assertion |
---|---|
REMOTE_USER | username |
REMOTE_USER_EMAIL | |
REMOTE_USER_FIRSTNAME | firstname |
REMOTE_USER_LASTNAME | lastname |
REMOTE_USER_FULLNAME | fullname |
REMOTE_USER_GROUPS | groups |
For Red Hat SSO, the above SAML assertions can be defined for the appliance client in Red Hat SSO as mappers.
Name | Category | Type | Property |
---|---|---|---|
username | AttributeStatement Mapper | User Property | username |
| AttributeStatement Mapper | User Property | |
firstname | AttributeStatement Mapper | User Property | firstName |
lastname | AttributeStatement Mapper | User Property | lastName |
fullname | AttributeStatement Mapper | User Attribute | fullName |
groups | Group Mapper | Group List | groups |
The fullName
attribute was not available in the default database as of this writing and was added as a user attribute.
4.3.3. Re-enabling Local Login (Optional)
If you disabled local login in the CloudForms user interface but need the ability to log in as admin
, you can re-enable local login using one of the following methods:
Re-enabling Local Login from the Appliance User Interface
This method requires the identity provider to be available, and the ability to log in as a user with enough administrative privileges to update CloudForms authentication settings.
- Log in to the appliance user interface as the administrative user.
- From the settings menu, select → .
- Uncheck Disable Local Login.
- Click Save.
Re-enabling Local Login from the Appliance Console:
-
Use SSH to log into the appliance as
root
. -
Run the
appliance_console
command. - Select Update External Authentication Options.
- Select Enable Local Login.
- Apply the updates.
Alternatively, log into the appliance as root using SSH, and run the following command:
# appliance_console_cli --extauth-opts local_login_disabled=false
4.4. Troubleshooting External Authentication Configuration
The following are common errors that you may encounter when integrating with IPA:
Error -1 : Kerberos authentication failed: kinit: Cannot contact any KDC for realm
Resolution: Verify on IPA server if you are able to log into the IPA server using same user.
Error-2: [----] W, [2017-09-28T10:05:29.157980 #28902:fa8bc4] WARN -- Failure: MIQ(Authenticator.authenticate) userid: [jdoe] - Authentication failed for userid jdoe: Authentication token is no longer valid; new one required
Resolution: The password has expired. Go to IPA/LDAP server and update your password using kinit <username>
.
Error-3: [----] W, [2017-09-28T10:13:10.083614 #28902:fa8bc4] WARN -- Failure: MIQ(Authenticator.block in authorize) userid: [jdoe] - Authentication failed for userid jdoe, unable to match user's group membership to an EVM role
Resolution: You should add the same group to the CloudForms group. Make sure you select Look up External Authentication Groups and enter the group name and user to look up.
4.4.1. Additional Troubleshooting Tips
-
Make an IPA/LDAP host entry in
/etc/hosts
file on the CloudForms appliance. - Make sure NTP synchronization exists between the CloudForms appliance and the IPA server.
-
Check
/var/log/krb5kdc.log
on the IPA server end and/var/www/miq/vmdb/log/audit.log
on the CloudForms appliance end for any other exception.