Federation Server Setup

​

Custom Resource Definitions (CRDs)

​

1. Identity

• KubernetesFederation
• SpiffeFederation

​

1.1. KubernetesFederation

• API Group: identity.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.

apiVersion: identity.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

​

1.2. SpiffeFederation

• API Group: identity.federation.external-secrets.io/v1alpha1
• Kind: SpiffeFederation
• Scope: Cluster
• Purpose: Defines a named federation relationship with a SPIFFE-enabled environment, allowing the Federation Server to trust and validate SPIFFE identities (spiffe://…) issued by that external trust domain.
• Spec Fields:
  • trustDomain (string, required): The SPIFFE Trust Domain (e.g. spiffe://client.example.com). Used to locate the bundle endpoint and validate SVIDs issued by that domain.

apiVersion: identity.federation.external-secrets.io/v1alpha1
kind: KubernetesFederation
metadata:
  name: my-client-cluster # A descriptive name for the client cluster
spec:
  trustDomain: spiffe://client.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.

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

​

Federation Server API Endpoints

• 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.