Authentication & Authorization

​

Overview of the Flow

​

Step-by-Step Breakdown

1. Client Initiates Request & Authentication (Client-Side):
   • The Federation Client (e.g., esi-cli or another ESE instance) prepares to request a secret from the Federation Server.
   • It retrieves its own Kubernetes Service Account (SA) token. This token is a JSON Web Token (JWT) signed by the client’s Kubernetes cluster.
   • It also retrieves its cluster’s CA certificate (the one that signed the keys for its token issuer’s JWKS endpoint).
   • The client sends an HTTP request to the appropriate Federation Server API endpoint (e.g., /secretstore/... or /generators/...).
   • Authentication Data Sent:
     • The SA token is included in the Authorization: Bearer <token> HTTP header.
     • The client cluster’s CA certificate (base64 encoded) is typically sent in the request body, often as part of a JSON payload like {"ca.crt": "<base64_encoded_ca_cert>"}.
2. Server Receives Request & Validates Token (Server-Side):
   • The Federation Server receives the request.
   • JWKS URI Construction: It extracts the issuer claim from the received JWT. Using this issuer URL and the provided client ca.crt, the Federation Server constructs the JWKS (JSON Web Key Set) URI for the client cluster. The ca.crt is crucial for the Federation Server to trust the client cluster’s OIDC discovery endpoint (where the JWKS is published).
   • JWKS Fetch & Signature Validation: The Federation Server securely fetches the public keys (JWKS) from the client cluster’s issuer. It then uses these public keys to validate the signature of the SA token. If the signature is invalid, the request is rejected (Authentication Failed).
3. Server Performs Authorization (Server-Side):
   • If the token’s signature is valid (Authentication Succeeded), the Federation Server proceeds to authorization.
   • It extracts the issuer (e.g., https://kubernetes.default.svc.cluster.local of the client) and subject (e.g., system:serviceaccount:client-namespace:client-sa-name) claims from the validated token.
   • Matching Authorization CR: The server searches for Authorization Custom Resources defined on its own cluster.
     • It looks for an Authorization CR where spec.subject.issuer and spec.subject.subject exactly match the claims from the client’s token.
   • Verifying KubernetesFederation Link: It checks that the matched Authorization CR’s spec.federationRef.name points to a valid KubernetesFederation CR. The url in this KubernetesFederation CR should correspond to the client cluster whose JWKS URI was used for token validation. This ensures the authorization rule is indeed for the authenticated cluster.
   • Checking Permissions: If a matching and valid Authorization CR is found, the server checks if the resource requested by the client (e.g., a specific ClusterSecretStore name or a Generator name/kind/namespace) is listed in the allowedClusterSecretStores or allowedGenerators sections of that Authorization CR.
   • If no matching Authorization CR is found, or if the requested resource is not permitted, the request is rejected (Authorization Failed).
4. Secret Retrieval & Response (Server-Side):
   • If both authentication and authorization are successful, the Federation Server proceeds to fulfill the request.
   • It uses its internal External Secrets Operator mechanisms to fetch the secret data from the permitted ClusterSecretStore or to execute the permitted Generator (using its own credentials to access backend systems like Vault, GCP SM, etc.).
   • The retrieved or generated secret data is then packaged into an HTTP response and sent back to the Federation Client.
5. Client Receives Secret (Client-Side):
   • The Federation Client receives the secret data and processes it (e.g., esi-cli injects it into the environment or files).