Macaw.Auth.Native.Config (macaw_auth v0.4.1)

Copy Markdown View Source

The native backend's configuration, read once and parsed into structs, every fault named (exio's AuthConfig approach):

config :macaw_auth, Macaw.Auth.Native,
  repo: MyApp.Repo,
  hasher: Macaw.Auth.Native.Hasher.Bcrypt,
  sources: [
    %{type: :password},
    %{type: :ldap, name: "nas", host: "nas.example.test", ...}
  ]
  • repo (required): the host's Ecto.Repo, holding macaw_auth_users.
  • hasher: Macaw.Auth.Native.Hasher.Bcrypt (the default) or Macaw.Auth.Native.Hasher.Argon2; refused when its library isn't a dependency.
  • sources: the chain, tried in order (Macaw.Auth.Native.Source); default [%{type: :password}]. Types: :password (Macaw.Auth.Native.Source.Password) and :ldap (Macaw.Auth.Native.Source.Ldap.Config). Names are unique: a name is the source of the rows it provisions.
  • session_idle_days: how long a session may go unused before it expires (Macaw.Auth.Native.Sessions), 1–3650; default 14.
  • totp_issuer: the name an authenticator app shows for this site's codes (Macaw.Auth.Native.Totp); default "Macaw".
  • totp_required: whether policy requires a second factor: false (the default), true (everyone), or a list of roles (a user with any of them). A user it requires who hasn't enrolled owes enrollment (second_factor: :required).
  • sealing_key: what TOTP secrets are sealed with at rest (Macaw.Auth.Native.Seal): a binary of at least 32 bytes, or {module, function, args} returning one. A literal shorter key is refused here; a missing one, or a function's short result, at first use. Never shown by inspect.

A source map may use string keys and a string type, as a JSON or config.exs file writes it; those become atoms only by lookup among the known ones. load!/0 raises Macaw.Auth.Native.Config.Error with the fault (sources[nas].host: is required); it runs when the application starts with backend: Macaw.Auth.Native, so a bad configuration refuses boot rather than a sign-in, and the result is kept in :persistent_term for get/0.

Summary

Types

t()

Functions

fetch()

The configuration as get/0 has it, but a fault is {:error, message}, not raised: for a command line (mix macaw_auth.user, a release's entry point), which answers it as one line.

get()

The parsed configuration, read at first use when boot didn't.

load!()

Reads and parses the application's configuration; raises Error naming the fault.

parse(config, opts \\ [])

Parses a configuration (a keyword list or map): {:ok, config} or {:error, message}. Options: :env (the environment for {:env, VAR} secrets, default the process's).

put(config)

Records a parsed configuration for this node (tests swap it).

Types

t()

@type t() :: %Macaw.Auth.Native.Config{
  hasher: module(),
  repo: module(),
  sealing_key: Macaw.Auth.Native.Seal.key_source(),
  session_idle_days: pos_integer(),
  sources: [Macaw.Auth.Native.Source.t()],
  totp_issuer: String.t(),
  totp_required: boolean() | [String.t()]
}

Functions

fetch()

@spec fetch() :: {:ok, t()} | {:error, String.t()}

The configuration as get/0 has it, but a fault is {:error, message}, not raised: for a command line (mix macaw_auth.user, a release's entry point), which answers it as one line.

get()

@spec get() :: t()

The parsed configuration, read at first use when boot didn't.

load!()

@spec load!() :: t()

Reads and parses the application's configuration; raises Error naming the fault.

parse(config, opts \\ [])

@spec parse(keyword() | map(), keyword()) :: {:ok, t()} | {:error, String.t()}

Parses a configuration (a keyword list or map): {:ok, config} or {:error, message}. Options: :env (the environment for {:env, VAR} secrets, default the process's).

put(config)

@spec put(t()) :: t()

Records a parsed configuration for this node (tests swap it).