Integrate Microsoft Active Directory with Keycloak

This section describes how to federate Microsoft Active Directory (AD) with the Keycloak instance installed with Oracle Linux Virtualization Manager (the internal SSO provider). After you configure federation, you can synchronize selected AD users and groups into Keycloak and then assign permissions to those groups in the Manager.

User and group recommendations

We recommend assigning permissions to groups and placing users into those groups. You can tailor the group schema for the environment. The following groups are commonly used:

  • olvm-admins: Global administrators (oVirt SuperUser) and grafana-admin access.

  • ovirt-admins: oVirt administrators (SuperUser or delegated admin roles).

  • ovirt-users: VM Portal users.

  • grafana-admins, grafana-editors, grafana-viewers: Monitoring Portal (Grafana) roles.

Note:

Grafana uses roles (Admin, Editor, Viewer). Group-based access is implemented by mapping Keycloak groups to those roles.

Prerequisites

  • Microsoft Active Directory 2016 or later.

  • Oracle Linux Virtualization Manager 4.5 or later installed with Keycloak enabled during engine-setup.

  • If you use LDAPS, ensure the AD certificate chain is trusted by the Manager host.

Export the Active Directory certificate and trust it on the Manager host (LDAPS)

If the AD server uses LDAPS, you must trust the AD certificate chain on the Manager host. The exact procedure depends on the organization. The following example shows a common approach for importing the AD root certificate into the system trust store.

  1. Export the AD root CA certificate (Base-64 encoded X.509) from the Windows certificate store and copy it to the Manager host.

  2. On the Manager host, rename the certificate to use a .pem extension (if required), then copy it to the trust anchors directory: 

    sudo cp activedirectory.pem /etc/pki/ca-trust/source/anchors/
sudo chmod 600 /etc/pki/ca-trust/source/anchors/activedirectory.pem
sudo chown root:root /etc/pki/ca-trust/source/anchors/activedirectory.pem
sudo update-ca-trust extract

  3. (Optional) Verify connectivity to the directory service. For example, install openldap-clients and run ldapsearch: 

    sudo dnf install -y openldap-clients

ldapsearch -H ldaps://ad-server-fqdn -x -LLL \
  -D "CN=bind-user,CN=Users,DC=example,DC=com" -W \
  -b "DC=example,DC=com"

Collect required information

Before you start, collect the following information:

  • AD server host name (FQDN) and connection URL (LDAP or LDAPS).

  • Directory base DN (for example, DC=example,DC=com).

  • Bind account DN and password for Keycloak to query the directory.

  • AD groups to synchronize (for example, olvm-admins, ovirt-admins, ovirt-users, grafana-* groups).

Configure user federation (LDAP) in Keycloak

  1. Open the Keycloak administration console: https://manager-fqdn/ovirt-engine-auth/.

  2. In the navigation menu, select User Federation, then select Add provider and choose LDAP.

  3. Configure the LDAP provider. The following settings are commonly required for Active Directory:

    • Enabled: ON

    • Console display name: a friendly name for the directory

    • Vendor: Active Directory

    • Username LDAP attribute: sAMAccountName

    • UUID LDAP attribute: objectGUID

    • Connection URL: ldap://ad-server or ldaps://ad-server

    • Users DN: for example, CN=Users,DC=example,DC=com

    • Bind type: Simple

    • Bind DN and Bind credential: the bind account DN and password

    • Edit mode: READ_ONLY

  4. Select Test connection and Test authentication, and confirm both tests succeed.

  5. Select Synchronize all users to import directory users into Keycloak.

  6. Select Save.

Import selected Active Directory groups

To avoid importing all directory groups, configure a group mapper with an LDAP filter that matches only the groups you want to synchronize.

  1. In Keycloak, select User Federation, select the LDAP provider, and then select the Mappers tab.

  2. Select Create, then configure the mapper:

    • Mapper type: group-ldap-mapper

    • LDAP groups DN: the DN that contains the AD groups

    • Group name LDAP attribute: cn

    • Membership LDAP attribute: member

    • Membership user LDAP attribute: sAMAccountName

    • LDAP filter (example): 

      (|(cn=olvm-admins)(cn=ovirt-admins)(cn=ovirt-users)(cn=grafana-admins)(cn=grafana-editors)(cn=grafana-viewers))

  3. Select Save, then select Sync LDAP groups to Keycloak.

  4. Verify that the groups are present under Groups in Keycloak.

Allow group lookup by base DN in internal authorization

On the Manager host, configure the authorization extension to use the directory base DN. This enables group lookup when adding federated groups in the Administration Portal.

  1. On the Manager host, edit /etc/ovirt-engine/extensions.d/internalkeycloak-authz.properties and add the following line at the end of the file: 

    config.globals.baseDN.simple_baseDN = DC=example,DC=com

  2. Restart the engine:

    sudo systemctl restart ovirt-engine

Add federated groups in the Administration Portal and assign permissions

  1. Sign in to the Administration Portal as admin@ovirt.

  2. Go to Administration > Users.

  3. Select Groups, then select Add.

  4. From the domain list, select internalsso (internal Keycloak authorization provider).

  5. Search for the group, select it, and add it.

  6. Select the group name, open the Permissions tab, and assign roles (for example, assign SuperUser to olvm-admins and ovirt-admins).

  7. Sign out and then sign in as a user from the federated directory to verify access.

Note:

Oracle Linux Virtualization Manager might not display a federated user's first name, last name, or email address in the Administration Portal user list. This is a known issue.