View Source AppIdentity.Plug (AppIdentity for Elixir v1.1.0)
A Plug that verifies App Identity proofs provided via one or more HTTP headers.
When multiple proof values are provided in the request, all must be
successfully verified. If any of the proof values cannot be verified,
request processing halts with 403 Forbidden
. Should no proof headers are
included, the request is considered invalid.
All of the above behaviours can be modified through configuration.
The results of completed proof validations can be found at
%Plug.Conn{private: %{app_identity: %{}}}
, regardless of the success or
failure state.
telemetry
Telemetry
When telemetry is enabled, this plug will emit [:app_identity, :plug, :start]
and [:app_identity, :plug, :stop]
events.
Link to this section Summary
Types
AppIdentity.Plug configuration options prior to validation.
Normalized options for AppIdentity.Plug.
Link to this section Types
@type on_failure() :: :forbidden | :continue | {:halt, Plug.Conn.status()} | {:halt, Plug.Conn.status(), Plug.Conn.body()}
@type on_failure_fn() :: (Plug.Conn.t() -> on_failure()) | {module(), function :: atom()}
@type option() :: AppIdentity.disallowed() | {:headers, [binary()]} | {:apps, [AppIdentity.App.input() | AppIdentity.App.t()]} | {:finder, AppIdentity.App.finder()} | {:on_failure, on_failure() | on_failure_fn()}
AppIdentity.Plug configuration options prior to validation.
apps
: A list ofAppIdentity.App
orAppIdentity.App.input/0
values to be used for proof validation. Duplicate values will be ignored.disallowed
: A list of algorithm versions that are not allowed when processing received identity proofs. SeeAppIdentity.disallowed/0
.finder
: AnAppIdentity.App.finder/0
function to load anAppIdentity.App.input/0
from an external source given a parsed proof.headers
: A list of HTTP header names.on_failure
: The behaviour of the AppIdentity.Plug when proof validation fails. Must be one of the following values::forbidden
: Halt request processing and respond with a403
(forbidden) status. This is the same as{:halt, :forbidden}
. This is the defaulton_failure
behaviour.{:halt, Plug.Conn.status()}
: Halt request processing and return the specified status code. An empty body is emitted.{:halt, Plug.Conn.status(), Plug.Conn.body()}
: Halt request processing and return the specified status code. The body value is included in the response.:continue
: Continue processing, ensuring that failure states are recorded for the application to act on at a later point. This could be used to implement a distinction between validating a proof and requiring that the proof is valid.A 1-arity anonymous function or a {module, function} tuple accepting
Plug.Conn
that returns one of the above values.
At least one of apps
or finder
must be supplied. If both are
present, apps are looked up in the apps
list first.
plug AppIdentity.Plug, header: "application-identity",
finder: fn proof -> ApplicationModel.get!(proof.id) end
@type t() :: %AppIdentity.Plug{ apps: %{optional(AppIdentity.id()) => AppIdentity.App.t()}, disallowed: [AppIdentity.version()], finder: nil | AppIdentity.App.finder(), headers: [binary()], on_failure: on_failure() | {:fn, on_failure()} }
Normalized options for AppIdentity.Plug.