Cluster SSO by provider¶

Which names each kind of cluster sign-in gives users and groups inside the cluster, and which identity template and native role groups fit it. Why these two pieces exist is in kubelatch on top of the SSO you already have.

Before you start¶

• Use the names the cluster really uses. What this cluster knows, on the cluster's page, lists the groups and users its bindings name and what each is bound to. For your own name, run kubectl auth whoami with the cluster's own kubeconfig.
• {email} and {oidc_subject} come from each account's identity at kubelatch's OIDC provider. For them to match the cluster's names, kubelatch and the cluster trust the same identity provider, and the cluster reads the verified e-mail for {email}, or the claim of OIDC_SUBJECT_CLAIM for {oidc_subject}.
• An account with no identity at the provider gets a 403 on that cluster until it signs in once with the provider (Accounts that can't be named).

k3s, kubeadm and other clusters with their own OIDC¶

The apiserver trusts an OpenID Connect provider through its --oidc-* flags, or an AuthenticationConfiguration file given with --authentication-config:

On k3s each flag goes through --kube-apiserver-arg, without its leading dashes: --kube-apiserver-arg=oidc-username-claim=email.

A cluster set up with --oidc-username-claim=email --oidc-username-prefix=oidc: --oidc-groups-claim=groups --oidc-groups-prefix=oidc: names Ana oidc:ana@acme.com and her groups oidc:developers, oidc:platform-admins. Then:

• Template: oidc:{email}.
• Native roles: oidc:developers and the other groups as the cluster names them, prefix included.

With the username claim left at sub, the template is the prefix followed by {oidc_subject}, and kubelatch's OIDC_SUBJECT_CLAIM is sub too.

EKS¶

With access entries or aws-auth, IAM principals get a Kubernetes username and a list of groups (kubernetesGroups, or groups in aws-auth). For IAM Identity Center the username is the session's ARN, not the e-mail.

• Template: keep user:{login}.
• Native roles: the groups your RoleBindings and ClusterRoleBindings name, such as eks-developers.

With an associated OIDC identity provider, pick the template and the groups as for k3s, with the prefixes set in the association.

AKS with Microsoft Entra ID¶

The cluster's bindings name Entra groups by their object id, a GUID such as 5d0f7b6e-….

• Native roles: those object ids. Use the role's name and description to say which group each one is.
• Template: {email}, since Entra names users by their UPN, the name they sign in with, by default. Use {oidc_subject} with OIDC_SUBJECT_CLAIM=oid only when the cluster names users by object id.

With Azure RBAC for Kubernetes Authorization, Azure role assignments decide access instead of bindings, so the cluster has no bindings for kubelatch to read.

GKE¶

GKE names people by their Google account e-mail, and with Google Groups for RBAC groups by the group's e-mail.

• Template: {email}, with kubelatch signing people in through Google Workspace.
• Native roles: the Google Groups your bindings name, such as gke-devs@acme.com.

DigitalOcean (DOKS)¶

DOKS names people by their DigitalOcean account e-mail and their team role as a group do-role-name:<role>.

• Template: {email}.
• Native roles: those groups.

At a glance¶

Whatever the provider, a group or a user that the cluster binds to cluster-admin follows the 8-hour rule (The name carries everything the cluster binds to it).