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 showcase how simple
it is to integrate auth_plug into any Phoenix Web App/API.
Our goal 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 auth_plug,
try the Fly.io example version
so you know what to expect:
auth-plug.fly.dev
You should see the following homepage:
When you click the
admin link,
you will be redirected to:
https://authdemo.fly.dev/?referer=https://auth-plug.fly.dev/admin

Once you have logged in, you will be redirected back to auth-plug.fly.dev:

Then if you logout, you will see:
That's it. Short and sweet.
Who?
This example is for us @dwyl who are using auth_plug
in all our projects and more specifically for our
App.
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?
These are the steps to recreate the auth_plug_demo App in 2 minutes:
1. Create New Phoenix App
mix phx.new app --no-ecto
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 a 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
grok
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: code .
2. Add auth_plug to deps
Open the mix.exs file
and locate the defp deps do section.
Add the line:
{:auth_plug, "~> 1.5"}
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:
- Create a new pipeline called
:auth
which will execute the AuthPlug
passing in the auth_url as an initialisation option.
- 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!