Introduce support for OIDC workload identity federation (#3711)

* feat(oidc): introduce support for OIDC workload identity federation Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com> * feat(oidc): add e2e test for bearer OIDC and a kind cluster Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com> * feat(oidc): make OIDC workload identity federation its own feature Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com> * feat(oidc): move errors to the errors package Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com> * feat(oidc): fix race in cel package Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com> * feat(oidc): compile cel expressions Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com> --------- Signed-off-by: Matheus Pimenta <matheuscscp@gmail.com>
2026-06-18 05:28:07 +08:00 · 2026-01-25 05:03:53 +00:00
parent ba3436c57e
commit bf619c570e
25 changed files with 5151 additions and 52 deletions
@@ -0,0 +1,405 @@
+# OIDC Workload Identity Authentication
+
+This document describes how to configure Zot to authenticate workloads using OIDC ID tokens, enabling secret-less authentication for automated workflows.
+
+## Overview
+
+OIDC Workload Identity authentication allows workloads (e.g., Kubernetes pods, CI/CD pipelines) to authenticate to Zot using OIDC ID tokens instead of static credentials. This is similar to how cloud providers implement "workload identity" features and how Kubernetes handles external OIDC authentication.
+
+## Benefits
+
+- **Secret-less Authentication**: No need to manage static credentials
+- **Automatic Credential Rotation**: Tokens are short-lived and automatically rotated
+- **Fine-grained Access Control**: Map OIDC claims to Zot identities and groups using CEL expressions
+- **Kubernetes Native**: Works seamlessly with Kubernetes ServiceAccount tokens
+- **Multi-Provider Support**: Configure multiple OIDC issuers for different workload types (e.g. multiple clusters)
+- **Standards-based**: Uses standard OIDC protocols
+
+## Configuration
+
+### Basic Configuration
+
+Add OIDC workload identity configuration to your bearer authentication settings. The `oidc` field accepts an array of provider configurations:
+
+```json
+{
+  "http": {
+    "auth": {
+      "bearer": {
+        "realm": "zot",
+        "service": "zot-service",
+        "oidc": [
+          {
+            "issuer": "https://kubernetes.default.svc.cluster.local",
+            "audiences": ["zot"]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Configuration Options
+
+- **`issuer`** (required): The OIDC issuer URL. This is the identity provider that signs the tokens.
+  - Example: `"https://kubernetes.default.svc.cluster.local"`
+  - Example: `"https://token.actions.githubusercontent.com"`
+
+- **`audiences`** (required): List of acceptable audiences for the OIDC token. At least one must be specified.
+  - Example: `["zot", "https://zot.example.com"]`
+
+- **`claimMapping`** (optional): CEL-based configuration for validating and mapping OIDC claims.
+  - **`variables`**: List of variables to extract from claims using CEL expressions
+  - **`validations`**: List of validation rules with CEL expressions
+  - **`username`**: CEL expression to extract the username. Default: `"claims.iss + '/' + claims.sub"`
+  - **`groups`**: CEL expression to extract groups. Default: none (no groups extracted)
+
+- **`skipIssuerVerification`** (optional): Skip issuer verification (for testing only). Default: `false`.
+
+### CEL Expressions
+
+Zot uses [Common Expression Language (CEL)](https://github.com/google/cel-go) for flexible claim validation and mapping. CEL expressions have access to:
+
+- **`claims`**: The OIDC token claims as a map (e.g., `claims.sub`, `claims.email`)
+- **`vars`**: Previously extracted variables (for use in validations and username/groups expressions)
+
+#### Example CEL Expressions
+
+| Expression | Description |
+|------------|-------------|
+| `claims.sub` | Extract the subject claim |
+| `claims.email` | Extract the email claim |
+| `claims.groups` | Extract the groups claim |
+| `claims['kubernetes.io/serviceaccount/namespace']` | Extract claims with special characters |
+| `claims.repository_owner + '/' + claims.sub` | Concatenate multiple claims |
+| `claims.email.split('@')[0]` | Extract username from email |
+| `claims.org in ['allowed-org-1', 'allowed-org-2']` | Check if org is in allowed list |
+| `claims.email_verified == true` | Validate email is verified |
+
+### Complete Example
+
+In the example below, the username is mapped from both the issuer and subject
+claims to uniquely identify Kubernetes ServiceAccounts across different clusters.
+Note that `claims.iss + '/' + claims.sub` is the default username mapping if none
+is specified (so the whole `claimMapping` section could be omitted in this example).
+
+```json
+{
+  "distSpecVersion": "1.1.1",
+  "storage": {
+    "rootDirectory": "/tmp/zot"
+  },
+  "http": {
+    "address": "127.0.0.1",
+    "port": "8080",
+    "auth": {
+      "bearer": {
+        "realm": "zot",
+        "service": "zot-service",
+        "oidc": [
+          {
+            "issuer": "https://kubernetes.default.svc.cluster.local",
+            "audiences": ["zot", "https://zot.example.com"],
+            "claimMapping": {
+              "username": "claims.iss + '/' + claims.sub"
+            }
+          }
+        ]
+      }
+    },
+    "accessControl": {
+      "repositories": {
+        "**": {
+          "policies": [
+            {
+              "users": ["https://kubernetes.default.svc.cluster.local/system:serviceaccount:flux-system:source-controller"],
+              "actions": ["read", "create", "update", "delete"]
+            }
+          ]
+        }
+      }
+    }
+  },
+  "log": {
+    "level": "info"
+  }
+}
+```
+
+### Advanced Configuration with CEL Validations
+
+Use CEL expressions to validate claims and extract complex usernames:
+
+```json
+{
+  "http": {
+    "auth": {
+      "bearer": {
+        "oidc": [
+          {
+            "issuer": "https://token.actions.githubusercontent.com",
+            "audiences": ["zot"],
+            "claimMapping": {
+              "variables": [
+                {
+                  "name": "repo",
+                  "expression": "claims.repository"
+                },
+                {
+                  "name": "owner",
+                  "expression": "claims.repository_owner"
+                }
+              ],
+              "validations": [
+                {
+                  "expression": "vars.owner == 'my-org'",
+                  "message": "only my-org repositories are allowed"
+                },
+                {
+                  "expression": "claims.ref.startsWith('refs/heads/')",
+                  "message": "must be a branch reference"
+                }
+              ],
+              "username": "vars.repo",
+              "groups": "['github-actions', 'ci']"
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Multiple OIDC Providers
+
+Configure multiple OIDC providers to support different identity sources. Zot will try each provider in order until one successfully authenticates the token:
+
+```json
+{
+  "http": {
+    "auth": {
+      "bearer": {
+        "oidc": [
+          {
+            "issuer": "https://kubernetes.default.svc.cluster.local",
+            "audiences": ["zot"],
+            "claimMapping": {
+              "variables": [
+                {
+                  "name": "ns",
+                  "expression": "claims['kubernetes.io/serviceaccount/namespace']"
+                },
+                {
+                  "name": "sa",
+                  "expression": "claims['kubernetes.io/serviceaccount/service-account.name']"
+                }
+              ],
+              "username": "vars.ns + ':' + vars.sa",
+              "groups": "['k8s-workloads']"
+            }
+          },
+          {
+            "issuer": "https://token.actions.githubusercontent.com",
+            "audiences": ["zot"],
+            "claimMapping": {
+              "username": "claims.repository",
+              "groups": "['github-actions']"
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+### Kubernetes ServiceAccount Tokens
+
+When running in Kubernetes, workloads can use their ServiceAccount tokens to authenticate:
+
+```bash
+# Get the ServiceAccount token
+TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
+
+# Use it to authenticate to Zot
+curl -H "Authorization: Bearer $TOKEN" https://zot.example.com/v2/_catalog
+```
+
+### Flux Integration
+
+Flux can use Kubernetes ServiceAccount tokens to authenticate to Zot without secrets:
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: OCIRepository
+metadata:
+  name: zot-repo
+  namespace: flux-system
+spec:
+  url: oci://zot.example.com/v2/manifests
+  credentials: ServiceAccountToken
+  serviceAccountName: my-tenant-sa # optional. if omitted, defaults to the source-controller ServiceAccount
+```
+
+Note: The configuration above is currently a proposal from the Flux maintainers
+and may change until officially released. For more details, see this
+[RFC](https://github.com/fluxcd/flux2/issues/5681).
+
+### GitHub Actions
+
+GitHub Actions can use OIDC tokens to authenticate:
+
+```yaml
+- name: Login to Zot
+  run: |
+    TOKEN=$(curl -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=zot" | jq -r .value)
+    echo $TOKEN | docker login -u oauth --password-stdin zot.example.com
+```
+
+## Token Claims
+
+### Required Claims
+
+- **`iss`**: Issuer URL (must match configured issuer)
+- **`aud`**: Audience (must match one of the configured audiences)
+- **`sub`**: Subject (used as username by default)
+- **`exp`**: Expiration time
+- **`iat`**: Issued at time
+
+### Optional Claims
+
+- **`groups`**: Array of group names for authorization (requires CEL `groups` expression)
+- **`preferred_username`**: Can be used as username with CEL expression
+- **`email`**: Can be used as username with CEL expression
+- **`name`**: Can be used as username with CEL expression
+
+### Example Token Payload
+
+```json
+{
+  "iss": "https://kubernetes.default.svc.cluster.local",
+  "aud": ["zot"],
+  "sub": "system:serviceaccount:flux-system:source-controller",
+  "exp": 1705258800,
+  "iat": 1705255200,
+  "kubernetes.io/serviceaccount/namespace": "flux-system",
+  "kubernetes.io/serviceaccount/service-account.name": "source-controller"
+}
+```
+
+## Access Control
+
+Use Zot's access control policies to grant permissions based on the OIDC identity:
+
+```json
+{
+  "accessControl": {
+    "repositories": {
+      "app/**": {
+        "policies": [
+          {
+            "users": ["system:serviceaccount:prod:app-controller"],
+            "actions": ["read", "create", "update"]
+          }
+        ]
+      },
+      "**": {
+        "policies": [
+          {
+            "users": ["system:serviceaccount:default:admin"],
+            "actions": ["read", "create", "update", "delete"]
+          }
+        ],
+        "defaultPolicy": ["read"]
+      }
+    }
+  }
+}
+```
+
+## Compatibility
+
+### Traditional Bearer Authentication
+
+OIDC workload identity can coexist with traditional bearer authentication. If both are configured, Zot will try OIDC authentication first, then fall back to traditional bearer token authentication:
+
+```json
+{
+  "http": {
+    "auth": {
+      "bearer": {
+        "realm": "https://auth.myreg.io/auth/token",
+        "service": "myauth",
+        "cert": "/etc/zot/auth.crt",
+        "oidc": [
+          {
+            "issuer": "https://kubernetes.default.svc.cluster.local",
+            "audiences": ["zot"]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Other Authentication Methods
+
+OIDC workload identity is only available with bearer authentication. For other authentication methods (htpasswd, LDAP, OAuth2 for humans), continue using the existing configuration options.
+
+## Troubleshooting
+
+### Enable Debug Logging
+
+Set log level to `debug` to see detailed authentication logs:
+
+```json
+{
+  "log": {
+    "level": "debug"
+  }
+}
+```
+
+### Common Issues
+
+1. **Token verification failed**: Check that the issuer URL is correct and reachable from Zot.
+
+2. **Audience not accepted**: Ensure the token's `aud` claim matches one of the configured audiences.
+
+3. **Token expired**: OIDC tokens are typically short-lived. Ensure your workload is obtaining fresh tokens.
+
+4. **CEL expression error**: Check the CEL expression syntax. Use `claims.field` for simple fields or `claims['field-name']` for fields with special characters.
+
+5. **Validation failed**: Check that your token claims satisfy all configured validation expressions.
+
+6. **JWKS endpoint not reachable**: Verify network connectivity to the OIDC issuer's JWKS endpoint. Note: Zot lazily initializes the OIDC provider on first authentication, so startup won't fail if the issuer is temporarily unreachable.
+
+7. **No username found**: Ensure the CEL expression for username evaluates to a non-empty string. Check that the required claims exist in the token.
+
+## Security Considerations
+
+1. **Token Expiration**: Always use short-lived tokens (typically 1 hour or less).
+
+2. **Audience Validation**: Always specify audiences to prevent token reuse across services.
+
+3. **TLS**: Use TLS for all communication to protect tokens in transit.
+
+4. **Issuer Verification**: Never disable issuer verification in production.
+
+5. **Access Control**: Always configure access control policies to limit what authenticated workloads can do.
+
+6. **CEL Validations**: Use CEL validations to enforce additional security constraints (e.g., require email verification, restrict to specific organizations).
+
+## References
+
+- [OIDC Specification](https://openid.net/specs/openid-connect-core-1_0.html)
+- [CEL Language Definition](https://github.com/google/cel-spec)
+- [Kubernetes OIDC Authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens)
+- [Flux Workload Identity RFC](https://github.com/fluxcd/flux2/tree/main/rfcs/0010-multi-tenant-workload-identity)
+- [GitHub Actions OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
@@ -0,0 +1,40 @@
+{
+  "distSpecVersion": "1.1.1",
+  "storage": {
+    "rootDirectory": "/tmp/zot"
+  },
+  "http": {
+    "address": "127.0.0.1",
+    "port": "8080",
+    "auth": {
+      "bearer": {
+        "realm": "zot",
+        "service": "zot-service",
+        "oidc": [
+          {
+            "issuer": "https://kubernetes.default.svc.cluster.local",
+            "audiences": ["zot", "https://zot.example.com"],
+            "claimMapping": {
+              "username": "claims.sub"
+            }
+          }
+        ]
+      }
+    },
+    "accessControl": {
+      "repositories": {
+        "**": {
+          "policies": [
+            {
+              "users": ["system:serviceaccount:flux-system:source-controller"],
+              "actions": ["read", "create", "update", "delete"]
+            }
+          ]
+        }
+      }
+    }
+  },
+  "log": {
+    "level": "info"
+  }
+}