Chapter 4. Configuring Federated Identity Management (External Authentication) with CloudForms

You can configure CloudForms to use federation authentication with system authentication methods such as Red Hat Identity Management (IdM), Red Hat Single Sign-On (SSO), or Active Directory (AD).

4.1. Configuring Federated Authentication with IdM

You can configure CloudForms to use Red Hat Identity Management (IdM) for federated authentication using the External Authentication (httpd) option in CloudForms.

When external authentication is enabled, users can log in to the CloudForms appliance using their IdM server credentials. The appliance creates user accounts automatically and imports relevant information from the IdM server.

The appliance contains IdM client software for connecting to IdM servers, but it is not configured by default. External authentication is enabled by first configuring it in the web interface, then in the console. Disabling external authentication and returning to internal database authentication also requires steps in both the web interface and the console.

4.1.1. External Authentication Requirements

  • For an appliance to leverage an IdM server on the network, both the appliance and the IdM server must have their clocks synchronized or Kerberos and LDAP authentication fail.
  • The IdM 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 IdM server and the appliance on both virtual machines.
  • For users to log in to the appliance using IdM server credentials, they must be members of at least one group on the IdM server which is also defined in the appliance. Navigate to the settings menu, then ConfigurationAccess ControlGroups to administer groups.

4.1.2. Configuring the Appliance for External Authentication

To configure the appliance for external authentication, first set up authentication using the web interface, then using the appliance console.

Using the web interface:

  1. Log in to the web interface as an administrative user.
  2. Navigate to the settings menu, then ConfigurationSettingsZoneServerNTP Servers or use the hosting provider of the virtual machine to synchronize the appliance’s time with an NTP server.
  3. From the settings menu, select Configuration.
  4. Select your server in the Settings accordion.
  5. Select the Authentication tab.
  6. Select a Session Timeout if required.
  7. Select External (httpd) in the Mode list.
  8. Select Enable Single Sign-On to allow single sign-on using Kerberos tickets from client machines that authenticate to the same IdM server as the appliance.
  9. In the Role Settings area, select Get User Groups from External Authentication (https).
  10. Click Save.

Using the console:

  1. Log in to the appliance console using the user name admin.
  2. The summary screen displays:

    External Auth:  not configured
  3. Press Enter.
  4. Select Configure External Authentication (httpd).
  5. Enter the fully qualified hostname of the IdM server, for example idmserver.test.company.com.
  6. Enter the IdM server domain, for example test.company.com.
  7. Enter the IdM server realm, for example TEST.COMPANY.COM.
  8. Enter the IdM server principal, for example admin.
  9. Enter the password of the IdM server principal.
  10. Enter y to proceed.
Note

If any of the following conditions are true, configuration fails:

  • The IdM server is not reachable by its FQDN
  • The IdM server cannot reach the appliance by its FQDN
  • The time is not synchronized between the appliance and the IdM server
  • The IdM server admin password is entered incorrectly

Example 4.1. Configuring External Authentication

$ ssh root@appliance.test.company.com
[appliance]# /bin/appliance_console_cli --host appliance.test.company.com \
                                      --ipaserver idmserver.test.company.com \
                                      --iparealm TEST.COMPANY.COM \
                                      --ipaprincipal admin \
                                      --ipapassword smartvm1

4.1.3. Reverting to Internal Database Authentication

To revert to internal database authentication, first configure authentication using the web interface, then using the console.

Using the web interface:

  1. From the settings menu, select Configuration.
  2. Select your server in the Settings accordion.
  3. Select the Authentication tab.
  4. Select Database in the Mode list.
  5. Click Save.

Using the console:

  1. Log in to the appliance console using the user name admin.
  2. The summary screen displays:

    External Auth:  Id.server.FQDN
  3. Press Enter.
  4. Select Configure External Authentication (httpd). The currently configured IdM server hostname and domain are displayed.
  5. Enter y to remove configuration details for the IdM 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 <idm_server_fqdn>
                           --iparealm <realm_of_idm_server>
                           --ipaprincipal <idm_server_principal>
                           --ipapassword <idm_server_password>
                           --uninstall-ipa4.5
--host
Updates the hostname 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 the ipaserver.
--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.

  1. Connect to the CloudForms appliance using SSH.
  2. 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
  3. 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: ******
  4. Allow all realm users to log in using realm permit:

    # realm permit --all
  5. 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
  6. Restart and enable the sssd service:

    # systemctl restart sssd
    # systemctl enable sssd
  7. Make sure the Kerberos keytab created by realm join above is readable by Apache:

    # chgrp apache /etc/krb5.keytab
    # chmod 640 /etc/krb5.keytab
  8. 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
  9. Edit the /etc/httpd/conf.d/manageiq-external-auth.conf file to point to your Kerberos domain hosted by your Active Directory domain by adding the lines for KrbAuthRealms, Krb5KeyTab and KrbServiceName 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>
  10. Set the appropriate SELinux booleans:

    # setsebool -P allow_httpd_mod_auth_pam on
    # setsebool -P httpd_dbus_sssd          on
  11. 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. Follow these steps from the CloudForms user interface:

  1. Log in to the user interface as an administrative user.
  2. Navigate to the settings menu, then ConfigurationAuthentication.
  3. Select a Session Timeout if required.
  4. Select External (httpd) as the authentication Mode.
  5. 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.
  6. In the Role Settings area, select Get User Groups from External Authentication (httpd).
  7. Click Save.
