Workload Identity for Kubernetes and Amazon EKS

A Kubernetes pod can get a service account token with a custom audience as a projected volume. Dodo Payments trusts this token through a kubernetes provider. Use this type for Amazon EKS also. Do not use the aws type for EKS.

Provider Settings

Setting	Value
Provider type	`kubernetes`
Issuer	The issuer of your cluster, for example `https://oidc.eks.<region>.amazonaws.com/id/<id>` on EKS
Audience	Must be `https://live.dodopayments.com` or `https://test.dodopayments.com`
Replay protection	Not enforced. All processes in the pod read the same token until the kubelet writes a new one.
JWT lifetime	24 hours or less.

Dodo Payments must be able to get the discovery document and the JWKS of the issuer over HTTPS. The EKS OIDC issuer is public. For a cluster with a private issuer, use a custom provider with uploaded keys. Refer to Custom OIDC. To find the issuer of an EKS cluster, run:

aws eks describe-cluster --name my-cluster \
  --query "cluster.identity.oidc.issuer" --output text

Required Claims

The mapping must pin sub to one service account:

[
  { "claim": "sub", "value": "system:serviceaccount:payments:billing-worker" }
]

Conditions read top-level claims only. The namespace and the pod are in the kubernetes.io object, thus pin them through sub.

Add the egress IPs of the cluster, for example the NAT gateway IPs, to the allowed_cidrs of the mapping. A stolen token file then cannot do an exchange from another network.

Pod Configuration

Mount a projected service account token with the Dodo Payments audience, and point DODO_PAYMENTS_IDENTITY_TOKEN_FILE to it:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: billing-worker
  namespace: payments
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: billing-worker
  namespace: payments
spec:
  replicas: 2
  selector:
    matchLabels:
      app: billing-worker
  template:
    metadata:
      labels:
        app: billing-worker
    spec:
      serviceAccountName: billing-worker
      containers:
        - name: worker
          image: ghcr.io/acme/billing-worker:latest
          env:
            - name: DODO_PAYMENTS_IDENTITY_PROVIDER_ID
              value: wip_...
          volumeMounts:
            - name: dodo-token
              mountPath: /var/run/secrets/tokens
              readOnly: true
      volumes:
        - name: dodo-token
          projected:
            sources:
              - serviceAccountToken:
                  path: dodo-token
                  audience: https://live.dodopayments.com
                  expirationSeconds: 3600

The kubelet writes a new token when the token is older than 80% of its life. With expirationSeconds: 3600, this occurs after about 48 minutes. The SDK reads the file again for each exchange.

SDK Usage

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  environment: 'live_mode',
  workloadIdentity: {
    identityProviderId: process.env.DODO_PAYMENTS_IDENTITY_PROVIDER_ID,
    provider: DodoPayments.workloadIdentity.kubernetes(),
  },
});

import os
from dodopayments import DodoPayments
from dodopayments.workload_identity import WorkloadIdentity, kubernetes

client = DodoPayments(
    environment="live_mode",
    workload_identity=WorkloadIdentity(
        identity_provider_id=os.environ["DODO_PAYMENTS_IDENTITY_PROVIDER_ID"],
        provider=kubernetes(),
    ),
)

client := dodopayments.NewClient(
	option.WithEnvironmentLiveMode(),
	option.WithWorkloadIdentity(option.WorkloadIdentity{
		IdentityProviderID: os.Getenv("DODO_PAYMENTS_IDENTITY_PROVIDER_ID"),
		Provider:           workloadidentity.Kubernetes(""),
	}),
)

The kubernetes() helper reads /var/run/secrets/tokens/dodo-token. To use a different path, give the path to the helper. Refer to SDK Usage for the other languages.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Workload Identity for Kubernetes and Amazon EKS

Provider Settings

Required Claims

Pod Configuration

SDK Usage

​Provider Settings

​Required Claims

​Pod Configuration

​SDK Usage

Provider Settings

Required Claims

Pod Configuration

SDK Usage