View Source Guardian.Token.Jwt (Guardian v2.3.1)

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

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

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

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

Link to this section Summary

Functions

Builds the default claims for all JWT tokens.

Create a token. Uses the claims, encodes and signs the token.

Decodes the token and validates the signature.

Exchange a token of one type to another.

Inspect the JWT without any validation or signature checking.

Revoking a JWT by default does not do anything.

Generate unique token id.

Link to this section Functions

Link to this function

build_claims(mod, resource, sub, claims \\ %{}, options \\ [])

View Source

Builds the default claims for all JWT tokens.

Note:

  • aud is set to the configured issuer unless aud is set

Options:

Options may override the defaults found in the configuration.

  • token_type - Override the default token type
  • ttl - The time to live. See Guardian.Token.ttl type
Link to this function

create_token(mod, claims, options \\ [])

View Source

Create a token. Uses the claims, encodes and signs the token.

The signing secret will be found first from the options. If not specified the secret key from the configuration will be used.

Configuration:

  • secret_key The secret key to use for signing

Options:

  • secret The secret key to use for signing
  • headers The Jose headers that should be used
  • allowed_algos

The secret may be in the form of any resolved value from Guardian.Config.

Link to this function

decode_token(mod, token, options \\ [])

View Source

Decodes the token and validates the signature.

Options:

  • secret - Override the configured secret. Guardian.Config.config_value is valid
  • allowed_algos - A list of allowable algos
Link to this function

exchange(mod, old_token, from_type, to_type, options)

View Source

Exchange a token of one type to another.

Type is encoded in the typ field.

Options:

  • secret - Override the configured secret. Guardian.Config.config_value is valid
  • allowed_algos - A list of allowable algos
  • ttl - The time to live. See Guardian.Token.ttl type

Inspect the JWT without any validation or signature checking.

Return an map with keys: headers and claims.

Link to this function

refresh(mod, old_token, options)

View Source

Refresh the token

Options:

  • secret - Override the configured secret. Guardian.Config.config_value is valid
  • allowed_algos - A list of allowable algos
  • ttl - The time to live. See Guardian.Token.ttl type
Link to this function

revoke(mod, claims, token, options)

View Source

Revoking a JWT by default does not do anything.

You'll need to track the token in storage in some way and revoke in your implementation callbacks.

See GuardianDb for an example.

Generate unique token id.

Link to this function

verify_claims(mod, claims, options)

View Source

Verifies the claims.

Options: