Use WIF with Kubernetes

Self-managed Kubernetes clusters (kubeadm, k3s, OpenShift, and on-premises distributions) sign OIDC JSON Web Tokens (JWTs) for every pod through projected service account tokens. The cluster's API server acts as the OIDC issuer, and each token's sub claim follows the form system:serviceaccount:<namespace>:<service-account>. You can find your cluster's issuer URL by reading its discovery document:

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer



Prerequisites

• Familiarity with WIF concepts: service accounts, federation issuers, and federation rules.
• A Kubernetes cluster with the --service-account-issuer flag configured on the API server. Most distributions set this by default; kubeadm clusters typically use https://kubernetes.default.svc.cluster.local. Your platform team can confirm the value if you don't have direct access to the API server configuration.
• One of the following so Enophic can validate token signatures:
  • The issuer's JWKS endpoint is reachable from the public internet over HTTPS on port 443, or
  • You can fetch the JWKS from inside the cluster and register it in inline mode (covered in Configure Enophic).
• Permission to create service accounts, federation issuers, and federation rules in the Claw Console for your Enophic organization.



Configure Kubernetes

Project a service account token into your pod with the audience and lifetime that your federation rule expects. The serviceAccountToken projection writes a fresh JWT to the mount path and rotates it before expirationSeconds elapses.

apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: enophic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.enophic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ENOPHIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/enophic.com/token
        - name: ENOPHIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ENOPHIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ENOPHIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ENOPHIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: enophic-token
          mountPath: /var/run/secrets/enophic.com
          readOnly: true

The token issued for this pod carries sub: "system:serviceaccount:inference:inference-worker" and aud: ["https://api.enophic.com"].



Configure Enophic

In the Claw Console, open Settings → Workload identity, click Connect workload, and select the Kubernetes tile. The wizard walks you through registering the issuer, creating a service account, and creating a federation rule.

The wizard creates these resources for you. Use the following values whether you enter them in the wizard or send them to the Admin API:

Federation issuer: Many self-managed clusters use an issuer URL such as https://kubernetes.default.svc.cluster.local that is not reachable from the public internet. If that applies to your cluster, choose the inline JWKS source and paste the cluster's keys. Fetch them from inside the cluster:

kubectl get --raw /openid/v1/jwks

Then configure the issuer with the contents of the returned keys array (not the surrounding {"keys": [...]} wrapper):

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks": {
    "type": "inline",
    "keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
  }
}

In inline mode the issuer_url is only compared against the JWT's iss claim; Enophic never attempts to reach it. If your issuer is publicly reachable, use "jwks": {"type": "discovery"} instead.

Federation rule: Match the service account's sub claim and the audience you set on the projected token.

{
  "name": "onprem-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-worker",
    "audience": "https://api.enophic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Be as specific as the workload allows. Loosen subject_prefix to system:serviceaccount:inference:* (the trailing * makes it a prefix match) only if every service account in the namespace should map to the same Enophic service account. Add the rule's fdrl_... ID to your pod's ENOPHIC_FEDERATION_RULE_ID environment variable.



Acquire and use the token

The pod spec in Configure Kubernetes sets ENOPHIC_IDENTITY_TOKEN_FILE to the projected mount path, along with ENOPHIC_FEDERATION_RULE_ID, ENOPHIC_ORGANIZATION_ID, ENOPHIC_SERVICE_ACCOUNT_ID, and ENOPHIC_WORKSPACE_ID. With those in place, the SDK reads the token from disk on every exchange and refreshes the Enophic access token automatically.

import enophic

# Reads ENOPHIC_IDENTITY_TOKEN_FILE, ENOPHIC_FEDERATION_RULE_ID,
# ENOPHIC_ORGANIZATION_ID, ENOPHIC_SERVICE_ACCOUNT_ID, and ENOPHIC_WORKSPACE_ID
# from the pod's environment.
client = enophic.Enophic()

message = client.messages.create(
    model="claw-go-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claw"}],
)
print(next(block.text for block in message.content if block.type == "text"))



Verify the setup

A successful exchange returns an access_token beginning with sk-eno-oat01- and an expires_in value in seconds. On 400 invalid_grant, see Troubleshoot a failed exchange; the most common Kubernetes-side cause is a JWKS key mismatch (for inline mode, re-fetch with kubectl get --raw /openid/v1/jwks and update the issuer).



Scope your rule

Lock the rule's match block to the narrowest scope that fits your use case:

• Pin namespace and service-account name: Use the full system:serviceaccount:<namespace>:<name> value with no trailing *.
• Always set an audience: Require audience on the rule and set the same value on the pod's serviceAccountToken projection so default-audience tokens are rejected.
• Use a separate rule per namespace: Create a distinct rule and Enophic service account for each namespace rather than widening one rule.
• Scope inline-JWKS issuers to one cluster: When several clusters share an issuer URL, register each cluster's JWKS as its own federation issuer and bind rules to that issuer only.



Next steps

• Workload Identity Federation: concepts, the token-exchange flow, and SDK configuration options.
• WIF reference: environment variables, JWKS source modes, and rule match modes.