nova_auth_oidc

OpenID Connect authentication for Nova web applications.

Provides OIDC login flows, JWT bearer validation, token introspection, and client credentials (M2M) – all integrated with nova_auth‘s unified actor session.

Features

Multi-provider OIDC – Authentik, Google, GitHub, Keycloak, etc.
JWT bearer validation – protect API routes with provider-issued JWTs
Token introspection – check revocation status (RFC 7662)
Client credentials – machine-to-machine tokens with caching
Claims mapping – transform provider claims to actor maps via nova_auth_claims
Nova integration – security callbacks, plugins, route protection

Quick Start

%% 1. Define your OIDC config
-module(my_oidc_config).
-behaviour(nova_auth_oidc).
-export([config/0]).

config() ->
    #{providers => #{
          authentik => #{
              issuer => ~"https://auth.example.com/application/o/myapp",
              client_id => os:getenv("AUTHENTIK_CLIENT_ID"),
              client_secret => os:getenv("AUTHENTIK_CLIENT_SECRET")
          }
      },
      base_url => ~"https://myapp.example.com",
      claims_mapping => #{
          ~"sub" => id, ~"email" => email, ~"groups" => roles
      }}.

%% 2. Start providers in your app&#39;s start/2
start(_Type, _Args) ->
    nova_auth_oidc:ensure_providers(my_oidc_config),
    my_sup:start_link().

%% 3. Add routes
routes(_Env) ->
    [#{prefix => ~"/auth", security => false,
       routes => [
           {~"/:provider/login", fun nova_auth_oidc_controller:login/1,
            #{auth_mod => my_oidc_config}},
           {~"/:provider/callback", fun nova_auth_oidc_controller:callback/1,
            #{auth_mod => my_oidc_config}}
       ]},
     #{prefix => ~"/dashboard",
       security => nova_auth_security:require_authenticated(),
       routes => [...]},
     #{prefix => ~"/api",
       security => nova_auth_oidc_security:require_bearer(my_oidc_config),
       routes => [...]}].

Modules

Module	Description
`nova_auth_oidc`	Behaviour-based config, provider worker management
`nova_auth_oidc_controller`	Login redirect and OAuth callback endpoints
`nova_auth_oidc_plugin`	Route protection plugin (session-based)
`nova_auth_oidc_jwt`	JWT bearer token validation via provider JWKS
`nova_auth_oidc_security`	Security callbacks: `require_bearer/1`, `require_any/1`
`nova_auth_oidc_introspect`	Token introspection (RFC 7662)
`nova_auth_oidc_client_credentials`	Client credentials flow with caching

How It Works

User visits /auth/authentik/login
Controller generates nonce + PKCE, stores in session, redirects to provider
User authenticates at Authentik
Authentik redirects to /auth/authentik/callback?code=...
Controller exchanges code for tokens via oidcc
Controller retrieves userinfo from provider
Claims are mapped to an actor via nova_auth_claims
Actor is stored in session via nova_auth_actor
User is redirected to the success URL

From this point, nova_auth_security:require_authenticated() works for all protected routes.

Guides

Getting Started – Installation and first setup
Configuration – Full config reference
JWT Bearer – Protecting API routes with JWTs
Claims Mapping – Transforming provider claims
Client Credentials – Machine-to-machine auth

Dependencies

nova_auth – unified actor session, claims mapping, policies
oidcc – ERLEF OpenID Connect Certified client
nova – web framework

Requirements

Erlang/OTP 28+

License

MIT