Access Token

Access token utility library based on JSON Web Token (JWT).

Installation

Add Access Token to your project's dependencies in mix.exs:

def deps do
  [{:access_token, "~> 1.0"}]
end

Fetch your project's dependencies:

$ mix deps.get

And configure the secret signing key in your application environment, usually defined in config/config.exs:

config :access_token, key: "6m/pr714TP8ijQeVdJ2gBOxuYwrD7nR/p5BhhcQ2ejURZpNYz9T//ze9mfx+TNpo"

Usage

Access Token provides a simple interface to generate and process access tokens:

iex> access_token = AccessToken.encode(%{user_id: 1})
iex> AccessToken.decode(access_token)
{:ok, %{user_id: user_id}}

See encode/2 and decode/1 for more information.

Plug

AccessToken.Plug is a plug for extracting the access token from the request.

The token may be sent by the request either via the params with key access_token or a header with name Authorization and content Bearer <access token>.

To use it, just plug it into the desired module:

plug AccessToken.Plug

If present, the access token will be accessible through the assigns map of the connection.

conn.assigns[:access_token]

Options

:param - The name of the HTTP request parameter to check for the access token. Default value is access_token.
```
plug AccessToken.Plug, param: "token"
```
:http_header - The name of the HTTP request header to check for the access token. Default value is authorization.
```
plug AccessToken.Plug, http_header: "custom-authorization"
```
:http_header_prefix - The prefix of the HTTP request authorization header. Default value is Bearer.
```
plug AccessToken.Plug, http_header_prefix: "Token"
```
:assign_to - The name of the key to assign the access token. Defaults to :access_token
```
plug AccessToken.Plug, assign_to: :token
```
:error_status - The status code to be returned in case the access token is not present. The status can be nil, an integer or an atom. The list of allowed atoms is available in Plug.Conn.Status. Defaults to :unauthorized
```
plug AccessToken.Plug, error_status: :forbidden
```
:error_handler - The function to be called in case the access token is not present. The :error_handler is set using a {module, function, args} tuple. The function will receive the conn followed by the list of args provided.
```
plug AccessToken.Plug,
  error_handler: {Phoenix.Controller, :render, [MyAppWeb.ErrorView, "401.json"]}
```

Documentation

Documentation is available at https://hexdocs.pm/access_token

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fertapric/access_token. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Running tests

Clone the repo and fetch its dependencies:

$ git clone https://github.com/fertapric/access_token.git
$ cd access_token
$ mix deps.get
$ mix test

Building docs

$ mix docs

License

Access Token is released under the MIT License.

Author

Fernando Tapia Rico, @fertapric