@spec load_subjects([AshAuthentication.subject()], module(), opts :: Keyword.t()) ::
  map()

Given a list of subjects, turn as many as possible into users.

Opts are forwarded to AshAuthentication.subject_to_user/2

@spec retrieve_from_bearer(Plug.Conn.t(), module()) :: Plug.Conn.t()

Validate authorization header(s).

Assumes that your clients are sending a bearer-style authorization header with your request. If a valid bearer token is present then the subject is loaded into the assigns under their subject name (with the prefix current_).

If the authentication token is required to be present in the database, it is loaded into the assigns using current_#{subject_name}_token_record

If there is no user present for a resource then the assign is set to nil.

@spec retrieve_from_session(Plug.Conn.t(), module()) :: Plug.Conn.t()

Attempt to retrieve all users from the connections' session.

Iterates through all configured authentication resources for otp_app and retrieves any users stored in the session, loads them and stores them in the assigns under their subject name (with the prefix current_).

If there is no user present for a resource then the assign is set to nil.

@spec revoke_bearer_tokens(Plug.Conn.t(), module()) :: Plug.Conn.t()

Revoke all authorization header(s).

Any bearer-style authorization headers will have their tokens revoked.

@spec set_actor(Plug.Conn.t(), subject_name :: atom()) :: Plug.Conn.t()

Set a subject as the request actor.

Presumes that you have already loaded your user resource(s) into the connection's assigns.

Uses Ash.PlugHelpers to streamline integration with AshGraphql and AshJsonApi.

Examples

Setting the actor for a AshGraphql API using Plug.Router.

defmodule MyApp.ApiRouter do
  use Plug.Router
  import MyApp.AuthPlug

  plug :match

  plug :retrieve_from_bearer
  plug :set_actor, :user

  plug :dispatch

  forward "/gql",
    to: Absinthe.Plug,
    init_opts: [schema: MyApp.Schema]
end

@spec store_authentication_result(
  Plug.Conn.t(),
  :ok | {:ok, Ash.Resource.record()} | :error | {:error, any()}
) :: Plug.Conn.t()

Store result in private.

This is used by authentication plug handlers to store their result for passing back to the dispatcher.

@spec store_in_session(Plug.Conn.t(), Ash.Resource.record()) :: Plug.Conn.t()

Store the user in the connections' session.