Deals with things JWT This module should not be used directly. It is intended to be used by Guardian on behalf of your implementation as it's token module.

Token types are encoded in the typ field.

Configuration

Configuration should be added to the implementation module in either the configuration file or as options to use Guardian

Required

• issuer - The issuer of the token. Your application name/id
• secret_key - The secret key to use for the implementation module. This may be any resolvable value for Guardian.Config

Optional

• token_verify_module - default Guardian.Token.Jwt.Verify. The module that verifies the claims
• allowed_algos - The allowed algos to use for encoding and decoding. See JOSE for available. Default ["HS512"]
• ttl - The default time to live for all tokens. See the type in Guardian.ttl
• token_ttl a map of token_type to ttl. Set specific ttls for specific types of tokens
• allowed_drift The drift that is allowed when decoding/verifying a token in milli seconds
• verify_issuer Verify that the token was issued by the configured issuer. Default false
• secret_fetcher A module used to fetch the secret. Default: Guardian.Token.Jwt.SecretFetcher

Options:

These options are available to encoding and decoding:

• secret The secret key to use for signing
• headers The Jose headers that should be used
• allowed_algos
• token_type - Override the default token type
• ttl - The time to live. See Guardian.Token.ttl type

Example

# encode a simple token
{:ok, token, claims} =
  MyApp.Tokens.encode_and_sign(resource)

# encode a token with custom claims
{:ok, token, claims} =
  MyApp.Tokens.encode_and_sign(resource, %{some: "claim"})

# encode a token with a custom type
{:ok, token, claims} =
  MyApp.Tokens.encode_and_sign(resource, %{}, token_type: "refresh")

# encode a token with custom options
{:ok, token, claims} =
  MyApp.Tokens.encode_and_sign(
    resource,
    %{},
    secret: {MyModule, :get_my_secret, ["some", "args"]},
    ttl: {4, :weeks},
    token_type: "refresh"
  )

# decode a token
{:ok, claims} =
  MyApp.Tokens.decode_and_verify(token)

# decode a token and check literal claims
{:ok, claims} =
  MyApp.Tokens.decode_and_verify(token, %{"typ" => "refresh"})

# decode a token and check literal claims with options
{:ok, claims} =
  MyApp.Tokens.decode_and_verify(token, %{"typ" => "refresh"}, secret: {MyModule, :get_my_secret, ["some", "args"]})

# exchange a token
{:ok, {old_token, old_claims}, {new_token, new_claims}} =
  MyApp.Tokens.exchange(old_token, ["access", "refresh"], "access")

# exchange a token with options
{:ok, {old_token, old_claims}, {new_token, new_claims}} =
  MyApp.Tokens.exchange(old_token, ["access", "refresh"], "access" secret: {MyModule, :get_my_secret, ["some", "args"]}, ttl: {1, :hour})

# refresh a token using defaults
{:ok, {old_token, old_claims}, {new_token, new_claims}} = MyApp.Tokens.refresh(old_token)

# refresh a token using options
{:ok, {old_token, old_claims}, {new_token, new_claims}} =
  MyApp.Tokens.refresh(old_token, ttl: {1, :week}, secret: {MyMod, :get_secret, ["some", "args"})

Token verify module

The token verify module by default is Guardian.Token.Jwt.Verify.

This module implements the Guardian.Token.Verify behaviour. To customize your token validation you have 2 options.

1. Implement the verify_claims callback on your implementation
2. use Guardian.Token.Verify in your own module and use that.

To create your own verify module use Guardian.Token.Verify and configure your implementation to use it either through config files or when you setup your implementation.

defmodule MyApp.Tokens do
  use Guardian, otp_app: :my_app,
                token_verify_module: MyVerifyModule
  # ... snip
end

### SecretFetcher

When you need dynamic secret verification, you should use a custom
[`Guardian.Token.Jwt.SecretFetcher`](Guardian.Token.Jwt.SecretFetcher.html) module.
This will allow you to use the header values to determine dynamically the
key that should be used.

defmodule MyCustomSecretFetcher do use Guardian.Token.Jwt.SecretFetcher

def fetch_signing_secret(impl_module, opts) do

# fetch the secret for signing

end

def fetch_verifying_secret(impl_module, token_headers, opts) do

# fetch the secret for verifying the token

end end