Copyright © KC Green

Pocket ID as the Lab OIDC Provider (Zot Example)

Permalink 2 min read Published:
 infrastructure  #Pocket-ID #OIDC #OAuth2 #Zot #Envoy-Gateway #GitOps

A small IdP at auth.this-is-fine.io — native OpenID login for the Zot registry.

Pocket ID is a small OpenID Connect provider — enough for a homelab without Keycloak. The lab runs it at https://auth.this-is-fine.io with Flux and an HTTPRoute on Envoy Gateway. Below is how Zot uses native OpenID against that issuer.

If you already run a homelab IdP, the interesting part is how little application code must change when the app speaks OIDC natively. Zot is a clear example: configure issuer URL, client ID, and redirect URIs, mount a secret, and the registry UI handles login without an OAuth sidecar in front of it.

Software map

Piece Link Role
Pocket ID pocket-id.org Users, OAuth clients, consent UI
OIDC primer OpenID Connect Issuer, client_id, redirect URIs
Zot OpenID Zot auth Registry login

Pocket ID on the cluster

browser -> auth.this-is-fine.io
  -> Pocket ID (PVC-backed)
  -> /.well-known/openid-configuration
  • Public route on shared-gateway-external; TRUST_PROXY=true behind Cloudflare.
  • Optional VolSync backup for the PVC.
  • Encryption key and client credentials via SOPS, same as other apps.

Register each OAuth client in Pocket ID (redirect URL and scopes) before switching the app on. A mismatch on redirect URI is the most common first-login failure; fix it in Pocket ID, not in Zot’s logs alone.

Zot: native OpenID

Zot at oci.this-is-fine.io reads OpenID from zot.json — no Envoy OIDC shim for the registry UI.

"openid": {
  "providers": {
    "oidc": {
      "issuer": "https://auth.this-is-fine.io",
      "scopes": ["openid", "profile", "email"]
    }
  }
}

A Kubernetes Secret mounts the client credentials file. htpasswd stays for robots (buildbot, CI); people use SSO. RBAC maps OIDC groups (admins, users) to registry roles.

human -> oci.this-is-fine.io -> redirect -> auth.this-is-fine.io
  <- authorization code / token
automation -> htpasswd or robot account (unchanged)

People through Pocket ID; automation through scoped local accounts — a useful split elsewhere too.

Headscale OIDC is on the backlog (Envoy post notes the TODO): the chart already has placeholder environment variables; enabling them means registering another client in Pocket ID and trusting the same issuer URL.

Pocket ID: installation, OIDC clients.