Behaviour for OIDC authentication configuration. Implementing modules define OIDC providers, scopes, and callbacks. Configuration is cached in persistent_term for fast repeated access.

Example

-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
      }}.

Provider discovery/JWKS trust options

On OTP 28+, each provider's oidcc_provider_configuration_worker already verifies TLS (verify_peer against the OS trust store) by default when it fetches the discovery document and JWKS. To pin an explicit CA bundle or other TLS options instead of relying on that default, set provider_configuration_opts in config/0:

provider_configuration_opts => #{request_opts => #{ssl => my_tls_opts()}}

Treat this key as a trust anchor, not just a TLS knob: its type is oidcc_provider_configuration:opts(), which besides request_opts also carries quirks - allow_unsafe_http (downgrades discovery to plaintext), document_overrides (can override jwks_uri/token_endpoint from the discovery document itself), and issuer_regex (relaxes issuer matching). Build it from static code, never from operator- or env-supplied data - a value that can be edited outside a release effectively controls where tokens are trusted from.

This applies to every provider ensure_providers/1 starts; there is no per-provider override.