Awesome
<div align="center">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 <kbd>Y</kbd> followed by the <kbd>Enter</kbd> key.
This example only needs the bare minimum Phoenix; we don't need any JavaScript or Database. <br /> For more info, see: https://hexdocs.pm/phoenix/Mix.Tasks.Phx.New.html <br /> 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). <br />
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
Explanation
There are two parts to this code:
- Create a new pipeline called
:auth
which will execute theAuthPlug
passing in theauth_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
This just means when the admin/2
function is invoked,
render the admin.html
template. <br />
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>
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!