Joken v2.0.0-rc2 Joken.Hooks behaviour View Source

Behaviour for defining hooks into Joken’s lifecycle.

Hooks are passed to Joken functions or added to Joken.Config through the add_hook/2 macro. They can change the execution flow of a token configuration.

Hooks are executed in a reduce_while call and so must always return either:

  • {:halt, result} -> when you want to abort execution
  • {:cont, result} -> when you want to let other hooks execute

When you want to let execution proceed, result must be a tuple where:

  • the first element is the status: :ok | {:error, reason}
  • other arguments are what is expected as the arguments for the next hook in the chain

For example:

defmodule MyHaltHook do
  use Joken.Hooks

  @impl true
  def before_generate(_hook_options, _extra_claims, _token_config) do
    {:halt, {:error, :no_go}}
  end
end

In this case MyHaltHook will abort execution returning {:error, :no_go}.

Another example:

defmodule CheckVerifyError do
  use Joken.Hooks
  require Logger

  @impl true
  def after_verify(hook_options, status, bearer_token, claims_map, signer) do
    case status do
      {:error, :invalid_signature} = err ->
        Logger.error("Check signer!!!")
        {:halt, err}

      :ok ->
        {:cont, {:ok, bearer_token, claims_map, signer}}
    end
  end
end

Joken.Config

When you create a module that has use Joken.Config it automatically implements this behaviour with overridable functions. You can simply override a callback implementation directly and it will be triggered when using any of the generated functions. Example:

defmodule HookToken do
  use Joken.Config

  @impl Joken.Hooks
  def before_generate(extra, token_config) do
    IO.puts("Before generating claims")
    {:ok, extra, token_config}
  end
end

Now if we call HookToken.generate_claims/1 it will call our callback.

Also, in Joken.Config a macro is imported for adding hooks with options. Example:

defmodule ManyHooks do
  use Joken.Config

  add_hook(JokenJwks, jwks_url: "http://someserver.com/.well-known/certs")
end

Link to this section Summary

Link to this section Types

Link to this type error_tuple() View Source
error_tuple() :: {:error, term()}
Link to this type halt_tuple() View Source
halt_tuple() :: {:halt, term()}
Link to this type hook_options() View Source
hook_options() :: Keyword.t()
Link to this type status() View Source
status() :: :ok | error_tuple()
Link to this type validate_result() View Source
validate_result() :: {:ok, Joken.claims()} | error_tuple()

Link to this section Callbacks

Link to this callback after_generate(hook_options, status, arg2) View Source
after_generate(hook_options(), status(), Joken.claims()) ::
  {:cont, {status(), Joken.claims()}} | halt_tuple()

Called after Joken.generate_claims/3

Link to this callback after_sign(hook_options, status, arg2, arg3, arg4) View Source

Called after Joken.encode_and_sign/3

Link to this callback after_validate(hook_options, status, arg2, arg3) View Source

Called after Joken.validate/4

Link to this callback after_verify(hook_options, status, arg2, arg3, arg4) View Source

Called after Joken.verify/3

Link to this callback before_generate(hook_options, status, extra, arg3) View Source
before_generate(
  hook_options(),
  status(),
  extra :: Joken.claims(),
  Joken.token_config()
) ::
  {:cont, {status(), extra :: Joken.claims(), Joken.token_config()}}
  | halt_tuple()

Called before Joken.generate_claims/3

Link to this callback before_sign(hook_options, status, arg2, arg3) View Source
before_sign(hook_options(), status(), Joken.claims(), Joken.Signer.t()) ::
  {:cont, {status(), Joken.claims(), Joken.Signer.t()}} | halt_tuple()

Called before Joken.encode_and_sign/3

Link to this callback before_validate(hook_options, status, arg2, arg3) View Source
before_validate(hook_options(), status(), Joken.claims(), Joken.token_config()) ::
  {:cont, {status(), Joken.claims(), Joken.token_config()}} | halt_tuple()

Called before Joken.validate/4

Link to this callback before_verify(hook_options, status, arg2, arg3) View Source

Called before Joken.verify/3