Joken is a library for working with standard JSON Web Tokens.

It provides 4 basic operations:

• Verify: the act of confirming the signature of the JWT;
• Validate: processing validation logic on the set of claims;
• Claim generation: generate dynamic value at token creation time;
• Signature creation: encoding header and claims and generate a signature of their value.

Architecture

The core of Joken is JOSE, a library which provides all facilities to sign and verify tokens. Joken brings an easier Elixir API with some added functionality:

• Validating claims. JOSE does not provide validation other than signature verification.
• config.exs friendly. You can optionally define your signer configuration straight in your config.exs.
• Portable configuration. All your token logic can be encapsulated in a module with behaviours.
• Enhanced errors. Joken strives to be as informative as it can when errors happen be it at compilation or at validation time.
• Debug friendly. When a token fails validation, a Logger debug message will show which claim failed validation with which value. The return value, though for security reasons, does not contain these information.
• Performance. We have a benchmark suite for identifying where we can have a better performance. From this analysis came: Jason adapter for JOSE and other minor tweaks.

Usage

Joken has 3 basic concepts:

• Portable token claims configuration.
• Signer configuration.
• Hooks.

The portable token claims configuration is a map of binary keys to Joken.Claim structs and is used to dynamically generate and validate tokens.

A signer is an instance of Joken.Signer that encapsulates the algorithm and the key configuration used to sign and verify a token.

A hook is an implementation of the behaviour Joken.Hooks for easy plugging into the lifecycle of Joken operations.

There are 2 forms of using Joken:

1. Pure data structures. You can create your token configuration and signer and use them with this module for all 4 operations: verify, validate, generate and sign.

   iex> token_config = %{} # empty config
   iex> token_config = Map.put(token_config, "scope", %Joken.Claim{
   ...>   generate: fn -> "user" end,
   ...>   validate: fn val, _claims, _context -> val in ["user", "admin"] end
   ...> })
   iex> signer = Joken.Signer.create("HS256", "my secret")
   iex> {:ok, claims} = Joken.generate_claims(token_config, %{"extra"=> "claim"})
   iex> {:ok, jwt, claims} = Joken.encode_and_sign(claims, signer)

2. With the encapsulated module approach using Joken.Config. See the docs for Joken.Config for more details.

   iex> defmodule MyAppToken do
   ...>   use Joken.Config, default_signer: :pem_rs256
   ...>
   ...>   @impl Joken.Config
   ...>   def token_config do
   ...>     default_claims()
   ...>     |> add_claim("role", fn -> "USER" end, &(&1 in ["ADMIN", "USER"]))
   ...>   end
   ...> end
   iex> {:ok, token, _claims} = MyAppToken.generate_and_sign(%{"user_id" => "1234567890"})
   iex> {:ok, _claim_map} = MyAppToken.verify_and_validate(token)