guard v0.9.0 Guard.Guardian

Link to this section Summary

Functions

An optional callback invoked after the token has been generated and signed

An optional callback invoked after sign in has been called

Checks to see if all of the permissions provided are present in the permissions (previously extracted from claims)

Checks to see if any of the permissions provided are present in the permissions (previously extracted from claims)

Lists all permissions in a normalized way using %{permission_set_name => [permission_name, …]}

An optional callback invoked before sign out has happened

An optional callback that allows the claims to be modified while they’re being built. This is useful to hook into the encoding lifecycle

Fetches the configuration for this module

Returns a resolved value of the configuration found at a key

Decodes and verifies a token using the configuration on the implementation module

Decodes permissions from the permissions found in claims (encoded to integers) or from a list of permissions

Decodes permissions directly from a claims map. This does the same as decode_permissions but will fetch the permissions map from the "pem" key where Guardian.Permissions.Bitwise places them when it encodes them into claims

The default type of token for this module

Encodes the claims. See Guardian.encode_and_sign for more information

Encodes the permissions provided into numeric form

Encodes the permissions provided into the claims in the "pem" key. Permissions are encoded into an integer inside the token corresponding with the value provided in the configuration

Exchanges a token of one type for another

An optional callback invoked when a token is exchanged

An optional callback invoked when a token is refreshed

An optional callback invoked when a token is revoked

An optional callback invoked after the claims have been validated

Provides the content of the token but without verification of either the claims or the signature

Fetches the resource that is represented by claims

Fetch the resource and claims directly from a token

Revoke a token

Fetches the subject for a token for the provided resource and claims The subject should be a short identifier that can be used to identify the resource

Validates that all permissions provided exist in the configuration

An optional callback to add custom verification to claims when decoding a token

Link to this section Functions

Link to this function after_encode_and_sign(r, claims, token, _)

An optional callback invoked after the token has been generated and signed.

Callback implementation for Guardian.after_encode_and_sign/4.

Link to this function after_sign_in(conn, r, t, c, o)

An optional callback invoked after sign in has been called

By returning an error the sign in will be halted

  • Note that if you return an error, a token still may have been generated

Callback implementation for Guardian.after_sign_in/5.

Checks to see if all of the permissions provided are present in the permissions (previously extracted from claims)

iex> claims |> MyTokens.decode_permissions() |> all_permissions?(%{user_actions: [:books, :music]}) true

Checks to see if any of the permissions provided are present in the permissions (previously extracted from claims)

iex> claims |> MyTokens.decode_permissions() |> any_permissions?(%{user_actions: [:books, :music]}) true

Link to this function available_permissions()
available_permissions() :: Guardian.Permissions.Bitwise.t()

Lists all permissions in a normalized way using %{permission_set_name => [permission_name, …]}

Link to this function before_sign_out(conn, location, opts)

An optional callback invoked before sign out has happened

Callback implementation for Guardian.before_sign_out/3.

Link to this function build_claims(c, arg2, opts)

An optional callback that allows the claims to be modified while they’re being built. This is useful to hook into the encoding lifecycle

Callback implementation for Guardian.build_claims/3.

Link to this function config()
config() :: Keyword.t()

Fetches the configuration for this module

Link to this function config(key, default \\ nil)
config(atom() | String.t(), any()) :: any()

Returns a resolved value of the configuration found at a key

See Guardian.Config.resolve_value

Link to this function decode_and_verify(token, claims_to_check \\ %{}, opts \\ [])
decode_and_verify(
  Guardian.Token.token(),
  Guardian.Token.claims(),
  Guardian.options()
) :: {:ok, Guardian.Token.claims()} | {:error, any()}

Decodes and verifies a token using the configuration on the implementation module.

See Guardian.decode_and_verify

Decodes permissions from the permissions found in claims (encoded to integers) or from a list of permissions.

iex> MyTokens.decode_permissions(%{default: [:public_profile]}) %{default: [:public_profile]}

iex> MyTokens.decode_permissions{%{“default” => 1, “user_actions” => 1}} %{default: [:public_profile], user_actions: [:books]}

When using integers (after encoding to claims), unknown bit positions are ignored.

