• OpenID-Connect
• Requirements
• Configuring Keycloak
  • OIDC Assertions
  • Apache Configuration
  • OIDC Configuration
• Configuring the Administrative UI
• Re-Enabling Local Login
  • Administrative UI:
  • Appliance Console Interface:
  • Appliance Console CLI:
• Configuring OIDC using the CLI
  • Configure OpenID-Connect
  • Unconfigure OpenID-Connect

OpenID-Connect

External Authentication on the Appliance has been enhanced to support OpenID-Connect, which will also be referred to as OIDC.

The OIDC implementation has been tested with KeyCloak 3.2.1.

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

The current implementation secures the Appliance’s Web administrative and Self-Service UI with OIDC.

1. Requirements

2. Configuring Keycloak

3. OIDC Assertions

4. Apache Configuration

5. OIDC Configuration

6. Configuring the Administrative UI

7. Re-Enabling Local Login

8. Configuring OIDC using the CLI

Requirements

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

• A CentOS/RHEL 7.5 based Appliance

• A OIDC Identity Provider, (e.g. KeyCloak 3.2.1 or Later)

Configuring Keycloak

For KeyCloak, a Realm can be created for one or more Appliances with individual Clients defined one per Appliance where the Client ID identifies the individual appliance, e.g. the appliance hostname.

Adding a Client in the KeyCloak ManageIQ Realm:

• Set Client ID as <miq-appliance>

• Set Client protocol as openid-connect.

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

Note: The trailing / for the /ui/service/ entry is required.

The value used for OIDCClientSecret (oidc_client_secret) in the manageiq-external-auth-oidc.conf file is taken from the Keycloak Client’s Credentials / Secret value. To generate a new client secret, First set the Credentials / Client Authenticator to Client Id and Secret . Then Regenerate Secret button.

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

For KeyCloak, the above OIDC Assertions can be created for the Appliance Client in KeyCloak as Mappers.

The following mappers are automatically generated when the OIDC client is created:

The following Group Membership mapper must be manually created:

The following User Session Note mappers must be manually created:

Apache Configuration

Copy the Apache OIDC template configuration files:

# TEMPLATE_DIR="/opt/manageiq/manageiq-appliance/TEMPLATE"
# cp ${TEMPLATE_DIR}/etc/httpd/conf.d/manageiq-remote-user-openidc.conf \
    /etc/httpd/conf.d/
# cp ${TEMPLATE_DIR}/etc/httpd/conf.d/manageiq-external-auth-openidc.conf.erb \
    /etc/httpd/conf.d/manageiq-external-auth-openidc.conf

OIDC Configuration

The Apache /etc/httpd/conf.d/manageiq-external-auth-openidc.conf configuration files must be updated with installation specific values:

The defaults in the manageiq-external-auth-oidc.conf file are:

Installation specific values must be specified in the manageiq-external-auth-oidc.conf file for the following parameters, where the parameter including the <%= …​ %> anchors need to be replaced with the appropriate values:

Optional parameters can be appended to the end fo the configuration file to avoid SSL verification. These can be used when a valid SSL server certificate is not available for communicating with the OpenID Provider.

NOTE: Using these parameters is insecure and should only be used in a development environment.

Finally, restart Apache on the appliance as follows:

# systemctl restart httpd

Configuring the Administrative UI

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

Login as admin, then in Configure→Configuration→Authentication

• Set mode to External (httpd)

• Check: Provider Type: Enable Enable OpenID-Connect - This enables the OIDC login button on the login screen, that redirects to the OIDC protected page for authentication, and supports the OIDC logout process.

• Optional: Check: Enable Single Signon - With this option enabled, initial access to the Appliance Administrative UI will redirect to the OIDC 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 OIDC 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 using either of the following methods:

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

Configuring OIDC using the CLI

Another way to configure OpenID-Connect on the appliance is to use the appliance console CLI instead of the above steps. The --oidc-config subcommand of the appliance console CLI allows one to configure the appliance for OpenID-Connect Authentication by updating both Apache configurations as well as the necessary Administrative UI settings. The --oidc-unconfig subcommand is also provided for unconfiguring the appliance OpenID-Connect Authentication and reverting the appliance to Database Authentication.

Usage of the new Appliance Console CLI subcommands are as follows:

Configure OpenID-Connect

To configure the appliance for OpenID-Connect Authentication:

# appliance_console_cli --oidc-config
                        [--oidc-client-host]
                        --oidc-url
                        --oidc-client-id
                        --oidc-client-secret
                        [--oidc-introspection-endpoint]
                        [--oidc-enable-sso]
                        [--oidc-insecure]

When the --oidc-introspection-endpoint is not specified, an attempt will be made to fetch the introspection endpoint by querying the OpenID-Connect Provider URL.

When the --oidc-client-host is not specified, the configured appliance host is used for the ServerName and OpenID-Connect Redirect URI in the OpenID-Connect Apache configuration file. The --oidc-client-host is usually the externally reachable FQDN of the appliance.

When --oidc-insecure is specified no SSL verification will be done when attempting to fetch the introspection endpoint and SSL verification will be disabled using parameters OIDCSSLValidateServer and OIDCOAuthSSLValidateServer as described above.

Configuring OpenID-Connect requires the following parameters:

The --oidc-url varies for different providers. An example provider URL for keycloak:

--oidc-url=http://keycloak-server:8080/auth/realms/miq-realm/.well-known/openid-configuration

With miq-realm being the Keycloak Realm this OpenID-Connect appliance client is being configured for.

The --oidc-client-id is the Client ID specified for the appliance in the OpenID-Connect provider, usually just <miq-appliance-fqdn>

By default, SSO is not enabled, so from the Appliance login page, the user clicks on Log In to Corporate System to get redirected to the OpenID-Connect login page. With the --oidc-enable-sso option specified, the Appliance redirects the user to the OpenID-Connect login page for logging in.

Unconfigure OpenID-Connect

To unconfigure the appliance from OpenID-Connect Authentication and revert to Database authentication:

# appliance_console_cli --oidc-unconfig

This will remove the Apache external authentication OpenID-Connect configuration files and revert the appliance’s authentication settings to Database mode.