View Source Authex

Build Status Authex Version

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

installation

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

Documentation

See HexDocs for additional documentation.

example

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

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.