<div align="center">

# `auth_plug`

The Elixir Plug that _seamlessly_ handles
all your authentication/authorization needs.

[![Build Status](](
[![ dependency status](](
<br />

## Why? 🤷

You want a way to add authentication
to your Elixir/Phoenix App
in the fewest steps and least code.
We did too. So we built `auth_plug`.

***Frustrated*** by the **complexity**
and **incomplete docs/tests**
in **_existing_ auth solutions**,
we built **`auth_plug`** to **simplify** our lives. <br />

We needed a way to ***minimise***
the steps
and **code** required
to add auth to our app(s).
With **`auth_plug`** we can **setup**
auth in any Elixir/Phoenix
App in **_less_ than 2 minutes**
with only **5 lines** of config/code
and **_one_ environment variable**.


<!-- revisit or remove this section
### Pain 😧

We try to maintain a
["beginner's mind"](
in everything we do.

There are virtually infinite options
for 3rd party Authentication.
Most are complex and unfriendly to beginners.
They require understanding the difference
between an authentication scheme, strategy or implementation.
We have used everything from
[black box](
(closed source)
services that promise the world but are consistently
painful to setup, to open source projects that
are woefully undocumented and lack automated tests
so we cannot _rely_ on them.
We got tired of compromising on the UX of auth,
so we built _exactly_ what we wanted
as the "users" of our own product.


## What? 🔐

An Elixir Plug (_HTTP Middleware_)
that a _complete_ beginner can use to add auth to a
Phoenix App
and _understand_ how it works. <br />
No macros/behaviours to `use` (_confuse_).
No complex configuration or "implementation".
Just a basic plug that uses Phoenix Sessions
and standards-based JSON Web Tokens (JWT).
Refreshingly simple. The way auth _should_ be done.

<div align="center">
  <a href="">
    <img src="" alt="auth_plug diagram" width="800">

Edit this diagram:


**`auth_plug`** protects any routes in your app
that require authentication. <br />

**`auth_plug`** is just
[57 lines](
of (_significant_)
the rest is comprehensive comments
to help _everyone understand_ how it works.
As with _all_ our code,
it's meant to be as beginner-friendly as possible.
If you get stuck or have any questions,
please [***ask***!](

## Who? 👥

We built this plug for use in _our_ products/services.
It does _exactly_ what we want it to and nothing more.
It's tested, documented and open source the way _all_ our code is.
It's **not _yet_** a **general purpose** auth solution
that _anyone_ can use.
If after reading through this you feel that
this is something you would like to have
in your own Elixir/Phoenix project,
[***tell us***!](

# How? 💡

_Before_ you attempt to use the **`auth_plug`**,
try the Heroku example version so you know what to expect: <br />


Notice how when you first visit the
page, your browser is _redirected_ to:
The the auth service handles the actual authentication
and then transparently redirects back to
with a JWT session.

For more detail on how the `Auth` service works,
please see:

If you get stuck during setup,
clone and run our fully working example:

<br />

## 1. Installation 📝

Add **`auth_plug`**
to your list of dependencies in `mix.exs`:

def deps do
    {:auth_plug, "~> 1.1.0"}
Once you've saved the `mix.exs` file,
download the dependency with:

mix deps.get

<br />

## 2. Get Your `AUTH_API_KEY` 🔑

and create a **New App**.
Once you have an App, 
you can export an `AUTH_API_KEY` environment variable.


### 2.1 Save it as an Environment Variable

Create a file called `.env` in the root directory of your app
and add the following line:

export AUTH_API_KEY=2cfxNaWUwJBq1F4nPndoEHZJ5YCCNqXbJ6Ga/2cfxNadrhMZk3iaT1L5k6Wt67c9ScbGNPz8BwLH1

The run the following command in your terminal:
source .env
That will export the environment variable AUTH_API_KEY.

Remember to add `.env` to your [`.gitignore`]( file.
echo ".env" >> .gitignore

<br />

## 3. Add `AuthPlug` to Your `router.ex` file to Protect a Route 🔒

Open the `lib/app_web/router.ex` file and locate the section:

  scope "/", AppWeb do
    pipe_through :browser

    get "/", PageController, :index

Immediately below this add the following lines of code:

  pipeline :auth, do: plug(AuthPlug, %{auth_url: ""})

  scope "/", AppWeb do
    pipe_through :browser
    pipe_through :auth
    get "/admin", PageController, :admin

> E.g:

#### _Explanation_

There are two parts to this code:

1. Create a new pipeline called `:auth` which will execute the `AuthPlug`
passing in the `auth_url` as an initialisation option.
2. Create a new scope where we `pipe_through`
both the `:browser` and `:auth` pipelines.

This means that the `"/admin"` route is protected by `AuthPlug`.

> **Note**: Ensure the route you are protecting works _without_ `AuthPlug`.
If in doubt simply comment out the line `pipe_through :auth` to check.

<br />

## 4. Attempt to view the protected route to test the authentication! 👩‍💻

Now that the `/admin` route is protected by **`auth_plug`**,
attempt to view it in your browser e.g: http://localhost:4000/admin

If you are not already authenticated,
your browser will be redirected to:

Once you have successfully authenticated with your GitHub or Google account,
you will be redirected back to `localhost:4000/admin`
where the `/admin` route will be visible.


<br />

## That's it!! 🎉

You just setup auth in a Phoenix app using **`auth_plug`**!

If you got stuck or have any questions,
[open an issue](,
we are here to help!

<br />

## Documentation

Documentation can be found at
[]( <br />
All our code is commented,
but if _anything_ is unclear,
please open an issue:

### Availiable infomation
By default using the authentication service,
`auth_plug` makes the following infomation availiable in `conn.assigns`:

jwt :: string()
person :: %{
  id :: integer() # This stays unique across providers
  auth_provider :: string()
  email :: string()
  givenName :: string() 
  picture :: string()
  # Also includes standard jwt metadata you may find useful:
  aud, exp, iat, iss

## Recommended / Relevant Reading

If you are new to Elixir Plug,
we recommend following:

To understand JSON Web Tokens,