Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

Introduction

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner programUpdated

Nauthera is a self-hosted OAuth 2.0 and OpenID Connect identity provider for Kubernetes, written in Go. It is built around one goal: an application's OAuth client is a Kubernetes resource that ships with it. You declare an OIDCClient beside the app's Deployment, and the Nauthera operator registers it with the server and writes the generated client secret into a Secret the workload mounts. See Operator.

nauthera-server is a single static Go binary that serves the protocol endpoints, a hosted sign-in UI, an admin dashboard and a versioned admin API, and exposes the mutual-TLS gRPC AdminService the operator calls.

Project status: Nauthera is pre-1.0, in a design-partner program: its signed server and operator images and its Helm chart are public on the GitHub Container Registry, and teams can apply for one of five design-partner seats to pilot it with direct support. The source is private. Everything under What it does today is tested in nauthera-server's CI: Go tests through the real handlers under the race detector, Playwright in a browser against the real binaries, and the operator on a kind cluster. Install the published chart without an account (Installation, every version on Downloads), or apply for a seat.

What it does today

  • OAuth 2.0 and OpenID Connect. Authorization code with PKCE (S256), refresh tokens that rotate on every use with reuse detection, client credentials, and the device authorization grant. Also discovery, JWKS, UserInfo, introspection, revocation, and RP-initiated, front-channel and back-channel logout. Third-party software registers and manages its own client through dynamic client registration (RFC 7591, RFC 7592), behind an initial access token; see Clients.
  • Sender-constrained and hardened requests. DPoP-bound tokens (RFC 9449), pushed authorization requests (RFC 9126), signed request objects (RFC 9101), resource indicators (RFC 8707) and the iss parameter on authorization responses (RFC 9207). A per-organization FAPI 2.0 mode (partial).
  • Organizations. Multi-tenant realms, each its own issuer with its own discovery document, JWKS and signing keys. Sessions never cross organizations. The main organization's settings can be pinned in the server's configuration.
  • Identity broker. One organization can sign users in for many: it asks for the email address, routes the user to the member organization that verified the domain, and issues tokens naming the member. See Identity Broker.
  • Hosted sign-in UI. Sign-in, registration, password reset, email verification, invitation acceptance, consent, device-code approval, MFA, passkey and logout screens are compiled into the binary, translated into English, German and French, and themed per organization and per OAuth client. Registration, emailed-link requests and repeated failed sign-ins ask for a captcha: a built-in proof-of-work by default, or Cloudflare Turnstile, hCaptcha or reCAPTCHA.
  • Social and directory sign-in. Each organization can declare external OpenID Connect providers and GitHub, and each client chooses which to offer for sign-in, sign-up or both. A provider's verified addresses can link to existing accounts, and its own multi-factor sign-in can stand in for the second factor. See Social sign-in. An organization's LDAP directory or Active Directory can sign its users in with their directory password; see LDAPDirectory.
  • Multi-factor authentication. TOTP with recovery codes and lockout, passkeys (WebAuthn) as a second factor or, where allowed, for passwordless sign-in, and emailed one-time codes where an operator opts in. A second-factor policy at deployment, organization and client level, each only tightening the one above, decides which methods are offered and whether they are required. Named network zones can spare the challenge in trusted networks, a browser that recently passed one can be remembered, and conditional rules can require a factor, or narrow the methods, outside a zone, from a new network or on a new browser. See Multi-Factor Authentication.
  • Email. Password reset links, email verification links, invitations, emailed one-time codes, alerts about a sign-in from an unrecognized browser or network, and notices when a role is granted or revoked, an account is suspended, blocked or reactivated, or a password, second factor or recovery codes change. They go through SMTP over TLS from a durable outbox, with a relay per organization if you want one.
  • Kubernetes operator. Reconciles OIDCClient, Organization, IdentityProvider, Branding, LDAPDirectory and BrokerMembership resources into the server, delivers a client's minted secret into a Secret, follows each manifest's deletion policy, reports a client changed outside it, and publishes metrics. It ships in the server's Helm chart.
  • Admin dashboard, admin API and audit log. A dashboard per organization for its clients, users, sessions, identity providers, audit log, threat analytics and email settings, over a REST API that requires an OAuth scope and an RBAC permission for every call. The dashboard's Problems page lists the resources an operator could not apply, and its Troubleshooting page explains a failed request from its reference ID. Eight built-in roles, named by scope and job (org-viewer to org-owner, platform-viewer to platform-owner), are granted and revoked over the API and the dashboard, and a caller can grant only roles its own roles cover. Administrators can invite users by email. User accounts carry a status (active, suspended, blocked) enforced at sign-in and on every token grant. Every change, including those made over the control plane, is recorded in a hash-chained audit log with signed checkpoints.
  • Threat analytics. A catalog of threat signals counted from the audit log per organization and judged against thresholds, shown in the dashboard and exported as Prometheus metrics with alerting rules.
  • Operations. PostgreSQL storage, a Redis cache (required for any non-loopback issuer, optional for local development), Prometheus metrics, OpenTelemetry tracing, structured logs, a Helm chart for the server with cert-manager integration and an optional Gateway API route, and startup checks that refuse unsafe production configuration.
  • Signed public releases. A version tag publishes the server and operator images and the Helm chart to GHCR, scanned and signed with cosign, with the images pinned by digest in the chart. Anyone can pull them; Downloads lists every version. See Installation.

What it does not do

It does not serve SAML, SCIM provisioning, user import or token exchange (RFC 8693); users sign in through OpenID Connect providers, GitHub, LDAP or Active Directory, or with an account of its own. It also does not serve:

  • Mutual-TLS client authentication or certificate-bound tokens (RFC 8705), or client_secret_jwt. Confidential clients authenticate with a client secret or private_key_jwt, and DPoP binds tokens to a client's key.
  • The JWT bearer grant (RFC 7523 §2.1). Like token exchange, it answers temporarily_unavailable and is not advertised.

Nauthera is not OpenID Certified. Each status on Standards is checked against the server's code and tests instead.

See Standards for a specification-by-specification breakdown, and the roadmap for planned work.

How it fits together

Where to go next

  1. Operator and OIDCClient: what the operator does and the resource you declare, with Organization and IdentityProvider beside it.
  2. Quick Start: install the published Helm chart on a local kind cluster, sign in and register a client.
  3. Installation: install the published Helm chart or one from a checkout, on a kind cluster, then in a production profile.
  4. Configuration: the configuration file, environment variables and secret files.
  5. Architecture: the three listeners, storage, email and the control plane.
  6. Organizations and Clients: tenants and how applications are registered.
  7. Connect an Application: sign users in to your own app, step by step.
  8. Endpoints: every HTTP endpoint the server serves.
  9. AI Prompts: copy-ready prompts that set up any of the above with Claude Code, Cursor, Copilot or another AI assistant.
  10. Keys & Secrets and Backups & Upgrades: what to protect and how to run it over time.
  11. Adopting Nauthera: for a company bringing it in, next to an identity provider it already runs, with migration, ownership, rollout and the operational requirements.