Important

Make sure the user’s Active Directory group 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.3. Configuring Federated Authentication with Red Hat Single Sign-On (RH-SSO) and SAML

This procedure outlines how to manually configure an appliance to use SAML for federation authentication. While other SAML identity providers can be used with CloudForms, this 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.

Note

For more information about Red Hat Single Sign-On (RH-SSO), see the Red Hat Single Sign-On documentation.

To enable external authentication using SAML, complete the following steps to configure your HTTP server, then your CloudForms appliance.

Note

The current SAML implementation only secures the CloudForms appliance’s web administrative user interface with SAML. The REST API and self service user interface do not currently support SAML.

4.3.1. SAML Requirements

The following is required in order to enable SAML authentication to the appliance:

  • A CloudForms 4.6 appliance
  • A SAML identity provider (e.g. Red Hat Single Sign-On (RH-SSO) 7.0 or later)

4.3.2. Configuring the HTTP Server for SAML Authentication

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/.

  1. Log into the CloudForms appliance as root using SSH, and create the /etc/httpd/saml2/ directory:

    # mkdir -p /etc/httpd/saml2
  2. 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/
    Note

    The 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
    • 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

    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.

  3. Generate the service provider files on the appliance using the Apache HTTP server’s mod_auth_mellon command mellon_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.

  4. Rename the files created by the mellon_create_metadata.sh script to match the expected file names from the manageiq-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
  5. 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:

    1. Select and import the miqsp-metadata.xml file created for mod_auth_mellon.
    2. Set the client ID as https://<miq-appliance>.
    3. Set the client protocol as saml.
  6. Update the client definition for the appliance in Red Hat SSO with the following:

    SettingValue

    Name ID Format

    username

    Valid Redirect URIs

    https://<miq-appliance>/saml2/postResponse

    Assertion Consumer Service POST Binding URL

    https://<miq-appliance>/saml2/postResponse

    Logout Service Redirect Binding URL

    https://<miq-appliance>/saml2/logout

  7. 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
  8. In CloudForms 4.6, the following change is necessary to the idp-metadata.xml file for SAML logout to work between mod_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=
      ...
  9. Restart the HTTP server on the appliance:

    # systemctl restart httpd

4.3.3. Configuring the Appliance Administrative User Interface

After configuring the HTTP server for SAML, update the CloudForms appliance so that the administrative user interface works with SAML authentication.

  1. From the settings menu, select Configuration.
  2. Select your server in the Settings accordion.
  3. Select the Authentication tab.
  4. Select a Session Timeout to set the period of inactivity before a user is logged out of the console.
  5. Set the mode to External (httpd).
  6. 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.
  7. Check Enable Single Sign-On. With this option enabled, initial access to the appliance’s administrative 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.
  8. 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 require admin 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.5, “Re-enabling Local Login (Optional).
  9. Check Get User Groups from External Authentication (httpd).
  10. Click Save.
Important

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.4, “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:

  1. In your SAML identity provider, specify your existing user groups in similar format to the following: REMOTE_USER_GROUPS=Administrators;CloudAdministrators;Users
  2. On your CloudForms appliance, create the equivalent groups. See Creating a User Group in General Configuration.
  3. 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 ConfigurationAccess Control.

You can now log into your CloudForms appliance using your SAML credentials.

4.3.4. 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 EnvironmentSAML Assertion

REMOTE_USER

username

REMOTE_USER_EMAIL

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.

NameCategoryTypeProperty

username

AttributeStatement Mapper

User Property

username

email

AttributeStatement Mapper

User Property

email

firstname

AttributeStatement Mapper

User Property

firstName

lastname

AttributeStatement Mapper

User Property

lastName

fullname

AttributeStatement Mapper

User Attribute

fullName

groups

Group Mapper

Group List

groups

Important

The fullName attribute was not available in the default database as of this writing and was added as a user attribute.

4.3.5. Re-enabling Local Login (Optional)

If you disabled local login in the administrative user interface but need the ability to log in as admin, local login can be re-enabled using one of the following methods:

Re-enabling Local Login from the Appliance Administrative 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.

  1. Log in to the appliance user interface as the administrative user.
  2. From the settings menu, select ConfigurationAuthentication.
  3. Uncheck Disable Local Login.
  4. Click Save.

Re-enabling Local Login from the Appliance Console:

  1. Use SSH to log into the appliance as root.
  2. Run the appliance_console command.
  3. Select Update External Authentication Options.
  4. Select Enable Local Login.
  5. 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.