Guardian provides a singular interface for authentication in Elixir applications that is token based.

Tokens should be:

• tamper proof
• include a payload (claims)

JWT tokens (the default) fit this description.

When using Guardian, you'll need an implementation module.

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

  def subject_for_token(resource, _claims), do: {:ok, to_string(resource.id)}
  def resource_from_claims(claims) do
    find_me_a_resource(claims["sub"]) # {:ok, resource} or {:error, reason}
  end
end

This module is what you will use to interact with tokens in your application.

When you use Guardian, the :otp_app option is required. Any other option provided will be merged with the configuration in the config files.

The Guardian module contains some generated functions and some callbacks.

Generated function

default_token_type()

Overridable.

Provides the default token type for the token - "access"

Token types allow a developer to mark a token as having a particular purpose. Different types of tokens can then be used specifically in your app.

Types may include (but are not limited to):

• "access"
• "refresh"

Access tokens should be short lived and are used to access resources on your API. Refresh tokens should be longer lived and whose only purpose is to exchange for a shorter lived access token.

To specify the type of token, use the :token_type option in the encode_and_sign function.

Token type is encoded into the token in the "typ" field.

Return - a string.

peek(token)

Inspect a tokens payload. Note that this function does no verification.

Return - a map including the :claims key.

config(), config(key, default \\ nil)

Without argument config will return the full configuration Keyword list.

When given a key and optionally a default, config will fetch a resolved value contained in the key.

See Guardian.Config.resolve_value/1

encode_and_sign(resource, claims \\ %{}, opts \\ [])

Creates a signed token.

Arguments:

• resource - The resource to represent in the token (i.e. the user)
• claims - Any custom claims that you want to use in your token
• opts - Options for the token module and callbacks

For more information on options see the documentation for your token module.

# Provide a token using the defaults including the default_token_type
{:ok, token, full_claims} = MyApp.Guardian.encode_and_sign(user)

# Provide a token including custom claims
{:ok, token, full_claims} = MyApp.Guardian.encode_and_sign(user, %{some: "claim"})

# Provide a token including custom claims and a different token type/ttl
{:ok, token, full_claims} =
  MyApp.Guardian.encode_and_sign(user, %{some: "claim"}, token_type: "refresh" ttl: {4, :weeks})

The encode_and_sign function calls a number of callbacks on your implementation module. See Guardian.encode_and_sign/4

decode_and_verify(token, claims_to_check \\ %{}, opts \\ [])

Decodes a token and verifies the claims are valid.

Arguments:

• token - The token to decode
• claims_to_check - A map of the literal claims that should be matched. If any of the claims do not literally match verification fails
• opts - The options to pass to the token module and callbacks

Callbacks:

decode_and_verify calls a number of callbacks on your implementation module, See Guardian.decode_and_verify/4

# Decode and verify using the defaults
{:ok, claims} = MyApp.Guardian.decode_and_verify(token)

# Decode and verify with literal claims check.
# If the claims in the token do not match those given verification will fail
{:ok, claims} = MyApp.Guardian.decode_and_verify(token, %{match: "claim"})

# Decode and verify with literal claims check and options.
# Options are passed to your token module and callbacks
{:ok, claims} = MyApp.Guardian.decode_and_verify(token, %{match: "claim"}, some: "secret")

revoke(token, opts \\ [])

Revoke a token.

Note: this is entirely dependent on your token module and implementation callbacks.

{:ok, claims} = MyApp.Guardian.revoke(token, some: "option")

refresh(token, opts \\ [])

Refreshes the time on a token. This is used to re-issue a token with essentially the same claims but with a different expiry.

Tokens are verified before performing the refresh to ensure only valid tokens may be refreshed.

Arguments:

• token - The old token to refresh
• opts - Options to pass to the Implementation Module and callbacks

Options:

• :ttl - The new ttl. If not specified the default will be used.

{:ok, {old_token, old_claims}, {new_token, new_claims}} =
  MyApp.Guardian.refresh(old_token, ttl: {1, :hour})

See Guardian.refresh

exchange(old_token, from_type, to_type, options)

Exchanges one token for another of a different type. Especially useful to trade in a refresh token for an access one.

Tokens are verified before performing the exchange to ensure that only valid tokens may be exchanged.

Arguments:

• old_token - The existing token you wish to exchange.
• from_type - The type the old token must be. Can be given a list of types.
• to_type - The new type of token that you want back.
• options - The options to pass to the token module and callbacks.

Options:

Options may be used by your token module or callbacks.

• ttl - The ttl for the new token

See Guardian.exchange