Guardian

v0.13.0

Guardian v0.13.0 Guardian.Plug

Guardian.Plug contains functions that assist with interacting with Guardian via Plugs.

Guardian.Plug is not itself a plug.

Example

Guardian.Plug.sign_in(conn, user)
Guardian.Plug.sign_in(conn, user, :access)

# stores this JWT in a different location (keyed by :secret)
Guardian.Plug.sign_in(
  conn,
  user,
  :access,
  %{ claims: "i", make: true, key: :secret }
)

Example

Guardian.Plug.sign_out(conn) # sign out all sessions
Guardian.Plug.sign_out(conn, :secret) # sign out only the :secret session

To sign in to an api action (i.e. not store the jwt in the session, just on the conn)

Example

Guardian.Plug.api_sign_in(conn, user)
Guardian.Plug.api_sign_in(conn, user, :access)

# Store the JWT on the conn
Guardian.Plug.api_sign_in(
  conn,
  user,
  :access,
  %{
    claims: "i",
    make: true,
    key: :secret
  }
)

Then use the Guardian.Plug helpers to look up current_token, claims and current_resource.

Example

Guardian.Plug.current_token(conn)
Guardian.Plug.claims(conn)
Guardian.Plug.current_resource(conn)

Summary

Functions

api_sign_in(conn, object)

Sign in a resource for API requests (that your configured serializer knows about). This is not stored in the session but is stored in the assigns only

api_sign_in(conn, object, type)

Sign in a resource (that your configured serializer knows about) only in the assigns. For use without a web session

api_sign_in(conn, object, type, new_claims)

Same as api_sign_in/3 but also encodes all claims into the JWT

authenticated?(conn)

A simple check to see if a request is authenticated

authenticated?(conn, type)

A simple check to see if a request is authenticated

claims(conn, the_key \\ :default)

Fetch the currently verified claims from the current request

current_resource(conn, the_key \\ :default)

Fetch the currently authenticated resource if loaded, optionally located at a location (key)

current_token(conn, the_key \\ :default)

Fetch the currently verified token from the request. Optionally located at a location (key)

sign_in(conn, object)

Sign in a resource (that your configured serializer knows about) into the current web session

sign_in(conn, object, type)

Sign in a resource (that your configured serializer knows about) into the current web session

sign_in(conn, object, type, new_claims)

Same as sign_in/3 but also encodes all claims into the JWT

sign_out(conn, the_key \\ :all)

Sign out of a session

Functions

api_sign_in(conn, object)

Specs

api_sign_in(Plug.Conn.t, any) :: Plug.Conn.t

Sign in a resource for API requests (that your configured serializer knows about). This is not stored in the session but is stored in the assigns only.

api_sign_in(conn, object, type)

Specs

api_sign_in(Plug.Conn.t, any, atom | String.t) :: Plug.Conn.t

Sign in a resource (that your configured serializer knows about) only in the assigns. For use without a web session.

By specifying the ‘type’ of the token, you’re setting the typ field in the JWT.

api_sign_in(conn, object, type, new_claims)

Specs

api_sign_in(Plug.Conn.t, any, atom | String.t, map) :: Plug.Conn.t

Same as api_sign_in/3 but also encodes all claims into the JWT.

The :key key in the claims map is special. In that it sets the location of the storage.

The :perms key will provide the ability to encode permissions into the token. The value at :perms should be a map

Example

Guardian.Plug.api_sign_in(
  conn,
  user,
  :token,
  perms: %{default: [:read, :write]}
)
authenticated?(conn)

Specs

authenticated?(Plug.Conn.t) :: atom

A simple check to see if a request is authenticated

authenticated?(conn, type)

Specs

authenticated?(Plug.Conn.t, atom) :: atom

A simple check to see if a request is authenticated

claims(conn, the_key \\ :default)

Specs

claims(Plug.Conn.t, atom) ::
  {:ok, map} |
  {:error, atom | String.t}

Fetch the currently verified claims from the current request

current_resource(conn, the_key \\ :default)

Specs

current_resource(Plug.Conn.t, atom) :: any | nil

Fetch the currently authenticated resource if loaded, optionally located at a location (key)

current_token(conn, the_key \\ :default)

Specs

current_token(Plug.Conn.t, atom) :: String.t | nil

Fetch the currently verified token from the request. Optionally located at a location (key)

sign_in(conn, object)

Specs

sign_in(Plug.Conn.t, any) :: Plug.Conn.t

Sign in a resource (that your configured serializer knows about) into the current web session.

sign_in(conn, object, type)

Specs

sign_in(Plug.Conn.t, any, atom | String.t) :: Plug.Conn.t

Sign in a resource (that your configured serializer knows about) into the current web session.

By specifying the ‘type’ of the token, you’re setting the typ field in the JWT.

sign_in(conn, object, type, new_claims)

Specs

sign_in(Plug.Conn.t, any, atom | String.t, map) :: Plug.Conn.t

Same as sign_in/3 but also encodes all claims into the JWT.

The :key key in the claims map is special in that it sets the location of the storage.

The :perms key will provide the ability to encode permissions into the token. The value at :perms should be a map

Example

Guardian.sign_in(conn, user, :access, perms: %{default: [:read, :write]})
sign_out(conn, the_key \\ :all)

Sign out of a session.

If no key is specified, the entire session is cleared. Otherwise, only the location specified is cleared