The External Secrets Enterprise is product suite is a premium product. It requires a specific subscription. Contact us for more information.
Setting up an External Secrets Enterprise (ESE) instance as a Federation Server involves configuring specific Custom Resources (CRDs) that define how it interacts with client clusters and what permissions clients have. The server also exposes dedicated API endpoints for clients to request secrets.

​
Custom Resource Definitions (CRDs)

The federation feature introduces two key Custom Resource Definitions that are typically applied on the Federation Server cluster.

​
1. KubernetesFederation

  • API Group: federation.external-secrets.io/v1alpha1
  • Kind: KubernetesFederation
  • Scope: Cluster
  • Purpose: Defines a named federation relationship with a client Kubernetes cluster. It essentially registers a client cluster with the Federation Server, enabling the server to validate tokens issued by that client cluster.
  • Spec Fields:
    • url (string, required): The Kubernetes API Server URL of the client cluster (e.g., https://kubeapi.client-cluster.example.com). This URL is used by the Federation Server to construct the JWKS (JSON Web Key Set) URI for the client cluster, allowing it to fetch the public keys needed to validate Service Account (SA) tokens issued by that client cluster.
Example KubernetesFederation CR: 
apiVersion: federation.external-secrets.io/v1alpha1
kind: KubernetesFederation
metadata:
  name: my-client-cluster # A descriptive name for the client cluster
spec:
  url: https://api.my-client-cluster.example.com

​
2. Authorization

  • API Group: federation.external-secrets.io/v1alpha1
  • Kind: Authorization
  • Scope: Cluster
  • Purpose: Grants specific client identities (Service Accounts from a federated client cluster) permission to access ClusterSecretStores or Generators on the Federation Server.
  • Spec Fields:
    • federationRef (object, required):
      • kind (string, required): Must be KubernetesFederation.
      • name (string, required): The name of the KubernetesFederation CR that represents the client cluster this authorization rule applies to.
    • subject (object, required):
      • issuer (string, required): The JWT issuer URL for the client’s SA token (e.g., https://kubernetes.default.svc.cluster.local of the client cluster, or a custom issuer if configured).
      • subject (string, required): The subject claim from the client’s SA JWT (e.g., system:serviceaccount:client-namespace:client-sa-name).
    • allowedClusterSecretStores (array of strings, optional): A list of ClusterSecretStore names (defined on the Federation Server) that the specified client identity is allowed to access.
    • allowedGenerators (array of objects, optional): A list of Generator resources (defined on the Federation Server) that the client identity is allowed to access. Each object in the list should specify:
      • name (string, required): The name of the Generator.
      • kind (string, required): The kind of the Generator (e.g., VaultDynamicSecret, Password).
      • namespace (string, required): The namespace where the Generator is defined on the Federation Server.
    • allowedGeneratorStates (array of objects, optional): Advanced permission for allowing the client to manage (e.g., delete) GeneratorState objects on the Federation Server. Each object specifies:
      • namespace (string, required): The namespace on the Federation Server where the GeneratorState objects reside.
Example Authorization CR: 
apiVersion: federation.external-secrets.io/v1alpha1
kind: Authorization
metadata:
  name: allow-app-x-access-vault
_spec:
  federationRef:
    kind: KubernetesFederation
    name: my-client-cluster
  subject:
    issuer: https://oidc.my-client-cluster.example.com # Client cluster's OIDC issuer URL
    subject: system:serviceaccount:app-ns:app-x-sa
  allowedClusterSecretStores:
    - central-vault-store
  allowedGenerators:
    - name: app-x-dynamic-db-creds
      kind: VaultDynamicSecret
      namespace: federation-generators
Both KubernetesFederation and Authorization CRs must be correctly configured on the Federation Server for clients to authenticate and be authorized to access secrets.

​
Federation Server API Endpoints

The Federation Server exposes the following HTTP POST endpoints for client interactions. Clients must authenticate to these endpoints using their Service Account tokens.
  • POST /secretstore/:secretStoreName/secrets/:secretName
    • Purpose: Fetches secret data from a specified ClusterSecretStore on the Federation Server. The :secretName typically corresponds to the name of an ExternalSecret’s data template that would be used if fetching locally.
    • Client Usage: esi-cli uses this endpoint when --federated-store is specified along with flags like --external-secrets or --inject-on-env that reference a secret name.
  • POST /generators/:generatorNamespace/:generatorKind/:generatorName
    • Purpose: Generates secret data using a specified Generator (e.g., VaultDynamicSecret, Password) on the Federation Server.
    • Client Usage: esi-cli uses this endpoint when --federated-generators is specified.
  • DELETE /generators/:generatorNamespace/:generatorKind/:generatorName
    • Purpose: Allows an authorized client to request revocation or cleanup of its own generated secrets or state related to a specific generator instance.
    • Permissions: Requires appropriate allowedGeneratorStates or specific generator-level permissions.
  • POST /generators/:generatorNamespace/revoke
    • Purpose: Allows an authorized client to request revocation of credentials related to a generator type within a namespace (e.g., revoking all tokens issued by a specific Vault PKI generator for that client).
    • Permissions: Depends on the generator’s capabilities and specific authorization rules.
The request body for these endpoints, beyond the authentication details (like ca.crt for the client cluster’s JWKS endpoint), may include parameters specific to the action, such as inputs for a generator. esi-cli handles the construction of these requests based on its command-line flags.
Properly configuring these CRDs and understanding the API endpoints are key to operating a secure and functional ESI Federation Server.