README.md

# Authex

[![Build Status](https://travis-ci.org/nsweeting/authex.svg?branch=master)](https://travis-ci.org/nsweeting/authex)
[![Authex Version](https://img.shields.io/hexpm/v/authex.svg)](https://hex.pm/packages/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`:

```elixir
def deps do
  [
    {:authex, "~> 0.1.4"}
  ]
end
```

## Documentation

See [HexDocs](https://hexdocs.pm/authex) for additional documentation.

## Configuration

Before starting, we should configure Authex. At a minimum, we need to add a secret from which our tokens will be signed with. There is a convenient mix task available for this.

```
mix authex.gen.secret
```

We should now add this secret to our config. In production this should be set via an env var. By default, authex will pick up the env var `AUTH_SECRET` if we have not set one via config.

```elixir
config :authex, [
  # REQUIRED
  # The secret used to sign tokens with.
  secret: "mysecret",

  # OPTIONAL
  # A blacklist module, or false if disabled.
  blacklist: false,
  # The default serializer module.
  serializer: Authex.Serializer.Basic,
  # The default algorithm used to sign tokens.
  default_alg: :hs256,
  # The default iss claim used in tokens.
  default_iss: nil,
  # The default aud claim used in tokens.
  default_aud: nil,
  # The default time to live for tokens in seconds.
  default_ttl: 3600,
  # The default module, function, and arg used to generate the jti claim.
  jti_mfa: {UUID, :uuid4, [:hex]}
]
```

The above config is all the defaults "out of the box".

## Creating Tokens

At the heart of token creation is the `Authex.Token` struct. This struct is simply a wrapper around the typical JWT claims. The only additional item is the `:scopes` key.

We can easily create `Authex.Token` structs using the `Authex.token/2` function.

```elixir
Authex.token(sub: 1, scopes: ["admin/read"])
```

The above would create an `Authex.Token` struct for a user with an id of 1, and with "admin/read" authorization.

## Signing Tokens

Once we have a `Authex.Token` struct, we can sign it to create a compact token binary. This is what we will use for authentication and authorization for our API.

```elixir
[sub: 1, scopes: ["admin/read"]]
|> Authex.token()
|> Authex.sign()
```

## Verifying Tokens

Once we have compact token binary, we can verify it and turn it back to an `Authex.Token` struct.

```elixir
[sub: 1, scopes: ["admin/read"]]
|> Authex.token()
|> Authex.sign()
|> Authex.verify()
```


## Creating Tokens with Serializers

Typically, we want to be able to create tokens from another source of data. This could be something like a `User` struct. We also will want to take a token and turn it back into a `User` struct.

To do this, we will create a serializer. A serializer is simply a module that adopts the `Authex.Serializer` behaviour.

```elixir
defmodule MyApp.TokenSerializer do
  use Authex.Serializer

  def handle_from_token(%Authex.Token{sub: sub, scopes: scopes}) do
    %MyApp.User{id: sub, scopes: scopes}
  end

  def handle_for_token(%MyApp.User{id: id, scopes: scopes}) do
    Authex.Token.new([sub: id, scopes: scopes])
  end
end
```

We will then want to define our serializer in our config.

```elixir
config :authex, [
  serializer: MyApp.TokenSerializer,
]
```

We can now easily create compact tokens from our `User` structs using the `Authex.for_token/1` function.

```elixir
user = %MyApp.User{id: 1, scopes: []}
Authex.for_token(user)
```

We can also turn compact tokens back into our `User` structs using the `Authex.from_token/1` function.

```elixir
user = %MyApp.User{id: 1, scopes: []}
compact_token = Authex.for_token(user)
Authex.from_token(compact_token)
```

## Authenticating Endpoints

We can authenticate a Phoenix controller using the `Authex.Plug.Authentication` plug. This plug looks for the `Authenicate: Bearer mytoken` header. It will then verify, and deserialize the token using our configured serializer.

We can access our current user from the conn using the `Authex.current_user/1` function.

By default, if authentication fails, the plug sends the conn to the `Authex.Plug.Unauthorized` plug. This plug will put a `401` status into the conn with the body `"Unauthorized"`. We can configure our own unauthorized plug by passing it as an option to the `Authex.Plug.Authentication` plug.

```elixir
defmodule MyApp.Web.UserController do
  use MyApp.Web, :controller

  plug :authenticate

  def show(conn, _params) do
    with {:ok, %{id: id}} <- Authex.current_user(conn),
         {:ok, user} <- MyApp.Users.get(id)
    do
      render(conn, "show.json", user: user)
    end
  end

  # Authenticates the user, and sends them to our custom plug if it fails.
  defp authenticate(conn, _opts) do
    opts = Authex.Plug.Authentication.init([unauthorized: MyApp.UnauthorizedPlug])
    Authex.Plug.Authentication.call(conn, opts)
  end
end
```

## Authorizing Endpoints

We can authorize a Phoenix controller using the `Authex.Plug.Authorization` plug. This plug checks the scopes of the token and compares them to the "permits" allowed for the controller action.

Authorization works by combining the "permits" with the "type" of request that is being made.

For example, with our controller below, we are permitting "user" and "admin" access. The show action would be a `GET` request, and would therefore be a "read" type.

Requests are bucketed under the following types:

  * GET - read
  * HEAD - read
  * PUT - write
  * PATCH - write
  * POST - write
  * DELETE - delete

So, in order to access the show action, our token would require one of the following scopes: `["user/read", "admin/read"]`. Or, the token would require `["user/write", "admin/write"]` to access the update action.

By default, if authorization fails, the plug sends the conn to the `Authex.Plug.Forbidden` plug. This plug will put a `403` status into the conn with the body `"Forbidden"`. We can configure our own forbidden plug by passing it as an option to the `Authex.Plug.Authorization` plug.

```elixir
defmodule MyApp.Web.UserController do
  use MyApp.Web, :controller

  plug :authenticate
  plug :authorize, permits: ["user", "admin"]

  def show(conn, _params) do
    with {:ok, %{id: id}} <- Authex.current_user(conn),
         {:ok, user} <- MyApp.Users.get(id)
    do
      render(conn, "show.json", user: user)
    end
  end

  # These should be moved to an imported module.

  def authenticate(conn, _opts) do
    opts = Authex.Plug.Authentication.init([unauthorized: MyApp.UnauthorizedPlug])
    Authex.Plug.Authentication.call(conn, opts)
  end

  def authorize(conn, opts) do
    opts = Authex.Plug.Authorization.init([forbidden: MyApp.ForbiddenPlug] ++ opts)
    Authex.Plug.Authorization.call(conn, opts)
  end
end
```

## Blacklisting Tokens

Authex includes the ability to blacklist tokens. The recommended way to do this is with the with [Authex.Blacklist.Redis](https://github.com/nsweeting/authex_blacklist_redis) library. As you can tell by its name, it uses Redis as the blacklist storage medium. Details on setup and config are available for its repo.

To blacklist a token, simply pass an `Authex.Token` struct, or binary jti claim to `Authex.blacklist/1`. To check whether a token is blacklisted, simply call `Authex.blacklisted?/1` with a token or binary jti.

```elixir
token = Authex.token()
Authex.blacklist(token)
Authex.blacklisted?(token)
```

By default, if we configure a blacklist via the authex config options, our `Authex.verify/1` process will also check the blacklist. The same process is used with the `Authex.Plug.Authorization` plug.

Alternatively, you can setup your own blacklist by `use`ing the `Authex.Blacklist` behaviour. The module must implement `handle_get/1`, `handle_set/1` and `handle_del/1`. For an example usage (but not production usable) - check out a [basic example](https://github.com/nsweeting/authex/blob/master/lib/authex/blacklist/basic.ex).