Guardian.Plug (Guardian v2.4.0)

Provides functions for the implementation module for dealing with Guardian in a Plug environment.

defmodule MyApp.Tokens do
  use Guardian, otp_app: :my_app

  # ... snip
end

Your implementation module will be given a Plug module for interacting with plug.

If you're using Guardian in your application most of the setters will be uninteresting. They're mostly for library authors and Guardian itself.

The usual functions you'd use in your application are:

`sign_in(conn, resource, claims \\ %{}, opts \\ [])`

Sign in a resource for your application. This will generate a token for your resource according to your TokenModule and subject_for_token callback.

sign_in will also cache the resource, claims, and token on the connection.

conn = MyApp.Guardian.Plug.sign_in(conn, resource, my_custom_claims)

If there is a session present the token will be stored in the session to provide traditional session based authentication.

Summary

Functions

authenticated?(conn, opts \\ [])

clear_remember_me(conn, mod, opts \\ [])

Puts a response cookie which replaces the previous remember_me cookie and is set to immediately expire on the client.

current_claims(conn, opts \\ [])

current_resource(conn, opts \\ [])

current_token(conn, opts \\ [])

default_key()

Provides the default key for the location of a token in the session and connection.

find_token_from_cookies(conn, opts \\ [])

maybe_halt(conn, opts \\ [])

put_current_claims(conn, claims, opts \\ [])

put_current_resource(conn, resource, opts \\ [])

put_current_token(conn, token, opts \\ [])

put_session_token(conn, token, opts \\ [])

remember_me(conn, mod, resource, claims \\ %{}, opts \\ [])

Sets a token of type refresh directly on a cookie.

remember_me_from_token(conn, mod, token, claims_to_check \\ %{}, opts \\ [])

session_active?(conn)

sign_in(conn, impl, resource, claims \\ %{}, opts \\ [])

sign_out(conn, impl, opts \\ [])

Functions

authenticated?(conn, opts \\ [])

@spec authenticated?(Plug.Conn.t(), Guardian.options()) :: true | false

clear_remember_me(conn, mod, opts \\ [])

@spec clear_remember_me(Plug.Conn.t(), module(), Guardian.options()) :: Plug.Conn.t()

Puts a response cookie which replaces the previous remember_me cookie and is set to immediately expire on the client.

Note that while this can be used as a cheap way to sign out, a malicious client could still access your server using the old JWT from the old cookie.

In other words, this does not in any way invalidate the token you issued, it just makes a compliant client forget it.

current_claims(conn, opts \\ [])

@spec current_claims(Plug.Conn.t(), Guardian.options()) ::
  Guardian.Token.claims() | nil

current_resource(conn, opts \\ [])

@spec current_resource(Plug.Conn.t(), Guardian.options()) :: any() | nil

current_token(conn, opts \\ [])

@spec current_token(Plug.Conn.t(), Guardian.options()) :: Guardian.Token.token() | nil

default_key()

@spec default_key() :: String.t()

Provides the default key for the location of a token in the session and connection.

find_token_from_cookies(conn, opts \\ [])

@spec find_token_from_cookies(conn :: Plug.Conn.t(), Keyword.t()) ::
  {:ok, String.t()} | :no_token_found

maybe_halt(conn, opts \\ [])

@spec maybe_halt(Plug.Conn.t(), Keyword.t()) :: Plug.Conn.t()

put_current_claims(conn, claims, opts \\ [])

@spec put_current_claims(
  Plug.Conn.t(),
  Guardian.Token.claims() | nil,
  Guardian.options()
) ::
  Plug.Conn.t()

put_current_resource(conn, resource, opts \\ [])

@spec put_current_resource(Plug.Conn.t(), resource :: any() | nil, Guardian.options()) ::
  Plug.Conn.t()

put_current_token(conn, token, opts \\ [])

@spec put_current_token(
  Plug.Conn.t(),
  Guardian.Token.token() | nil,
  Guardian.options()
) ::
  Plug.Conn.t()

put_session_token(conn, token, opts \\ [])

@spec put_session_token(
  Plug.Conn.t(),
  Guardian.Token.token(),
  Guardian.options()
) :: Plug.Conn.t()

remember_me(conn, mod, resource, claims \\ %{}, opts \\ [])

@spec remember_me(
  Plug.Conn.t(),
  module(),
  any(),
  Guardian.Token.claims(),
  Guardian.options()
) ::
  Plug.Conn.t()

Sets a token of type refresh directly on a cookie.

The max_age of the cookie till be the expire time of the Token, if available If the token does not have an exp,t the default will be 30 days.

The max age can be overridden by setting the cookie option config.

remember_me_from_token(conn, mod, token, claims_to_check \\ %{}, opts \\ [])

@spec remember_me_from_token(
  Plug.Conn.t(),
  module(),
  Guardian.Token.token(),
  Guardian.Token.claims(),
  Guardian.options()
) :: Plug.Conn.t()

session_active?(conn)

sign_in(conn, impl, resource, claims \\ %{}, opts \\ [])

@spec sign_in(
  Plug.Conn.t(),
  module(),
  any(),
  Guardian.Token.claims(),
  Guardian.options()
) ::
  Plug.Conn.t()

sign_out(conn, impl, opts \\ [])

@spec sign_out(Plug.Conn.t(), module(), Guardian.options()) :: Plug.Conn.t()