iex> MyTokens.decode_permissions(%{"default" => -1})
%{default: [:public_profile, :user_about_me]}
Link to this function decode_permissions_from_claims(arg1)
decode_permissions_from_claims(Guardian.Token.claims()) ::
  Guardian.Permissions.Bitwise.t()

Decodes permissions directly from a claims map. This does the same as decode_permissions but will fetch the permissions map from the "pem" key where Guardian.Permissions.Bitwise places them when it encodes them into claims.

Link to this function default_token_type()
default_token_type() :: String.t()

The default type of token for this module

Link to this function encode_and_sign(resource, claims \\ %{}, opts \\ [])
encode_and_sign(any(), Guardian.Token.claims(), Guardian.options()) ::
  {:ok, Guardian.Token.token(), Guardian.Token.claims()} | {:error, any()}

Encodes the claims. See Guardian.encode_and_sign for more information

Encodes the permissions provided into numeric form

iex> MyTokens.encode_permissions!(%{user_actions: [:books, :music]}) %{user_actions: 9}

Link to this function encode_permissions_into_claims!(claims, perms)

Encodes the permissions provided into the claims in the "pem" key. Permissions are encoded into an integer inside the token corresponding with the value provided in the configuration.

Link to this function exchange(token, from_type, to_type, opts \\ [])
exchange(
  token :: Guardian.Token.token(),
  from_type :: String.t() | [String.t(), ...],
  to_type :: String.t(),
  options :: Guardian.options()
) ::
  {:ok, {Guardian.Token.token(), Guardian.Token.claims()},
   {Guardian.Token.token(), Guardian.Token.claims()}}
  | {:error, any()}

Exchanges a token of one type for another.

See Guardian.exchange for more information

Link to this function load_resource(arg)
Link to this function on_exchange(old_stuff, new_stuff, options)

An optional callback invoked when a token is exchanged

Callback implementation for Guardian.on_exchange/3.

Link to this function on_refresh(old_stuff, new_stuff, options)

An optional callback invoked when a token is refreshed

Callback implementation for Guardian.on_refresh/3.

Link to this function on_revoke(claims, token, options)

An optional callback invoked when a token is revoked

Callback implementation for Guardian.on_revoke/3.

Link to this function on_verify(claims, token, options)

An optional callback invoked after the claims have been validated

Callback implementation for Guardian.on_verify/3.

Link to this function peek(token)
peek(String.t()) :: map()

Provides the content of the token but without verification of either the claims or the signature

Claims will be present at the :claims key.

See Guardian.peek for more information

Refresh a token.

See Guardian.refresh for more information

Link to this function resource_from_claims(claims)

Fetches the resource that is represented by claims.

For JWT this would normally be found in the sub field

Callback implementation for Guardian.resource_from_claims/1.

Link to this function resource_from_token(token, claims_to_check \\ %{}, opts \\ [])
resource_from_token(
  token :: Guardian.Token.token(),
  claims_to_check :: Guardian.Token.claims() | nil,
  opts :: Guardian.options()
) ::
  {:ok, Guardian.Token.resource(), Guardian.Token.claims()} | {:error, any()}

Fetch the resource and claims directly from a token

See Guardian.resource_from_token for more information

Link to this function revoke(token, opts \\ [])
revoke(Guardian.Token.token(), Guardian.options()) ::
  {:ok, Guardian.Token.claims()} | {:error, any()}

Revoke a token.

See Guardian.revoke for more information

Link to this function subject_for_token(user, arg2)

Fetches the subject for a token for the provided resource and claims The subject should be a short identifier that can be used to identify the resource

Callback implementation for Guardian.subject_for_token/2.

Link to this function validate_permissions!(map)

Validates that all permissions provided exist in the configuration.

iex> MyTokens.validate_permissions!(%{default: [:user_about_me]})

iex> MyTokens.validate_permissions!(%{not: [:a, :thing]}) raise Guardian.Permissions.Bitwise.PermissionNotFoundError

Link to this function verify_claims(claims, options)

An optional callback to add custom verification to claims when decoding a token

Returning {:ok, claims} will allow the decoding to continue Returning {:error, reason} will stop the decoding and return the error

Callback implementation for Guardian.verify_claims/2.