ManageIQ
Latest
Versions: Latest / Quinteros / Petrosian / Oparin / Najdorf / Morphy / Lasker / Kasparov / Jansa / Ivanchuk / Hammer / Gaprindashvili / Fine / Euwe

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 only secures the Appliance’s Web administrative UI with OIDC.

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

  1. Requirements

  2. Apache Configuration

  3. OIDC Configuration

  4. OIDC Assertions

  5. Configuring the Administrative UI

  6. Re-Enabling Local Login

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)

Apache Configuration

Copy the Apache OIDC template configuration files:

# TEMPLATE_DIR="/var/www/miq/system/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 \
    /etc/httpd/conf.d/

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:

Name Value

LogLevel

warn

OIDCCryptoPassphrase

sp-cookie

OIDCOAuthRemoteUserClaim

username

Installation specific values must be specified in the manageiq-external-auth-oidc.conf file for these values:

Name Value

ServerName

https://<miq-appliance>

OIDCProviderMetadataURL

http://<openidc server>:<openidc port, usually 8080>/auth/realms/miq/.well-known/openid-configuration

OIDCCLientID

<openidc client name>

OIDCClientSecret

<openidc client secret>

OIDCRedirectURI

https://<miq-appliance>/oidc_login/redirect_uri

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:

Setting Value

Client Protocol

openid-connect

Access Type

confidential

Valid Redirect URIs

https://<miq-appliance>

https://<miq-appliance>/oidc_login/redirect_uri

User Info Signed

unsigned

Request Object Signature Algorithm

any

The value used for OIDCClientSecret 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.

Finally, restart Apache on the appliance as follows:

# systemctl restart httpd

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.

HTTP Environment OIDC 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 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:

Name Category Mapper Type

email

Token mapper

User Property

family name

Token mapper

User Property

given name

Token mapper

User Property

full name

Token mapper

User’s full name

username

Token mapper

User Property

The following Group Membership mapper must be manually created:

Name Consent Required Mapper Type Token Claim Name Full group path Add to ID token Add to access token Add to userinfo

groups

OFF

Group Membership

groups

OFF

ON

OFF

OFF

The following User Session Note mappers must be manually created:

Name Consent Required Mapper Type User Session Note Token Claim Name Claim JSON Type Add to ID token Add to access token

Client Host

OFF

User Session Note

clientHost

clientHost

String

ON

ON

Client ID

OFF

User Session Note

clientId

clientId

String

ON

ON

Client IP Address

OFF

User Session Note

clientAddress

clientAddress

String

ON

ON

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