OpenID Connect integration#
kubectl to access Kubernetes clusters. By default
kubectl uses a certificate to authenticate to the Kubernetes API. This means that when multiple developers need to access a cluster, the certificate needs to be shared. Sharing the credentials to access a Kubernetes cluster presents a significant security problem. Compromise of the certificate is very easy and the consequences can be catastrophic.
In this tutorial, we walk through how to set up your Kubernetes cluster to add Single Sign-On support for kubectl using OpenID Connect (OIDC).
OpenID Connect based authentication#
OpenID Connect can be enabled by modifying k0s configuration (using extraArgs).
Configuring k0s: overview#
There are list of arguments for the kube-api that allows us to manage OIDC based authentication
||URL of the provider which allows the API server to discover public signing keys. Only URLs which use the
||If the discovery URL is
||A client id that all tokens must be issued for.||kubernetes||Yes|
||JWT claim to use as the user name. By default
||Prefix prepended to username claims to prevent clashes with existing names (such as
||JWT claim to use as the user's group. If the claim is present it must be an array of strings.||groups||No|
||Prefix prepended to group claims to prevent clashes with existing names (such as
||A key=value pair that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. Repeat this flag to specify multiple claims.||
||The path to the certificate for the CA that signed your identity provider's web certificate. Defaults to the host's root CAs.||
To set up bare minimum example we need to use:
Configuring k0s: prerequisites#
You will require:
Please, refer to providers configuration guide or your selected OIDC provider's own documentation (we don't cover all of them in k0s docs).
apiVersion: k0s.k0sproject.io/v1beta1 kind: ClusterConfig spec: api: extraArgs: oidc-issuer-url: <issuer-url> oidc-client-id: <client-id> oidc-username-claim: email # we use email token claim field as a username
Use the configuration as a starting point. Continue with configuration guide for finishing k0s cluster installation.
OpenID Connect based authorisation#
There are two alternative options to implement authorization
Provider based role mapping#
Please refer to the providers configuration guide. Generally speaking, using the
oidc-groups-claim argument let's you specify which token claim is used a list of RBAC roles for a given user. You still need somehow sync up that data between your OIDC provider and kube-api RBAC system.
Manual roles management#
To use manual role management for each user you will need to create a role and role-binding for each new user within k0s cluster. The role can be shared for all the users. Role example:
--- kind: Role apiVersion: rbac.authorization.k8s.io/v1 metadata: namespace: default name: dev-role rules: - apiGroups: ["*"] resources: ["*"] verbs: ["*"]
kind: RoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: name: dev-role-binding subjects: - kind: User name: <provider side user id> roleRef: kind: Role name: dev-role apiGroup: rbac.authorization.k8s.io
The provided Role example is an all-inclusive and comprehensive example and should be tuned up to your actual requirements.
NB: it's not safe to provide full content of the
/var/lib/k0s/pki/admin.conf to the end-user. Instead, create a user specific kubeconfig with limited permissions.
The authorization side of the kubeconfig management is described in provider specific guides. Use
/var/lib/k0s/pki/admin.conf as a template for cluster specific kubeconfig.
OAuth2 spec Kubernetes authorization system (RBAC) Kubernetes authenticating system