Skip to content

configuration.md

Latest commit

 

History

History
92 lines (72 loc) · 3.21 KB

configuration.md

File metadata and controls

92 lines (72 loc) · 3.21 KB

Configuration

All configuration is provided through the config/0 callback in your module implementing -behaviour(nova_auth_oidc). The returned map is merged with defaults and cached in persistent_term.

Config Keys

Key Type Default Description
providers #{atom() => provider_config()} required Map of provider name to config
base_url binary() ~"http://localhost:8080" Application base URL for callback URIs
auth_path_prefix binary() ~"/auth" URL prefix for auth routes
scopes [binary()] [~"openid", ~"profile", ~"email"] Default OIDC scopes
on_success {redirect, binary()} {redirect, ~"/"} Action after successful auth
on_failure {status, integer()} | {redirect, binary()} {status, 401} Action on auth failure
claims_mapping #{binary() => atom()} | {module(), atom()} #{} How to map claims to actor

Provider Config

Each provider entry requires:

Key Type Required Description
issuer binary() yes OIDC issuer URL (used for discovery)
client_id binary() yes OAuth2 client ID
client_secret binary() yes OAuth2 client secret
scopes [binary()] no Override default scopes for this provider
extra_params #{binary() => binary()} no Extra query parameters for authorization

Full 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",
        auth_path_prefix => ~"/auth",
        scopes => [~"openid", ~"profile", ~"email"],
        on_success => {redirect, ~"/dashboard"},
        on_failure => {redirect, ~"/login?error=auth_failed"},
        claims_mapping => #{
            ~"sub" => id,
            ~"email" => email,
            ~"name" => display_name,
            ~"groups" => roles
        }
    }.

Session Keys

During the OIDC flow, temporary state is stored in the Nova session:

Key Lifetime Contents
oidc_nonce Login to callback Cryptographic nonce
oidc_pkce Login to callback PKCE code verifier
oidc_provider Login to callback Provider name
nova_auth_actor After callback Mapped actor (permanent session)

The temporary keys are cleaned up after the callback completes.

Provider Worker Names

Each provider gets a worker process registered as nova_auth_oidc_<module>_<provider>. For example, with module my_oidc_config and provider authentik, the worker is nova_auth_oidc_my_oidc_config_authentik.

You can retrieve the name programmatically:

Name = nova_auth_oidc:provider_worker_name(my_oidc_config, authentik).

Cache Invalidation

Configuration is cached in persistent_term. To force a refresh:

nova_auth_oidc:invalidate_cache(my_oidc_config).