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.


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        \
# cp ${TEMPLATE_DIR}/etc/httpd/conf.d/manageiq-external-auth-saml.conf \

SAML Configuration

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

Description Default

Identity Provider Files (i.e. KeyCloak)

Metadata File


Service Provider Files (i.e. mod_auth_mellon)

Private Key File


Certificate File


Metadata File


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 as follows:

# cd /etc/httpd/saml2
# /usr/libexec/mod_auth_mellon/ https://<miq-appliance> https://<miq-appliance>/saml2

The 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


Valid Redirect URIs


Master SAML Processing URL


Assertion Consumer Service POST Binding URL


Logout Service Redirect Binding URL


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 \

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

<   Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
>   Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

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













For KeyCloak, the above SAML Assertions can be defined for the Appliance Client in KeyCloak as Mappers.

Name Category Type Property


AttributeStatement Mapper

User Property



AttributeStatement Mapper

User Property



AttributeStatement Mapper

User Property



AttributeStatement Mapper

User Property



AttributeStatement Mapper

User Attribute



Group Mapper

Group List


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