OIDC

OpenID Connect (OIDC) allows Kubernetes to authenticate users through external identity providers like AWS IAM, Azure AD, Google Cloud Identity, or any OIDC-compatible provider. This enables single sign-on (SSO) and centralized user management.

What is OIDC?

OIDC is an authentication layer built on top of OAuth 2.0. It allows Kubernetes to verify user identity by trusting tokens issued by an external identity provider (IdP). Instead of managing user credentials directly, Kubernetes delegates authentication to your organization’s existing identity system.

Think of it like using your company badge to access different buildings—the badge is issued by your company (the IdP), and each building (Kubernetes) trusts your company’s badge system.

How OIDC Works with Kubernetes

sequenceDiagram participant User participant Browser participant IdP as Identity Provider participant K8s as Kubernetes API User->>Browser: Access kubectl/kubectl Browser->>IdP: Redirect to login IdP->>User: Authenticate User->>IdP: Provide credentials IdP->>Browser: Return ID token Browser->>K8s: API request with token K8s->>IdP: Verify token signature IdP-->>K8s: Token valid K8s->>K8s: Check RBAC permissions K8s-->>Browser: API response

The flow:

User authenticates with the identity provider
IdP issues an ID token (JWT)
User includes the token in Kubernetes API requests
Kubernetes validates the token with the IdP
Kubernetes extracts user identity and checks RBAC permissions

Configuring OIDC

To enable OIDC authentication, configure the API server with OIDC parameters:

# /etc/kubernetes/manifests/kube-apiserver.yaml
apiVersion: v1
kind: Pod
metadata:
  name: kube-apiserver
  namespace: kube-system
spec:
  containers:
  - name: kube-apiserver
    command:
    - kube-apiserver
    - --oidc-issuer-url=https://accounts.google.com
    - --oidc-client-id=YOUR_CLIENT_ID
    - --oidc-username-claim=email
    - --oidc-groups-claim=groups
    - --oidc-ca-file=/etc/ssl/certs/ca-certificates.crt

Key Parameters

--oidc-issuer-url - The URL of the OIDC issuer (e.g., https://accounts.google.com)
--oidc-client-id - The client ID registered with the identity provider
--oidc-username-claim - Which claim to use as the username (default: sub)
--oidc-groups-claim - Which claim contains group membership
--oidc-ca-file - CA certificate for validating the IdP’s TLS certificate

AWS IAM Integration

Setting Up AWS IAM as OIDC Provider

Create OIDC Identity Provider in AWS IAM:

aws iam create-open-id-connect-provider \
  --url https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D304 \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 9e99a48a9960b14926bb7f3b02e22da2b0ab7280

Configure EKS API Server:

The EKS API server is pre-configured for OIDC. You need to associate an OIDC provider:

eksctl utils associate-iam-oidc-provider \
  --cluster my-cluster \
  --region us-west-2 \
  --approve

Create IAM Role and Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/oidc.eks.us-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D304"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.us-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D304:sub": "system:serviceaccount:production:my-app"
        }
      }
    }
  ]
}

Use the Role in Kubernetes:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app
  namespace: production
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/my-app-role

Azure AD Integration

Configuring Azure AD

Register Application in Azure AD:

Create an app registration and note the:

Application (client) ID
Directory (tenant) ID
OIDC issuer URL: https://login.microsoftonline.com/TENANT_ID/v2.0

Configure API Server:

- --oidc-issuer-url=https://login.microsoftonline.com/TENANT_ID/v2.0
- --oidc-client-id=YOUR_CLIENT_ID
- --oidc-username-claim=email
- --oidc-groups-claim=groups

Get Token:

az login
az account get-access-token --resource https://management.azure.com/

Use Token with kubectl:

kubectl config set-credentials azure-user \
  --token=$(az account get-access-token --query accessToken -o tsv)

Google Cloud Identity Integration

Setting Up Google Cloud

Create OAuth 2.0 Credentials:

In Google Cloud Console:

Go to APIs & Services > Credentials
Create OAuth 2.0 Client ID
Note the Client ID and Client Secret

Configure API Server:

- --oidc-issuer-url=https://accounts.google.com
- --oidc-client-id=YOUR_CLIENT_ID.apps.googleusercontent.com
- --oidc-username-claim=email
- --oidc-groups-claim=groups

Authenticate:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
kubectl config set-credentials gcp-user \
  --auth-provider=oidc \
  --auth-provider-arg=idp-issuer-url=https://accounts.google.com \
  --auth-provider-arg=client-id=YOUR_CLIENT_ID \
  --auth-provider-arg=client-secret=YOUR_CLIENT_SECRET \
  --auth-provider-arg=id-token=YOUR_ID_TOKEN \
  --auth-provider-arg=refresh-token=YOUR_REFRESH_TOKEN

Generic OIDC Provider

For any OIDC-compatible provider:

1. Obtain OIDC Discovery Document

curl https://your-idp.com/.well-known/openid-configuration

This returns the issuer URL, authorization endpoint, token endpoint, etc.

2. Configure API Server

- --oidc-issuer-url=https://your-idp.com
- --oidc-client-id=YOUR_CLIENT_ID
- --oidc-client-secret=YOUR_CLIENT_SECRET  # Optional
- --oidc-username-claim=preferred_username
- --oidc-groups-claim=groups

3. Configure kubectl

kubectl config set-credentials oidc-user \
  --auth-provider=oidc \
  --auth-provider-arg=idp-issuer-url=https://your-idp.com \
  --auth-provider-arg=client-id=YOUR_CLIENT_ID \
  --auth-provider-arg=client-secret=YOUR_CLIENT_SECRET \
  --auth-provider-arg=id-token=YOUR_ID_TOKEN \
  --auth-provider-arg=refresh-token=YOUR_REFRESH_TOKEN

Token Validation

Kubernetes validates OIDC tokens by:

Checking signature - Verifies the token is signed by the trusted IdP
Checking expiration - Ensures the token hasn’t expired
Checking issuer - Verifies the issuer matches the configured issuer URL
Extracting claims - Reads username and groups from token claims

RBAC Integration

After OIDC authentication, Kubernetes uses the username and groups from the token for RBAC:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: developers-binding
subjects:
- kind: Group
  name: [email protected]  # Group from OIDC token
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: edit
  apiGroup: rbac.authorization.k8s.io

Or bind to a specific user:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: alice-binding
  namespace: production
subjects:
- kind: User
  name: [email protected]  # Username from OIDC token
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: developer
  apiGroup: rbac.authorization.k8s.io

Best Practices

Use groups, not individual users - Easier to manage permissions
Set appropriate token lifetime - Balance security and user experience
Use HTTPS - Always use TLS for OIDC endpoints
Validate CA certificates - Use --oidc-ca-file to verify IdP certificates
Monitor authentication failures - Track failed OIDC authentication attempts
Rotate client secrets - Regularly update OIDC client credentials

Troubleshooting

Verify OIDC configuration:

# Check API server configuration
kubectl get pod kube-apiserver -n kube-system -o yaml | grep oidc

Test token validation:

# Decode JWT token to see claims
echo "YOUR_TOKEN" | cut -d. -f2 | base64 -d | jq

Check user identity:

# See what user kubectl is authenticated as
kubectl config view --minify -o jsonpath='{.users[0].name}'

# Test permissions
kubectl auth can-i get pods --all-namespaces

Common Issues

Token expired - Refresh the token or re-authenticate
Wrong issuer URL - Verify --oidc-issuer-url matches IdP configuration
Missing groups claim - Ensure --oidc-groups-claim matches the claim name in your token
CA certificate issues - Verify --oidc-ca-file points to correct CA certificate