Rancher v2.X KeyCloak Authentication Backend Configuration

rancher-keycloak-idp-configuration.md

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 (https://rancher.com/docs/rancher/v2.x/en/admin-settings/authentication/keycloak/). That's the reason why here every single required step is documented down here.

KeyCloak Configuration

I simply use the default master realm for the Rancher client. Nevertheless, it would sometimes absolutely make sense to use a custom KeyCloak realm.

1. Login as admin on https://keycloak.example.com/. 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 https://keycloak.example.com/auth/admin/master/console/#/realms/master/clients
   • 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
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
   2. Groups:
   • Name: groups
   • Mapper Type: Group list
   • Group attribute name: member
   • Friendly Name: Leave empty
   • SAML Attribute Name: Basic
   • Single Group Attribute: ON
   • Full group path: OFF
5. Since Rancher needs a private and public certificate to sign the messages, you need to export the just created KeyCloak client https://rancher.example.com/v1-saml/keycloak/saml/metadata as JSON in order to get the private private and public certificate from it.
   1. Navigate to the clients overview https://keycloak.example.com/auth/admin/master/console/#/realms/master/clients and click on Export on the Rancher client.
   2. Now open the just downloaded JSON file and search the attributes saml.signing.certificate and saml.signing.private.key. Save them to two separate files:
      1. rancher-client-public-cert.crt

      -----BEGIN CERTIFICATE-----
      <your-saml.signing.certificate-value-here>
      -----END CERTIFICATE-----
      

      2. rancher-client-private-cert.key

      -----BEGIN RSA PRIVATE KEY-----
      <your-saml.signing.private.key-value-here>
      -----END RSA PRIVATE KEY-----
      

6. Last but not least, you need to get the SAML Descriptior XML file.
   1. Access https://keycloak.example.com/auth/realms/master/protocol/saml/descriptor and save this XML content to a file called keycloak-metadata.xml.
   2. Since Rancher do not understand the EntitiesDescriptor tags (https://rancher.com/docs/rancher/v2.x/en/admin-settings/authentication/keycloak/#keycloak-6-0-0-idpssodescriptor-missing-from-options), 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:

      <EntitiesDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Name="urn:keycloak">
        <EntityDescriptor entityID="https://keycloak.example.com/auth/realms/master">
          <IDPSSODescriptor ......
            .....
          </IDPSSODescriptor>
        </EntityDescriptor>
      </EntitiesDescriptor>
      

      2. To this:

      <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.example.com/auth/realms/master">
        <IDPSSODescriptor ......
            .....
        </IDPSSODescriptor>
      </EntityDescriptor>
      

   3. Save and close the keycloak-metadata.xml file.
7. Now it's time to create groups inside KeyCloak (https://keycloak.example.com/auth/admin/master/console/#/realms/master/groups), which you afterwards would like to permit on Rancher. In our example:
   1. Admin group for all KeyCloak users which should have full access on Rancher:
      • Name: rancher-admins
   2. User group for all KeyCloak users which should only have basic user access:
      • Name: rancher-student
8. 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 regarding user (https://keycloak.example.com/auth/admin/master/console/#/realms/master/users) -> 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.
9. 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: member (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-private-cert.key
   • CA Certificate: rancher-client-public-cert.crt
   • Metadata XML: keycloak-metadata.xml
4. Click on Save and a small window should open which redirects you to the KeyCloak Login mask. Enter the KeyCloak credentials and if everything was configured properly, the small window should close back again and you should 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 should 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 should be good to go.

Test the KeyCloak login in a incognito browser window by accessing https://rancher.example.com/ and clicking on Log In with KeyCloak (you should then be redirected to the KeyCloak authentication site (https://keycloak.example.com/auth/realms/master/protocol/saml)).

Possible Problems and Solutions

Please check that pop up windows work in your browser.

https://rancher.com/docs/rancher/v2.x/en/admin-settings/authentication/keycloak/#keycloak-error-we-re-sorry-invalid-requester

• Check your Keycloak log.
• If the log displays request validation failed: org.keycloak.common.VerificationException: SigAlg was null, set Client Signature Required to OFF in your Keycloak client.

Helpful GitHub Issues

• rancher/rancher#16539
• rancher/rancher#26404