Authentication & Identities

The network is built on one identity per person, managed by Kanidm 🡕. This page explains how a service verifies who you are, following two integration paths, and what happens between the browser, the gateway, and Kanidm.

Two ways to authenticate

Everything starts from Kanidm, the network’s identity provider (IdP). A service connects to it in two ways, depending on whether it speaks OIDC or not.

Path	Which services	Mechanism
Native OIDC	Service that speaks OIDC (Forgejo, Immich, Grafana…)	The service communicates directly with Kanidm
Authenticating reverse proxy	Service without auth (homepage, static site, bare UI)	oauth2-proxy + Caddy protect the service upstream

Identities and groups

Accounts and groups are provisioned in Kanidm from etc/config.yaml: one account per person, groups that control access. The users group contains all accounts; idm-admins and idm-devs are the special administration and development groups.

Account details

Account management (creation, passwords, groups) is described in SSO and identities.

Path 1: Native OIDC

When a service supports OIDC, DNF integrates it automatically: Kanidm provisions one OAuth2 client per service, the secret is managed by sops, and the service redirects itself to Kanidm for login. Nothing to configure manually.

This is the preferred path: the service knows the person’s identity and groups, and can apply its own roles (admin, reader…).

Path 2: authenticating reverse proxy

A service without authentication (the homepage, a static site…) cannot verify an identity. DNF then places a Kanidm login screen in front of it, at the gateway’s reverse proxy level. Three components work together:

• Caddy : the gateway’s reverse proxy. Before serving content, it delegates verification (forward auth) to oauth2-proxy.
• oauth2-proxy : one daemon per gateway (listens locally), Kanidm’s OAuth2 client. It holds the session and drives the login flow.
• Kanidm : issues the login screen and identity token.

Group-based authorization

Once the person is logged in, access is filtered by Kanidm group. Caddy passes the list of allowed groups to oauth2-proxy; without membership, the response is 403 even if authenticated.

Groups are SPNs

Kanidm returns groups as SPNs (name@domain.tld), not the short name. DNF appends this suffix automatically: declaring users on the service side is enough, the framework compares against users@domain.tld.

Session and SSO

After login, oauth2-proxy sets a session cookie valid across the entire zone domain (.maison.domain.tld). All protected services in the zone share the same session: you log in once. The flow endpoints (/oauth2/*) are hosted on the home page FQDN of the zone, which serves as the common anchor.

Internal vs external access

Protection can be limited to external access: internal clients (private LAN and tailnet VPN) reach the service without login, while access from the outside goes through the Kanidm login page. Useful for a portal open at home but protected on the Internet.

Secrets and certificates

• The oauth2-proxy client secret is shared with Kanidm via sops (a session secret is added as well).
• The flow introduces no new hostname : it reuses the homepage FQDN, already covered by a TLS certificate of the network.

Configuring protection

The administrator setup (enabling, choosing groups, internal/external mode) is described in SSO and identities. The code wiring is in Creating a service module.