# Introduction

> A self-hosted OAuth 2.0 and OpenID Connect provider for Kubernetes, where an app's OAuth client is declared as a resource. What works today and where to start.

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`](https://www.nauthera.io/docs/v1/oidc-client) 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](https://www.nauthera.io/docs/v1/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](https://www.nauthera.io/docs/v1/installation#from-the-published-chart), every version on
> [Downloads](https://www.nauthera.io/downloads)), or [apply for a seat](https://www.nauthera.io/#waitlist).

## 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](https://www.nauthera.io/docs/v1/clients#dynamic-client-registration).
- **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](https://www.nauthera.io/docs/v1/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](https://www.nauthera.io/docs/v1/sign-in-flows/social-sign-in). An organization's LDAP
  directory or Active Directory can sign its users in with their directory password; see
  [LDAPDirectory](https://www.nauthera.io/docs/v1/ldap-directory-resource).
- **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](https://www.nauthera.io/docs/v1/mfa).
- **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](https://www.nauthera.io/downloads) lists every version.
  See [Installation](https://www.nauthera.io/docs/v1/installation#from-the-published-chart).

## 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](https://www.nauthera.io/standards#method) is checked against
the server's code and tests instead.

See [Standards](https://www.nauthera.io/standards) for a specification-by-specification breakdown, and the
[roadmap](https://www.nauthera.io/roadmap) for planned work.

## How it fits together

```mermaid
flowchart LR
    users["Users & relying parties"] -->|":8080 HTTPS"| public
    scrapers["Prometheus & kubelet"] -->|":9090"| admin
    operator["Operator"] -->|":9091 mTLS"| grpc
    cli["nauthera-cli (local dev)"] -.->|":9091 dev only"| grpc

    subgraph server["nauthera-server"]
        public["Public HTTP<br/>OAuth2 · OIDC · sign-in UI · dashboard · admin API"]
        admin["Admin HTTP<br/>metrics · health · pprof"]
        grpc["gRPC<br/>AdminService · grpc.health.v1"]
    end

    public --> db[("PostgreSQL")]
    grpc --> db
    public --> cache[("Redis")]
    public -.->|"outbox"| smtp[("SMTP relay")]
```

## Where to go next

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