Repository files navigation

Jwker is a Kubernetes operator that manages OAuth2 client registrations for applications that use theTokendings authorization server as part of the TokenX system.

It does this through theJwker custom resource definition (CRD):

apiVersion:nais.io/v1kind:Jwkermetadata:name:my-appnamespace:my-teamspec:accessPolicy:inbound:rules:      -application:some-other-appnamespace:some-teamcluster:some-clustersecretName:jwker-my-app

For the full CRD specification, see the spec innais/liberator:

• nais/liberator/config/crd/nais.io_jwkers.yaml

AJwker resource contains:

• the access policies for the application
• the name of the Kubernetes secret that the application expects

The operator is responsible for managing the secret and reconciling the OAuth2 client with its policies and credentials with Tokendings.

The secret contains the following keys:

sequenceDiagram    actor developer as Developer or<br/>Operator    box rgba(33,66,99,0.5) Kubernetes Cluster      participant crd as Jwker resource      participant secrets as Secrets      participant jwker as Jwker Controller    end    participant tokendings as Tokendings<br/>Authorization Server    loop forever      jwker ->> crd: watches    end    developer ->> crd: apply resource    jwker ->> crd: get resource    crd ->> secrets: owns    jwker ->> secrets: get all owned by resource    alt `spec.secretName` has changed      jwker ->> jwker: create new private key    else `spec.secretName` is unchanged      jwker ->> jwker: re-use private key from existing secret    end    jwker ->> jwker: create client assertion for<br/>authenticating with tokendings    jwker ->> tokendings: POST public keys (JWKS)<br/>and access policies to<br/>`/registration/client`    note over tokendings: JWKS contains all currently used public keys    jwker ->> secrets: create/update    loop for each owned secret      alt name equals `spec.secretName`         jwker ->> secrets: keep secret      else         jwker ->> secrets: delete if<br/>unreferenced      end    end

1. When aJwker resource is applied to the cluster (either by a developer or another operator), the Jwker controller will reconcile it.
2. The controller reads theJwker resource and retrieves all existing secrets owned by the resource.
3. The controller then checks if thespec.secretName has changed:
   1. If the secret name has changed, it creates a new private key for the application.
   2. If the secret name is unchanged, it reuses the private key from the existing secret.
4. The operator creates a client assertion for authenticating with Tokendings.
5. The application's public keys (JWKS) and access policies are registered with Tokendings via the/registration/client endpoint.
   1. The JWKS contains all currently used public keys to ensure key rotation works properly.
   2. Each application is registered with Tokendings using a unique identifier in the form ofclustername:namespace:application
6. The operator creates or updates the Kubernetes secret with the specifiedsecretName.
7. Finally, any unreferenced secrets are deleted to clean up resources.
   1. Secrets are considered referenced if mounted as files or environment variables in a pod.The pod must have a labelapp=<name> where<name> is equal to.metadata.name in theJwker resource.

helm install jwker ./charts

Jwker can be configured using either command-line flags or equivalent environment variables:

Start a local Kubernetes cluster, e.g. usingkind,minikube, or similar.

Install the CRD if you haven't already:

make install-crd

Start up dependencies:

docker-compose up -d

Run the operator:

makelocal

Deploy a sampleJwker:

make sample