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.

t()

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 of AppIdentity.App or AppIdentity.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. See AppIdentity.disallowed/0.

  • finder: An AppIdentity.App.finder/0 function to load an AppIdentity.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 a 403 (forbidden) status. This is the same as {:halt, :forbidden}. This is the default on_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.