Skip to content

Rancher SSO Support

Keycloak Setup

Create a client

  • Log in to the Keycloak Admin Console at https://auth.virtomat.net/auth/admin
  • Use your admin credentials to log in.
  • In the left sidebar, click realms drop-down box and then Create Realm.
  • Enter a name for your realm (e.g., rancher) and click Create.
  • Inside your newly created realm, navigate to Clients on the left sidebar.
  • Click on Create Client to add a new client

General Settings

Field Value
Client Type OpenID Connect
Client ID rancher

Capability Config

Field Value Details
Client Authentication: On (to enable confidential access type)
Standard Flow Enabled: Yes
Implicit Flow Enabled: No
Direct Access Grants Enabled: No
Service Accounts Enabled: No

Login Settings

Field Value
Root URL: https://rancher.virtomat.dev
Home URL: https://rancher.virtomat.dev
Valid Redirect URIs: https://rancher.virtomat.dev/verify-auth
Valid Post Logout Redirect URIs: https://rancher.virtomat.dev/*
Web Origins: https://rancher.virtomat.dev
Admin URL: (optional, not needed)

Create a user

  • In the left sidebar, click Users.
  • Click Add User and fill in the details
  • Click Save.
Field Value
Email verified: On
Username: john.doe@virtomat.net
Email: john.doe@virtomat.net
First Name: John
Last Name: Doe
  • Click on the Credentials tab.
  • Set a password for the user and make sure to disable the Temporary option.
  • Click Save.

Create mappers

  • Go to Client Scopes from the left-hand menu.
  • Click on Create in the Client Scopes section.
Field Value
Name: rancher
Description: Scope for Rancher OIDC mappers
Protocol: openid-connect
  • Navigate to the Mappers tab
  • Click Create to add a new mapper
Field Value
Name: Groups Mapper
Mapper Type: Group Membership
Token Claim Name: groups
Full group path: Off
Add to ID token: Off
Add to access token: Off
Add to lightweight access token: Off
Add to userinfo: On
Add to token introspection: On
Field Value
Name: Group Path
Mapper Type: Group Membership
Token Claim Name: full_group_path
Full group path: On
Add to ID token: Off
Add to access token: Off
Add to lightweight access token: Off
Add to userinfo: On
Add to token introspection: On
Field Value
Name: Client Audience
Mapper Type: Audience
Included Client Audience: rancher
Add to ID token: Off
Add to access token: On
Add to lightweight access token: Off
Add to token introspection: On

Once the mappers have been created under the client scope, assign this client scope to the rancher client:

  • Go back to the Clients section, select the rancher client.
  • In the Client settings for rancher, navigate to the Client Scopes tab.
  • Click Add Client Scope.
  • Select rancher and save.

Rancher Setup

  • Access your Rancher at https://rancher.virtomat.dev
  • Log in using your admin credentials.
  • Go to Global Settings → Users & Authentication → Auth Provider.
  • Choose Keycloak (OIDC) from the list of identity providers.
  • Fill in the required information:
Field Value
Client ID rancher
Client Secret Lbs6pHYTTfBOohwl374TVASVS16Oug5q
URL https://auth.virtomat.net
Realm rancher

Warning

It didn't work for me using the generated values (Generate options)

Double check values and use Specify options if not correct:

Field Value
Client ID rancher
Client Secret Lbs6pHYTTfBOohwl374TVASVS16Oug5q
Rancher URL https://rancher.virtomat.dev/verify-auth
Issuer https://auth.virtomat.net/realms/rancher
Auth Endpoint https://auth.virtomat.net/realms/rancher/protocol/openid-connect/auth

Configure who should be able to login and use Rancher

  • Allow any valid user
    • This option means that any user with valid credentials in Keycloak can log in to Rancher.
    • It allows broad access: any user in your Keycloak realm who authenticates successfully can log into Rancher.
    • This is useful if you want to grant basic access to anyone within your organization or realm, and then you can assign specific roles and permissions after they log in.
  • Allow members of clusters and projects,plus authorized users & groups
    • This option restricts access to only users who are explicitly assigned to clusters or projects in Rancher.
    • Users who are not members of any cluster or project will be denied access, even if they have valid Keycloak credentials.
    • This is useful for more restricted environments where you want to ensure that only users involved in specific clusters or projects can log in.
  • Restrict access to only the authorized users & groups
    • This is the most restrictive option, where only specific predefined users or groups from Keycloak will be able to access Rancher.
    • You would need to define these authorized users or groups in Rancher, ensuring that only selected individuals or teams can log in.
    • This option is best for scenarios where strict access control is needed and only specific people or roles are allowed to log in to Rancher.

🤔 TODO: We should consider group based access (3rd option)

Disable local login (optional) 

ubuntu@office-infra$ kubectl -n cattle-system get authconfigs.management.cattle.io local -o yaml
apiVersion: management.cattle.io/v3
enabled: true
kind: AuthConfig
metadata:
  annotations:
    management.cattle.io/auth-provider-cleanup: unlocked
  creationTimestamp: "2024-09-20T13:51:16Z"
  generation: 2
  labels:
    cattle.io/creator: norman
  name: local
  resourceVersion: "9146977"
  uid: 5090864a-57ca-4506-9a71-680892eb78bf
status:
  conditions:
  - status: "True"
    type: SecretsMigrated
type: localConfig
Change enabled: false and save. Then restart rancher. 
kubectl -n cattle-system rollout restart deployment rancher

Additional Permissions

Before Rancher can communicate properly with Keycloak to refresh user attributes and search for users or groups, the Rancher client in Keycloak needs limited read-only permissions through its service account. Without these permissions, Rancher logs repeated "permission denied 403" errors when trying to access Keycloak's Admin API.

Configure Service Account Roles

  1. Open the Keycloak Admin Console at https://auth.virtomat.dev/admin and log in with a realm admin account

  2. Go to Clients and open the rancher client used for OIDC authentication

  3. In the client settings page, check the box named "Service Accounts Roles" and save. This enables a special technical user called service-account-rancher that Rancher will use for API calls

  4. After saving, a new tab called "Service Account Roles" appears at the top of the client page. Open it

  5. Click the "Assign Role" button. In the search dialog, type view-users. Select the role that belongs to the client realm-management and assign it

  6. Repeat the same for the role query-users from the same realm-management client

  7. Optionally, if Rancher is configured to use Keycloak groups, also assign query-groups from realm-management

  8. Verify that the assigned roles list shows:

    • realm-management / view-users
    • realm-management / query-users
    • realm-management / query-groups (optional)

Restart Rancher

  1. Go to the Kubernetes cluster where Rancher runs and restart Rancher with the command: 

    kubectl -n cattle-system rollout restart deploy/rancher

  2. After 30 to 60 seconds, check the logs with: 

    kubectl -n cattle-system logs deploy/rancher --since=5m | grep keycloak
    There should be no more "permission denied 403" errors

Info

This prerequisite gives Rancher the minimum read-only access it needs in Keycloak without granting any administrative privileges.