13 KiB
Getting Started Ash Authentication Phoenix
In this 10 minute tutorial we create a new empty Example
Phoenix application which provides the functionality to register users with their email address and a password. Registered users can sign in and out.
We assumes that you have Elixir version 1.14.x (check with elixir -v
) and Phoenix 1.7 (check with mix phx.new --version
) installed. We also assume that you have a PostgreSQL database running which we use to persist the user data.
Green Field
We start with a new Phoenix application and use the --no-ecto
flag to skip the Ecto setup.
$ mix phx.new example --no-ecto
$ cd example
Application Dependencies
We need to add the following dependencies:
** mix.exs
**
defmodule Example.MixProject do
use Mix.Project
# ...
defp deps do
[
# ...
# add these lines -->
{:ash, "~> 2.5.11"},
{:ash_authentication, "~> 3.7.3"},
{:ash_authentication_phoenix, "~> 1.4.7"},
{:ash_postgres, "~> 1.3.2"}
# <-- add these lines
]
end
# ...
Let's fetch everything:
$ mix deps.get
Formatter
We can make our life easier and the code more consistent by adding formatters to the project. We will use Elixir's built-in formatter for this.
** .formatter.exs
**
[
import_deps: [
:phoenix,
# add these lines -->
:ash,
:ash_authentication_phoenix,
:ash_postgres
# <-- add these lines
],
plugins: [Phoenix.LiveView.HTMLFormatter],
inputs: ["*.{heex,ex,exs}", "{config,lib,test}/**/*.{heex,ex,exs}"]
]
Phoenix 1.7 compatibility
For Phoenix 1.7 we need to change helpers: false
to helpers: true
in the router section:
** lib/example_web.ex
**
defmodule ExampleWeb do
# ...
def router do
quote do
use Phoenix.Router, helpers: true # <-- Change this line
# ...
Create and configure the Repo
We use AshPostgres to handle the database tables for our application. We need to create a new Repo
module for that:
** lib/example/repo.ex
**
defmodule Example.Repo do
use AshPostgres.Repo, otp_app: :example
def installed_extensions do
["uuid-ossp", "citext"]
end
end
We have to configure the Repo in config/config.exs
. While doing that we also configure other stuff which we need later.
** config/config.exs
**
# ...
import Config
# add these lines -->
config :example,
ash_apis: [Example.Accounts]
config :example,
ecto_repos: [Example.Repo]
config :ash,
:use_all_identities_in_manage_relationship?, false
# <-- add these lines
# ...
We need to add the Repo
to the supervision tree in lib/example/application.ex
:
** lib/example/application.ex **
defmodule Example.Application do
# ...
@impl true
def start(_type, _args) do
children = [
# ...
# add these lines -->
Example.Repo,
{AshAuthentication.Supervisor, otp_app: :example}
# <-- add these lines
]
# ...
Database Configuration
In case you have other usernames
and passwords
for your database you need to change the following values. We use the default postgres
user and password.
** config/dev.exs
**
import Config
# add these lines -->
config :example, Example.Repo,
username: "postgres",
password: "postgres",
hostname: "localhost",
database: "example_dev",
port: 5432,
show_sensitive_data_on_connection_error: true,
pool_size: 10
# <-- add these lines
# ...
** config/test.exs
**
import Config
# add these lines -->
config :example, Example.Repo,
username: "postgres",
password: "postgres",
hostname: "localhost",
database: "example_test#{System.get_env("MIX_TEST_PARTITION")}",
pool: Ecto.Adapters.SQL.Sandbox,
pool_size: 10
# <-- add these lines
** config/runtime.exs
**
import Config
# ...
if config_env() == :prod do
# add these lines -->
database_url =
System.get_env("DATABASE_URL") ||
raise """
environment variable DATABASE_URL is missing.
For example: ecto://USER:PASS@HOST/DATABASE
"""
config :example, Example.Repo,
url: database_url,
pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
# <-- add these lines
# ...
Create an Accounts API
We need to create an Accounts
API in our application to provide a User
and a Token
resource. For that we create a couple of new files and one new directory. At the end we should have the following directory structure:
lib/example
├── accounts
│ ├── registry.ex
│ ├── token.ex
│ └── user.ex
├── accounts.ex
...
** lib/example/accounts.ex
**
defmodule Example.Accounts do
use Ash.Api
resources do
registry Example.Accounts.Registry
end
end
** lib/example/accounts/user.ex
**
defmodule Example.Accounts.User do
use Ash.Resource,
data_layer: AshPostgres.DataLayer,
extensions: [AshAuthentication]
attributes do
uuid_primary_key :id
attribute :email, :ci_string, allow_nil?: false
attribute :hashed_password, :string, allow_nil?: false, sensitive?: true
end
authentication do
api Example.Accounts
strategies do
password :password do
identity_field(:email)
end
end
tokens do
enabled?(true)
token_resource(Example.Accounts.Token)
signing_secret(Application.get_env(:example, ExampleWeb.Endpoint)[:secret_key_base])
end
end
postgres do
table "users"
repo Example.Repo
end
identities do
identity :unique_email, [:email]
end
end
** lib/example/accounts/token.ex
**
defmodule Example.Accounts.Token do
use Ash.Resource,
data_layer: AshPostgres.DataLayer,
extensions: [AshAuthentication.TokenResource]
token do
api Example.Accounts
end
postgres do
table "tokens"
repo Example.Repo
end
end
Next, let's define our registry:
** lib/example/accounts/registry.ex
**
defmodule Example.Accounts.Registry do
use Ash.Registry, extensions: [Ash.Registry.ResourceValidations]
entries do
entry Example.Accounts.User
entry Example.Accounts.Token
end
end
Migration and Create
Now is a good time to create the database and run the migrations:
$ mix ash_postgres.create
$ mix ash_postgres.generate_migrations --name add_user_and_token
$ mix ash_postgres.migrate
In case you want to drop the database and start over again during development you can use
mix ash_postgres.drop
followed bymix ash_postgres.create
andmix ash_postgres.migrate
.
AshAuthentication.Phoenix.Router
ash_authentication_phoenix
includes several helper macros which can generate
Phoenix routes for you. For that you need to add 6 lines in the router module:
** lib/example_web/router.ex
**
defmodule ExampleWeb.Router do
use ExampleWeb, :router
use AshAuthentication.Phoenix.Router # <--- Add this line
pipeline :browser do
plug :accepts, ["html"]
plug :fetch_session
plug :fetch_live_flash
plug :put_root_layout, {ExampleWeb.Layouts, :root}
plug :protect_from_forgery
plug :put_secure_browser_headers
plug :load_from_session # <--- Add this line
end
pipeline :api do
plug :accepts, ["json"]
plug :load_from_bearer # <--- Add this line
end
scope "/", ExampleWeb do
pipe_through :browser
# add these lines -->
sign_in_route()
sign_out_route AuthController
auth_routes_for Example.Accounts.User, to: AuthController
# <-- add these lines
get "/", PageController, :home
end
# ...
Generated routes
Given the above configuration you should see the following in your routes:
# mix phx.routes
Generated example app
auth_path GET /sign-in AshAuthentication.Phoenix.SignInLive :sign_in
auth_path GET /sign-out ExampleWeb.AuthController :sign_out
auth_path * /auth/user/password/register ExampleWeb.AuthController {:user, :password, :register}
auth_path * /auth/user/password/sign_in ExampleWeb.AuthController {:user, :password, :sign_in}
page_path GET / ExampleWeb.PageController :home
...
AshAuthentication.Phoenix.Controller
While running mix phx.routes
you probably saw the warning message that the ExampleWeb.AuthController.init/1 is undefined
. Let's fix that by creating a new controller:
** lib/my_app_web/controllers/auth_controller.ex
**
defmodule ExampleWeb.AuthController do
use ExampleWeb, :controller
use AshAuthentication.Phoenix.Controller
def success(conn, _activity, user, _token) do
return_to = get_session(conn, :return_to) || ~p"/"
conn
|> delete_session(:return_to)
|> store_in_session(user)
|> assign(:current_user, user)
|> redirect(to: return_to)
end
def failure(conn, _activity, _reason) do
conn
|> put_status(401)
|> render("failure.html")
end
def sign_out(conn, _params) do
return_to = get_session(conn, :return_to) || ~p"/"
conn
|> clear_session()
|> redirect(to: return_to)
end
end
** lib/example_web/controller/auth_html.ex
**
defmodule ExampleWeb.AuthHTML do
use ExampleWeb, :html
embed_templates "auth_html/*"
end
** lib/example_web/controllers/auth_html/failure.html.heex
**
<h1 class="text-2xl">Authentication Error</h1>
Tailwind
If you plan on using our default Tailwind-based
components without overriding them you will need to modify your
assets/tailwind.config.js
to include the ash_authentication_phoenix
dependency:
** assets/tailwind.config.js
**
// See the Tailwind configuration guide for advanced usage
// https://tailwindcss.com/docs/configuration
const plugin = require("tailwindcss/plugin")
module.exports = {
content: [
"./js/**/*.js",
"../lib/*_web.ex",
"../lib/*_web/**/*.*ex",
"../deps/ash_authentication_phoenix/**/*.ex" // <-- Add this line
],
// ...
Minimal Example
To see how the authentication works we replace the default Phoenix home.html.eex
with a minimal example which has a top navbar. On the right side it shows the @current_user
and a sign out button. If you are not signed in you will see a sign in button.
** lib/example_web/controllers/page_html/home.html.heex
**
<nav class="bg-gray-800">
<div class="px-2 mx-auto max-w-7xl sm:px-6 lg:px-8">
<div class="relative flex items-center justify-between h-16">
<div class="flex items-center justify-center flex-1 sm:items-stretch sm:justify-start">
<div class="block ml-6">
<div class="flex space-x-4">
<div class="px-3 py-2 text-xl font-medium text-white ">
Ash Demo
</div>
</div>
</div>
</div>
<div class="absolute inset-y-0 right-0 flex items-center pr-2 sm:static sm:inset-auto sm:ml-6 sm:pr-0">
<%= if @current_user do %>
<span class="px-3 py-2 text-sm font-medium text-white rounded-md">
<%= @current_user.email %>
</span>
<a
href="/sign-out"
class="rounded-lg bg-zinc-100 px-2 py-1 text-[0.8125rem] font-semibold leading-6 text-zinc-900 hover:bg-zinc-200/80 active:text-zinc-900/70"
>
Sign out
</a>
<% else %>
<a
href="/sign-in"
class="rounded-lg bg-zinc-100 px-2 py-1 text-[0.8125rem] font-semibold leading-6 text-zinc-900 hover:bg-zinc-200/80 active:text-zinc-900/70"
>
Sign In
</a>
<% end %>
</div>
</div>
</div>
</nav>
<div class="py-10">
<header>
<div class="px-4 mx-auto max-w-7xl sm:px-6 lg:px-8">
<h1 class="text-3xl font-bold leading-tight tracking-tight text-gray-900">Demo</h1>
</div>
</header>
<main>
<div class="mx-auto max-w-7xl sm:px-6 lg:px-8">
<div class="px-4 py-8 sm:px-0">
<div class="border-4 border-gray-200 border-dashed rounded-lg h-96"></div>
</div>
</div>
</main>
</div>
Start Phoenix
You can now start Phoenix and visit
localhost:4000
from your browser.
$ mix phx.server
Sign In
Visit localhost:4000/sign-in
from your browser.
The sign in page shows a link to register a new account.
Sign Out
Visit localhost:4000/sign-out
from your browser.