Guardian v1.2.1 Guardian.Token.Jwt View Source

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

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. 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 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.

Configuration:

  • token_verify_module Default Guardian.Token.Jwt.Verify the module to use to verify the claims