eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/how-to/authentik/authentik-api-client-generation.md
Erich Blume efa9806bfa
All checks were successful
Build Container / detect (push) Successful in 3s
Details
Build Container (Nix) / detect (push) Successful in 1s
Details
Build Container / build (authentik) (push) Successful in 2s
Details
Build Container (Nix) / build (authentik) (push) Successful in 22s
Details
C2: Build authentik from source (Mikado chain) (#274) 
## Mikado Chain: build-authentik-from-source

Replace `pkgs.authentik` from nixpkgs with a custom Nix derivation built from source.
This removes the dependency on the nixpkgs packaging timeline and gives full version control.

Target version: **2025.12.4** (nixpkgs reference, upgrading from deployed 2025.10.1).

### Dependency Graph

```
build-authentik-from-source (goal)
├── authentik-go-server-derivation
│   ├── authentik-api-client-generation  ← IN PROGRESS
│   └── authentik-python-backend-derivation
├── authentik-web-ui-derivation
│   └── authentik-api-client-generation  ← IN PROGRESS
└── authentik-python-backend-derivation
```

### Ready Leaves
- `authentik-api-client-generation` — Go + TypeScript client generation from OpenAPI schema
- `authentik-python-backend-derivation` — Django backend with 60+ deps, 4 in-tree packages

### Architecture
Ported from [nixpkgs `pkgs/by-name/au/authentik/package.nix`](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/au/authentik):
- `source.nix` — shared version/source fetch
- `client-go.nix` — Go API client generation
- `client-ts.nix` — TypeScript API client generation
- `api-go-vendor-hook.nix` — Go vendor directory injection hook
- (more components to follow as leaves are closed)

### Related Cards
- [[build-authentik-from-source]] — Goal card
- [[authentik-api-client-generation]]
- [[authentik-python-backend-derivation]]
- [[authentik-web-ui-derivation]]
- [[authentik-go-server-derivation]]

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/274
2026-03-01 13:45:00 -08:00

2.5 KiB
Raw Blame History

title modified requires tags
Generate Authentik API Clients 2026-02-28
mirror-authentik-build-deps
how-to
authentik
nix

Generate Authentik API Clients

Build Go and TypeScript API client bindings from authentik's OpenAPI spec (schema.yml). These are build-time inputs for the Go server and web UI respectively.

Context

Authentik maintains a separate repo (goauthentik/client-go) with pre-generated Go client code. The nixpkgs derivation fetches this and injects it into the Go vendor directory via a setup hook (apiGoVendorHook). The TypeScript client is generated inline from schema.yml using openapi-generator-cli.

Both clients are generated from the same schema.yml OpenAPI spec in the main authentik repo.

What to Do

  1. Create a Nix derivation (client-go) that generates Go API client bindings from schema.yml using openapi-generator-cli
  2. Create a Nix derivation (client-ts) that generates TypeScript fetch client bindings from the same spec
  3. Create a setup hook (apiGoVendorHook) that replaces goauthentik.io/api/v3 in the Go vendor directory with the generated client
  4. Verify the generated code compiles (Go: go build, TypeScript: type-check with tsc)

Key Details

  • Source spec: schema.yml in the authentik repo root
  • Go client replaces vendor/goauthentik.io/api/v3/ in the server build
  • TypeScript client replaces web/node_modules/@goauthentik/api/ in the web UI build
  • The nixpkgs derivation patches the generated Go client (client-go-config.patch) — check if still needed

Testing on Ringtail

Use this ad-hoc test-build.nix harness (not committed to the repo):

# test-build.nix
let
  pkgs = (builtins.getFlake "nixpkgs").legacyPackages.x86_64-linux;
  sources = import ./sources.nix { inherit pkgs; };
in
{
  client-go = import ./client-go.nix { inherit pkgs sources; };
  client-ts = import ./client-ts.nix { inherit pkgs sources; };
  api-go-vendor-hook = import ./api-go-vendor-hook.nix { inherit pkgs sources; };
}

set tmpdir (ssh ringtail 'mktemp -d /tmp/authentik-test.XXXXXX')
scp containers/authentik/*.nix ringtail:$tmpdir/
ssh ringtail "cd $tmpdir && nix-build test-build.nix -A client-go --extra-experimental-features 'nix-command flakes'"
ssh ringtail "rm -rf $tmpdir"

Related