[v17] Add support for Kubernetes OIDC joining

[timothyb89]

⚠️ This is an unclean backport and should be reviewed as a standalone PR ⚠️

This PR adds Kubernetes OIDC joining to v17, as originally added in #57538. However, as we've since switched OIDC libraries in v18, the change could not be cleanly backported: this depends on #54939, but in addition to being a poor backport candidate, depends on a new version of zitadel/oidc/v3 that I'm wary of updating in v17 unnecessarily.

Instead, I've ended up directly including some of the zitadel/oidc related functions that this particular join method needs, and left some notes to indicate that, should #54939 be backported in full, we should remove the duplicated functionality.

changelog: Add new oidc joining mode for Kubernetes delegated joining to support providers that can be configured to provide public OIDC endpoints, like EKS, AKS, and GKE.

---

To use, you'll need a Kubernetes cluster that issues OIDC tokens from an issuer with a public OpenID-compatible endpoint, like Amazon EKS. To check and resolve the right issuer value, run this command:

$ curl $(kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer')/.well-known/openid-configuration | jq -r '.issuer'
https://oidc.eks.us-west-2.amazonaws.com/id/my-cluster

This attempts to resolve the issuer from your local machine; providers like EKS will return an OIDC config pointing to internal URLs when used on an internal network. If your provider's OIDC endpoint isn't available, the curl call will fail, in which case this method won't work.

Once you've determined the issuer, create a join token:

kind: token
metadata:
  name: kubernetes-oidc-example
spec:
  bot_name: kubernetes-oidc-example
  join_method: kubernetes
  kubernetes:
    allow:
    - service_account: default:example
    oidc:
      issuer: https://oidc.eks.us-west-2.amazonaws.com/id/my-cluster
    type: oidc
  roles:
  - Bot
version: v2

You'll need to configure your Kubernetes pod to project a token with the Teleport cluster name as the configured audience, in this case we'll assume example.teleport.sh.

To project an additional token, add this to your pod spec:

spec:
  containers:
  - name: example
    # ...
    volumeMounts:
    - mountPath: /var/run/secrets/teleport-token
      name: teleport-token
  volumes:
  - name: teleport-token
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          audience: example.teleport.sh
          expirationSeconds: 600
          path: token

When joining a client (Teleport agent, tbot, etc) make sure KUBERNETES_TOKEN_PATH is set to the token in the projected mount path, e.g. /var/run/secrets/teleport-token/token.

[github-actions]

Amplify deployment status

Branch	Commit	Job ID	Status	Preview	Updated (UTC)
timothyb89/v17/kubernetes-oidc-joining	247e271	4	✅SUCCEED	timothyb89-v17-kubernetes-oidc-joining	2025-08-22 01:15:35