Integrating FreeIPA with ICE ClusterWare#

Installation#

FreeIPA is a powerful, open-source identity management system that can export an LDAP directory of user credentials which can then be ingested into Keycloak and other authentication systems. The ICE ClusterWare™ platform's use of FreeIPA does not necessarily use all of its features, and the full configuration process for all of FreeIPA is beyond the scope of this document. For more in-depth information, admins can refer to the FreeIPA website and, particularly, its documentation link:

https://www.freeipa.org/page/Documentation.html

Assuming FreeIPA is installed and operational, the process to integrate it with Keycloak involves creating a new "User Federation" connection, including an optional "User LDAP Filter" to reduce the user accounts to only those in a certain group. Once configured, any users that match the filter will be available inside Keycloak and can then be assigned roles and added to the ClusterWare software.

Installation instructions can be found in FreeIPA's documentation. FreeIPA provides RPM and DEB packages, as well as container deployment options.

https://www.freeipa.org/page/Quick_Start_Guide https://www.freeipa.org/Downloads.html

Identify a Group for ClusterWare Users#

In a larger enterprise, it may make sense to select or create a group that will be used to identify users who have administrative access to the ClusterWare system. This can help reduce the number of accounts that are being sync'ed between Keycloak and FreeIPA. If a group already exists for those users, the full DN for the group should be noted. Otherwise, a new group should be created and any ClusterWare admins should be added to that group.

By default, FreeIPA places user groups in a DN of the form:

cn=keycloak-allowed,cn=groups,cn=accounts,dc=<companyname>,dc=<com>

The DC components at the end will be dependent on the domain name as it is configured inside FreeIPA.

Identify an Admin Account for Keycloak#

Keycloak will need to authenticate in order to access FreeIPA, so it will need an admin-level account to do so. If an account already exists, the full DN for the account should be noted. Otherwise, a new account should be created.

By default, FreeIPA places users in a DN of the form:

uid=<kcadmin>,cn=users,cn=accounts,dc=<companyname>,dc=<com>

Again, the DC components will reflect the domain name, and the kcadmin component will be the username.

Configure Keycloak#

In Keycloak, switch to the realm that is being used by the ClusterWare system and look for the "User federation" tab in the left menu. When creating a new User-federation connection, select the "LDAP" option.

Several settings need to be configured:

  • For the "Vendor", select "Red Hat Directory Services"

  • Connection URL will be the URL to get to the FreeIPA server. Note that this should start with a prefix of ldap:// or ldaps://.

    • Use the "Test connection" button to verify that Keycloak can reach FreeIPA over the network. If any problems show up, it may indicate firewall or other network issues.

  • Bind type is "simple", and use the DN for the admin user selected or created above. E.g. uid=<kcadmin>,cn=users,cn=accounts,dc=<companyname>,dc=<com>. Enter the admin password into the "Bind credential" text box.

    • Use the "Test authentication" button to verify that the username and password are working correctly, and that FreeIPA is responding properly to Keycloak's requests.

  • Edit mode should be "READ_ONLY"

  • For the default FreeIPA settings, the Users DN field should be cn=users,cn=accounts,dc=<companyname>,dc=<com>.

  • Username LDAP attribute and RDN LDAP attribute should both be set to uid.

  • UUID LDAP attribute should be uidNumber.

  • Although optional, admins are encouraged to set a User LDAP filter to reduce the number of user accounts that are downloaded and sync'ed from FreeIPA to Keycloak.

    • For a newly created group in a default FreeIPA system, a suitable filter might be: (memberOf=cn=<keycloak-allowed>,cn=groups,cn=accounts,dc=<companyname>,dc=<com>) where keycloak-group is the name of the group that contains all ClusterWare admins.

LDAP offers a power filtering syntax that can allow for one or more user-groups, or even selecting users by one or more roles. See https://ldap.com/ldap-filters/ for more information.

For all other settings, the defaults should work. Larger enterprises may want to think through the Periodic full sync and Periodic changed users sync settings to limit the load on the FreeIPA servers; note that those settings are defined in number of seconds between synchronization events.

Note that one must click the "Save" button at the bottom of the webpage or else any changes will be lost!

Verifying the Integration#

Once the User federation connection is created, the connection can be verified by going to the Users page in the Keycloak web-UI. Since there is a federation defined, the Users webpage will only present a search box, not a list of known users. To see all users, simply search for *. Depending on the number of accounts that need to be downloaded or sync'ed, it may take a few seconds before results are rendered.

Once the page updates, all available users should be shown -- all users defined inside Keycloak as well as those defined in FreeIPA.

Note

Keycloak and FreeIPA accounts can co-exist, so it may be useful to create a few Keycloak-only users just in case the FreeIPA connection goes down.

In addition to the "Test" buttons in the Keycloak web-UI, one can always go directly to the Keycloak and FreeIPA web-UIs to do some "debugging".

  • The FreeIPA login page should be at https://<freeipa-base-url/ipa/ui/ (be sure to logout from any current sessions). This can be useful in verifying that a given username and password work at all. If FreeIPA does not allow the account, then Keycloak will never see it and the problem is likely inside FreeIPA.

  • The Keycloak login page for a realm should be at: https://<keycloak-base-url>:8080/realms/<realm-name>/account/ (be sure to logout from any current sessions). If Keycloak does not allow the account, then it could be a problem inside Keycloak.

Note

When using Keycloak and FreeIPA, no roles should be assigned in the ClusterWare software – all roles must be assigned through Keycloak.