README.md

auth_plug example

A working example of auth_plug showing you how simple it is to use auth in your Phoenix App!

Why?

The purpose of this project/repo is to demonstrate how simple it is to integrate auth_plug into any Phoenix Web App/API. Our objective was to build a re-useable auth system that we could add to any Phoenix App in less than 5 minutes.

What?

The most basic example of using auth_plug to add Authentication to a Phoenix App and showcase a protected route.

Before you attempt to use the auth_plug, try the Heroku example version so you know what to expect: https://auth-plug.fly.dev/admin

You will be redirected to:

Once you have logged in, you will be redirected back:

Who?

This example is for us @dwyl who will be using auth_plug in all our projects and more specifically for our App. But we have made it as generic as possible to show that anyone can use (an instance of the) Auth Service to add Auth to any app in less than 2 minutes!

How?

1. Create New Phoenix App

mix phx.new app --no-ecto --no-webpack

When asked if you want to Fetch and install dependencies? [Yn] Type Y followed by the Enter key.

This example only needs the bare minimum Phoenix; we don't need any JavaScript or Database.
For more info, see: https://hexdocs.pm/phoenix/Mix.Tasks.Phx.New.html
The beauty is that this simple use-case is identical to the advanced one. Once you understand these basic principals, you "grock" how to use auth_plug anywhere!

Change into the app directory (cd app) and open the project in your text editor (or IDE).
e.g: atom .

2. Add auth_plug to deps

Open the mix.exs file and locate the defp deps do section. Add the line:

{:auth_plug, "~> 1.4"}

E.g: mix.exs#L45

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
  end

Immediately below this add the following lines of code:

  pipeline :auth, do: plug(AuthPlug)

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

E.g: /lib/app_web/router.ex#L23-L29

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.

4. Add the admin function to the PageController

Open the /lib/app_web/controllers/page_controller.ex file and locate the def index function:

  def index(conn, _params) do
    render(conn, "index.html")
  end

Directly below it, add the following code:

  def admin(conn, _param) do
    render(conn, "admin.html")
  end

E.g: /lib/app_web/controllers/page_controller.ex#L8-L10

This just means when the admin/2 function is invoked, render the admin.html template.
Speaking of which, let's create it!

5. Create the admin.html.eex Template

Create a new file at the following path: /lib/app_web/templates/page/admin.html.eex

And paste the following code into it:

<section class="phx-hero">
  <h1> Welcome <%= @conn.assigns.person.givenName %>!
  <img width="32px" src="<%= @conn.assigns.person.picture %>" />
  </h1>
  <p> You are <strong>signed in</strong>
    with your <strong><%= @conn.assigns.person.auth_provider %> account</strong> <br />.
  </p>
</section>

E.g: /lib/app_web/templates/page/admin.html.eex

6. Get and Set the AUTH_API_KEY Environment Variable

Visit: authdemo.fly.dev and create a New App:

Save the key as an environment variable named AUTH_API_KEY. Remember to export the environment variable or add it to an .env file which should be in your .gitignore file.

Note: If you are new to Environment Variables, please see: https://github.com/dwyl/learn-environment-variables

7. Run the App!

Run your phoenix app on localhost:

mix phx.server

Now open your web browser to: http://localhost:4000/admin

Given that you are not yet authenticated, your request will be redirected to https://authdemo.fly.dev/?referer=http://localhost:4000/admin&auth_client_id=etc

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.

That's it!! 🎉

You just setup auth in a brand new phoenix app using auth_plug!

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