SAML

External Authentication on the Appliance has been enhanced to support SAML. The SAML implementation has been tested with KeyCloak 1.8.

In this guide we will cover how to manually configure an Appliance’s external authentication to work with SAML. The SAML implementation has been tested with KeyCloak but is implemented generically using Apache’s mod_auth_mellon module and should work with other SAML Identity Providers.

The current implementation only secures the Appliance’s Web administrative UI with SAML.

Note: The REST API and Self-Service UI do not currently support SAML.

Requirements

The following is needed in order to enable SAML Authentication to the Appliance:

  • A CentOS/RHEL 7.2 based Appliance

  • A SAML Identity Provider, (e.g. KeyCloak 1.8 or Later)

Configure SAML

All SAML related certificates and keys are accessed from /etc/httpd/saml2/

First ssh to the appliance as root, then create that directory:

# mkdir -p /etc/httpd/saml2

Apache Configuration

Copy the Apache remote user and SAML template configuration files:

# TEMPLATE_DIR="/var/www/miq/system/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/

SAML Configuration

Notable defaults in the manageiq-external-auth-saml.conf file:

Description Default

Identity Provider Files (i.e. KeyCloak)

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 must not be modified as the Appliance expects them to be defined as such, i.e. End points, Protected URL, etc.

For the Service Provider files on the Appliance, these can be generated using the mod_auth_mellon command mellon_create_metadata.sh as follows:

# 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 but can be renamed 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

With the service provider metadata.xml file generated, the Service Provider definition can now be defined in the Identity Provider.

For KeyCloak, a Realm can be created for one or more Appliances with individual Clients defined one per Appliance where the Client ID is essentially the URL of the appliance.

Adding a Client in the KeyCloak ManageIQ Realm:

  • Select and Import the miqsp-metadata.xml file created for mod_auth_mellon.

  • Set Client ID as https://<miq-appliance>

  • Set Client protocol as saml.

The Client definition for the appliance can then be updated with the following:

Setting Value

Name ID Format

username

Valid Redirect URIs

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

Master SAML Processing URL

https://<miq-appliance>/saml2

Assertion Consumer Service POST Binding URL

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

Logout Service Redirect Binding URL

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

The Identity Provider’s Metadata file idp-metadata.xml can then be obtained as follows:

# cd /etc/httpd/saml2
# curl -s -o idp-metadata.xml \
    http://<keycloak-server>:8080/auth/realms/<miq-realm>/protocol/saml/descriptor

As of this writing, the following change is necessary for the SAML Logout to work between mod_auth_mellon and KeyCloak:

# 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=
  ...

Finally, restart Apache on the appliance as follows:

# systemctl restart httpd

SAML Assertions

For authenticating to the appliance, the following remote user parameters are looked at by the appliance upon a successful login and redirect from the Identity Provider.

HTTP Environment SAML 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 KeyCloak, the above SAML Assertions can be defined for the Appliance Client in KeyCloak as Mappers.

Name Category Type Property

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

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

Configure Administrative UI

After having configured Apache for SAML, the next step is to update the Appliance Administrative UI to be SAML aware and function accordingly.

Login as admin, then in Configure→Configuration→Authentication

  • Set mode to External (httpd)

  • Check: Enable SAML - This will enable the SAML login button on the login screen, the redirects to the SAML protected page for authentication as well as supporting the SAML logout process.

  • Check: Enable Single Signon - With this option enabled, initial access to the Appliance Administrative UI will redirect to the SAML Identity Provider authentication screen. Note that logouts from the Appliance will return the user to the Appliance login screen allowing them to login as admin unless Disable Local Login is checked below.

  • Optional: Check: Disable Local Login - Do this only if you need to disable admin login to appliance and only allow SAML based authentication. Note that if there are issues with the Identity Provider or you need admin access to the appliance you won’t be able to login until you re-enable the Local Login as described below.

  • Check: Get User Groups from External Authentication (httpd)

  • Click Save.

The above steps need to be done on each UI enabled appliance.

in Configure→Configuration→Access Control

  • Make sure the user’s groups are created on the Appliance and appropriate roles assigned to those groups.

Re-Enabling Local Login

If the Local Login has been disabled in the Administrative UI and there is a need to be able to login as admin, the Local Login can be re-enabled as follows:

Administrative UI:

This option is available if the Identity Provider is available and one can login using a user with enough administrative privileges to update it:

  • Login as administrative user,

  • In then in Configure→Configuration→Authentication uncheck Disable Local Login and save.

Appliance Console Interface:

  • ssh to the appliance as root

  • Run appliance_console

  • Select menu entry Update External Authentication Options

  • Select Enable Local Login

  • then Apply updates

Appliance Console CLI:

  • ssh to the appliance as root

  • Run appliance_console_cli --extauth-opts local_login_disabled=false