README.md

Authex

Authex is a simple JWT authentication and authorization library for Elixir.

Installation

The package can be installed by adding authex to your list of dependencies in mix.exs.

In addition, we must also add a JSON encoder/decoder. Jason is recommended. But any of these will work: jiffy, jsone, jsx, ojson, Poison.

Finally, if you wish to use any of the plug functionality, make sure to add the plug dependency.

def deps do
  [
    {:authex, "~> 2.0"},
    {:jason, "~> 1.0"},
    {:plug, "~> 1.0"}
  ]
end

Documentation

See HexDocs for additional documentation.

Example

To get started, we must define our auth module:

defmodule MyApp.Auth do
  use Authex

  def start_link(opts \\\\ []) do
    Authex.start_link(__MODULE__, opts, name: __MODULE__)
  end

  # Callbacks

  @impl Authex
  def init(opts) do
    # Add any configuration listed in Authex.start_link/3

    secret = System.get_env("AUTH_SECRET") || "foobar"
    opts = Keyword.put(opts, :secret, secret)

    {:ok, opts}
  end

  @impl Authex
  def handle_for_token(%MyApp.User{} = resource, opts) do
    {:ok, [sub: resource.id, scopes: resource.scopes], opts}
  end

  def handle_for_token(_resource, _opts) do
    {:error, :bad_resource}
  end

  @impl Authex
  def handle_from_token(token, _opts) do
    # You may want to perform a database lookup for your user instead
    {:ok, %MyApp.User{id: token.sub, scopes: token.scopes}}
  end
end

And add it to your supervision tree:

children = [
  MyApp.Auth
]

We can then create, sign, and verify tokens:

token = Authex.token(MyApp.Auth, sub: 1, scopes: ["admin/read"])
compact_token = Authex.sign(MyApp.Auth, token)
{:ok, token} = Authex.verify(MyApp.Auth, compact_token)

We can also convert resources to and from tokens.

token = Authex.for_token(MyApp.Auth, user)
compact_token = Authex.sign(MyApp.Auth, token)
{:ok, token} = Authex.verify(MyApp.Auth, compact_token)
{:ok, user} = Authex.from_token(MyApp.Auth, token)

Please check out the documentation for more advanced features.

Features

• Easy to integrate with almost any app.
• Handles both authentication + authorization.
• Convert data to and from tokens.
• Handle persistence for things like blacklists.
• Batteries included for plug integration.