Skip to content

OIDC authentication

By default, access to a Kluster is done with the administrator kubeconfig. To give access to several users without sharing this file, you can configure the Kluster to authenticate users with your own OpenID Connect (OIDC) identity provider, such as Keycloak, Dex, GitLab or Microsoft Entra ID.

Users then log in with their own identity, and their permissions inside the Kluster are managed with Kubernetes RBAC.

Prerequisites

  • A Kluster. See Create a Kluster.
  • kubectl 1.30 or later.
  • An OIDC client created on your identity provider, with:
    • its issuer URL, for example https://auth.example.com/realms/my-realm. It must be reachable from the Internet.
    • its client ID
    • http://localhost:8000 registered as a redirect URI (used by kubelogin)

Settings

The OIDC settings are passed to the Kubernetes API server:

Setting API server flag Description Example
Issuer URL --oidc-issuer-url URL of your identity provider. Required. https://auth.example.com/realms/my-realm
Client ID --oidc-client-id ID of the OIDC client. Required. kubernetes
Username claim --oidc-username-claim Claim used as the Kubernetes username: sub, email, name, upn or preferred_username. email
Username prefix --oidc-username-prefix Prefix added to usernames, to avoid conflicts with other users. oidc:
Groups claim --oidc-groups-claim Claim used as the Kubernetes groups. groups
Groups prefix --oidc-groups-prefix Prefix added to group names. oidc:
Required claim --oidc-required-claim key=value pairs, separated by commas, that must be present in the token. hd=example.com
Signing algorithm --oidc-signing-algs RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 or PS512. RS256
CA certificate PEM certificate of your identity provider, if it is not signed by a public certificate authority.

Note

Claim and scope names depend on your identity provider. For example, GitLab puts the groups in the groups_direct claim and has no groups scope: use groups_direct as groups claim, and drop --oidc-extra-scope=groups from the kubelogin command below.

Note

When a prefix is set, it is part of the user and group names seen by Kubernetes. With oidc: as groups prefix, the developers group of your identity provider becomes oidc:developers in the Kluster.

Configure OIDC on the Kluster

  1. Open your Kluster in the Manager.
  2. Go to the OIDC settings.
  3. Fill in the settings described above.
  4. Save. The control plane is reconfigured within a few minutes.

Add an apiserver.oidc block to the infomaniak_kaas resource:

resource "infomaniak_kaas" "kluster" {
  # ...

  apiserver = {
    oidc = {
      issuer_url      = "https://auth.example.com/realms/my-realm"
      client_id       = "kubernetes"
      username_claim  = "email"
      username_prefix = "oidc:"
      groups_claim    = "groups"
      groups_prefix   = "oidc:"
      signing_algs    = "RS256"
      # Only if your identity provider uses a private CA
      # ca            = file("ca.crt")
    }
  }
}

curl -s -X PATCH \
  -H "Authorization: Bearer $INFOMANIAK_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.infomaniak.com/1/public_clouds/$PUBLIC_CLOUD_ID/projects/$PROJECT_ID/kaas/$KAAS_ID/apiserver" \
  -d '{
        "apiserver_params": {
          "--oidc-issuer-url": "https://auth.example.com/realms/my-realm",
          "--oidc-client-id": "kubernetes",
          "--oidc-username-claim": "email",
          "--oidc-username-prefix": "oidc:",
          "--oidc-groups-claim": "groups",
          "--oidc-groups-prefix": "oidc:",
          "--oidc-signing-algs": "RS256"
        }
      }'

If your identity provider uses a private CA, add its PEM certificate in the oidc_ca field.

Give permissions to users

OIDC only authenticates users: by default they have no permission on the Kluster. Using the administrator kubeconfig, bind a role to a user or to a group of your identity provider.

For example, give read-only access on the whole Kluster to the developers group, with the oidc: groups prefix:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: developers-view
subjects:
  - kind: Group
    name: oidc:developers
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f developers-view.yaml

Log in as a user

Users authenticate with the kubelogin plugin for kubectl.

  1. Install kubelogin:

    # Homebrew
brew install kubelogin
# Krew
kubectl krew install oidc-login

  2. Add a user to the kubeconfig, using the same issuer URL and client ID as configured on the Kluster:

    kubectl config set-credentials oidc \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-interactive-mode=IfAvailable \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://auth.example.com/realms/my-realm \
  --exec-arg=--oidc-client-id=kubernetes \
  --exec-arg=--oidc-extra-scope=email \
  --exec-arg=--oidc-extra-scope=groups

    If your OIDC client is confidential, also add --exec-arg=--oidc-client-secret=<secret>.

  3. Use it:

    kubectl --user=oidc get pods -A

    A browser window opens to log in to your identity provider. The token is then cached and refreshed automatically.

Tip

Once OIDC works, share with your users a kubeconfig that only contains the oidc user, and keep the administrator kubeconfig for break-glass access.