Rancher & Keycloak authentication backend setup

calendar Oct 21, 2024 · 5 min read · Rancher Kubernetes Keycloak  ·
Share on: linkedin copy

Rancher v2.X KeyCloak Authentication Backend Configuration

Ranchers official documentation about how to configure the Rancher & KeyCloak setup is fine but definitely not sufficient to successfully configure it. That's why every single required step is documented down here.

KeyCloak Configuration

Steps are based on master realm for the Rancher client. Nevertheless, it would sometimes absolutely make sense to use a custom KeyCloak realm.

  1. Login as admin on KEYCLOAK Important: It's crucial that in KeyCloak the same username exists as you use as admin user on Rancher. Since I just use the admin account in this guide, this prerequisite is already achieved.

  2. Create a new client under KEYCLOAK

    • Client ID: https://rancher.example.com/v1-saml/keycloak/saml/metadata
    • Client Protocol: saml
    • Root URL: Leave empty

  3. Configure some more properties (every other property is set to its default value):

    • Name: rancher
    • Enabled: ON
    • Login Theme: keycloak
    • Sign Documents: ON
    • Sign Assertions: ON
    • Name ID Format: username
    • Valid Redirect URLs: https://rancher.example.com/v1-saml/keycloak/saml/acs
    • IDP Initiated SSO URL Name: IdPSSOName Every other setting should be OFF

  4. Next, continue with the client mappers. Add/update the following two additional ones:

    1. Username:
    • Name: x509 username
    • Mapper Type: User Property
    • Property: username
    • Friendly Name: Leave empty
    • SAML Attribute Name: uid
    • SAML Attribute NameFormat: Basic
    1. Groups:
    • Name: groups
    • Mapper Type: Group list
    • Group attribute name: memberOf
    • Friendly Name: Leave empty
    • SAML Attribute Name: Basic
    • Single Group Attribute: ON
    • Full group path: OFF
    • Group attribute name can also be set as member. If you have existing users from ldap fedration etc, better to use memberOf it works with both.

  5. Enable Builtin Mappers

    saml protocol mapper

  6. Since Rancher needs a private key and public certificate to sign the messages, you need to create one for this purpose or use any existing.

    • To create new use the below command.
    1       openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout rancher-client.key -out rancher-client.cert

  7. Last but not least, you need to get the SAML Descriptior XML file.

    1. Access https://KEYCLOAK/auth/realms/master/protocol/saml/descriptor and save this XML content to a file called metadata.xml.
      OR
    1    curl -k https://KEYCLOAK/auth/realms/master/protocol/saml/descriptor >metadata.xml
    1. Since Rancher do not understand the EntitiesDescriptor tags Rancher Docs , copy all attributes from the <EntitiesDescriptor ...> tag and paste them in the <EntityDescriptor ...> tag one line below. Then remove the EntitiesDescriptor tags on the first and last line. Example:
      1. From this:
      1<EntitiesDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Name="urn:keycloak">
2  <EntityDescriptor entityID="https://KEYCLOAK/auth/realms/master">
3    <IDPSSODescriptor ......
4      .....
5    </IDPSSODescriptor>
6  </EntityDescriptor>
7</EntitiesDescriptor>
      1. To this:
      1<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Name="urn:keycloak" entityID="https://KEYCLOAK/auth/realms/master">
2  <IDPSSODescriptor ......
3      .....
4  </IDPSSODescriptor>
5</EntityDescriptor>
    2. Save and close the metadata.xml file.

  8. Now it's time to create groups inside KeyCloak, which you afterwards would like to permit on Rancher. In our example:

    1. In case of using fedrated ldap server following must be configured in order to map groups from ldap to roles in keycloak.
      • User Federation > Ldap >LDAP Mappers > Create New Name: ldap-group-name Mapper Type: group-ldap-mapper
    2. Furter configure the following
      • LDAP Groups DN: cn=groups,cn=accounts,dc=ldap,dc=example,dc=com
      • LDAP Filter: (cn=ldap_group_name)

  9. Assign the group memberships for your KeyCloak user, which is named the same as your current Rancher admin account (in our case admin). Add this user to the group by clicking Edit on the related user -> Groups -> Select both just created groups (one by one) and click Join.

Important: This user needs to have all group memberships for groups, which you would like to permit on Rancher later on. That's because Rancher is not able to search for groups via SAML, it just knows the one from your user. 10. That's all for the KeyCloak configuration part - simple, right ;-)?... Now continue with the Rancher configuration.

Rancher KeyCloak Authentication Configuration

  1. Access the Rancher GUI and navigate to Security -> Authentication.

  2. Select KeyCloak (SAML) and set the properties according to the values down here:

    • Display Name Field: givenName
    • User Name Field: uid (this field must match the SAML Attribute Name value from the KeyCloak Rancher client x509 username mapping!)
    • UID Field: uid (this field must match the SAML Attribute Name value from the KeyCloak Rancher client x509 username mapping!)
    • Groups Field: memberOf (this field must match the Group attribute name value from the KeyCloak Rancher client groups mapping!)
    • Rancher API Host: rancher.example.com

  3. Next, upload the before created files:

    • Private Key: rancher-client.key
    • CA Certificate: rancher-client.crt
    • Metadata XML: metadata.xml

  4. Click on Save and a small window will open which redirects you to the KeyCloak Login mask. (Allow popup in your browser)
    Enter the KeyCloak credentials and if everything was configured properly, the small window will close back again and you will be redirected and directly logged into Rancher.

  5. Now configure which groups can access Rancher by default without being specially granted on cluster/project basis.
    Chose Allow members of Clusters, Projects, plus Authorized Users and Organizations and in the textfield/dropdown on the right, click the dropdown button and select which group will be able to access Rancher (e.g. rancher-admins). Do not enter the group name in the textfield and hit enter (or click on the suggested value in the dropdown) since then it's then added as user and not as group! Ensure that right under the group name there is Group written in a light gray font and not User.

  6. Finally click save and you will be good to go.

Test the KeyCloak login in a incognito browser window by accessing Rancher endpoint and clicking on Log In with KeyCloak (you will then be redirected to the KeyCloak authentication site.