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 its 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. The default by Guardian.Token.JWT is {4, :weeks}
• 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 - A list of allowable algos
• token_type - Override the default token type. The default is "access"
• 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 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

If the signing secret contains a "kid" (https://tools.ietf.org/html/rfc7515#section-4.1.4) it will be passed along to the signature to provide a hint about which secret was used.

This can be useful for specifying which public key to use during verification if you're using a public/private key rotation strategy.

An example implementation of this can be found here: https://gist.github.com/mpinkston/469009001b694d3ca162894d74c9bfe3