# `AshAuthentication.Plug.Helpers`
[🔗](https://github.com/team-alembic/ash_authentication/blob/main/lib/ash_authentication/plug/helpers.ex#L5)

Authentication helpers for use in your router, etc.

# `assign_new_resources`

Assigns all subjects from their equivalent sessions, if they are not already assigned.

This is meant to used via `AshAuthenticationPhoenix` for nested liveviews.
See `AshAuthenticationPhoenix.LiveSession.assign_new_resources/3` for more.

# `get_authentication_result`

# `load_subjects`

```elixir
@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`

# `retrieve_from_bearer`

```elixir
@spec retrieve_from_bearer(Plug.Conn.t(), module(), keyword()) :: 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`.

# `retrieve_from_session`

```elixir
@spec retrieve_from_session(Plug.Conn.t(), module(), keyword()) :: 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`.

# `revoke_bearer_tokens`

```elixir
@spec revoke_bearer_tokens(Plug.Conn.t(), atom(), opts :: Keyword.t()) ::
  Plug.Conn.t()
```

Revoke all authorization header(s).

Any bearer-style authorization headers will have their tokens revoked.  A
header which does not hold a verifiable token is ignored.

# `revoke_session_tokens`

```elixir
@spec revoke_session_tokens(Plug.Conn.t(), atom(), opts :: Keyword.t()) ::
  Plug.Conn.t()
```

Revoke all tokens in the session.

# `set_actor`

```elixir
@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`.

```elixir
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
```

# `sign_in_using_remember_me`

```elixir
@spec sign_in_using_remember_me(Plug.Conn.t(), module(), keyword()) :: Plug.Conn.t()
```

Attempts to sign in all authenticated resources for the specificed otp_app 
using the RememberMe strategy if not already signed in. You can limited it to
specific strategies using the `strategy` opt.

Opts are forwarded to `AshAuthentication.Strategies.RememberMe.Plug.sign_in_resource_with_remember_me/3`

# `store_authentication_result`

```elixir
@spec store_authentication_result(
  Plug.Conn.t(),
  :ok | {:ok, Ash.Resource.Record.t()} | :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.

# `store_in_session`

```elixir
@spec store_in_session(Plug.Conn.t(), Ash.Resource.Record.t()) :: Plug.Conn.t()
```

Store the user in the connections' session.

Stores both the session identifier (token, jti:subject, or subject) and any
authentication metadata from the user. The metadata is stored separately and
will be restored onto the user when loading from the session.

The session is renewed before the subject is written. Renewing issues a new
session identifier and carries the existing session contents across, so values
such as `return_to` and the flash survive. Without it the identifier the
visitor arrived with would continue into their authenticated session, and an
identifier an attacker planted in the visitor's browser beforehand would become
an authenticated one.

---

*Consult [api-reference.md](api-reference.md) for complete listing*