# `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.

# `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()} | :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()) :: 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.

---

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