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.

It 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 includes (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 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, will fetch a resolved value contained in the key.

See Guardian.Config.resolve_value

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

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

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

# Decode and verify with literal claims check.
# If the cliams int he 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 dependant 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