Pow
Pow is a powerful, modular, and extendable authentication and user management solution for Phoenix and Plug based apps.
Features
- User registration
- Session based authorization
- Per Endpoint/Plug configuration
- Extendable
- I18n
Installation
Add Pow to your list of dependencies in mix.exs
:
def deps do
[
# ...
{:pow, "~> 0.1"}
# ...
]
end
Run mix deps.get
to install it.
Getting started
Install the necessary files:
mix pow.install
This will add the following files to your app:
LIB_PATH/pow.ex
LIB_PATH/users/user.ex
PRIV_PATH/repo/migrations/TIMESTAMP_create_user.ex
Add user and repo to pow.ex
:
defmodule MyApp.Pow do
use Pow,
user: MyApp.Users.User,
repo: MyApp.Repo
end
Set up endpoint.ex
to enable session based authentication:
defmodule MyAppWeb.Endpoint do
use Phoenix.Endpoint, otp_app: :my_app
# ...
plug Plug.Session,
store: :cookie,
key: "_my_project_demo_key",
signing_salt: "secret"
plug MyApp.Pow.Plug.Session
# ...
end
Add Pow routes to router.ex
:
defmodule MyAppWeb.Router do
use MyAppWeb, :router
use MyApp.Pow.Phoenix.Router
# ...
pipeline :protected do
plug Pow.Plug.RequireAuthenticated
end
scope "/" do
pipe_through :browser
pow_routes()
end
# ...
scope "/", MyAppWeb do
pipe_through [:browser, :protected]
# Protected routes ...
end
end
That’s it! Run mix ecto.setup
, and you can now visit http://localhost:4000/registrations/new
, and create a new user.
By default, Pow will only expose files that are absolutely necessary, but you can expose other files such as views and templates using the mix pow.phoenix.install
command.
Extensions
Pow is made so it’s easy to extend the functionality with your own complimentary library. The following extensions are included in this library:
PowResetPassword
PowEmailConfirmation
Many extensions requires a mailer to have been set up. Let’s create the mailer in lib/my_app_web/mailer.ex
using swoosh:
defmodule MyAppWeb.Mailer do
use Pow.Phoenix.Mailer
use Swoosh.Mailer, otp_app: :my_app_web
import Swoosh.Email
def cast(%{user: user, subject: subject, text: text, html: html}) do
new()
|> to({"", user.email})
|> from({"My App", "myapp@example.com"})
|> subject(subject)
|> html_body(html)
|> text_body(text)
end
def process(email) do
deliver(email)
end
end
Update lib/my_app/pow.ex
with the :backend_mailer
key, and any extensions you wish to enable:
defmodule MyApp.Pow do
use Pow,
user: MyApp.Users.User,
repo: MyApp.Repo,
backend_mailer: MyAppWeb.Mailer,
extensions: [PowResetPassword, PowEmailConfirmation]
end
To install any migration files for extensions, run the following:
mix pow.extension.ecto.gen.migrations --extension PowResetPassword
That’s it!
Configuration
Pow is build to be modular, and easy to configure. Configuration is primarily passed through method calls, and plug options and they will take priority over any environment configuration. This is ideal in case you’ve an umbrella app with multiple separate user domains.
Module groups
Pow has three main groups of modules that each can used individually, or in conjunction with each other:
Pow.Plug
This group will handle the plug connection. The configuration will be assigned to conn.private[:pow_config]
and passed through the controller to the users context module.
Pow.Ecto
This group contains all modules related to the Ecto based user schema and context. By default, Pow will use the Pow.Ecto.Context
module for authenticating, creating, updating and deleting users. However, it’s very simple to extend, or write your own user context. You can do this by setting the :users_context
configuration key.
Pow.Phoenix
This contains the controllers, views and templates for Phoenix. Templates are not generated by default, instead compiled default templates will be used. You can choose to generate these by running mix pow.phoenix.install --templates
.
Pow.Extension
This module helps build extensions for Pow. There’s two extension mix tasks to generate ecto migrations and phoenix templates.
mix pow.extension.ecto.gen.migrations
mix pow.extension.phoenix.gen.templates
Authorization plug
Pow ships with a session plug module. You can easily switch it out with a different one. As an example, here’s how you do that with Guardian:
defmodule MyAppWeb.Pow.Plug do
use Pow.Plug.Base
def fetch(conn, config) do
MyApp.Guardian.Plug.current_resource(conn)
end
def create(conn, user, config) do
MyApp.Guardian.Plug.sign_in(conn, user)
end
def delete(conn, config) do
MyApp.Guardian.Plug.sign_out(conn)
end
end
defmodule MyAppWeb.Endpoint do
# ...
plug MyAppWeb.Pow.Plug,
repo: MyApp.Repo,
user: MyApp.Users.User
end
Changeset
The user module has a fallback changeset/2
method. If you need to add custom validations, you can use the pow_changeset/2
method like this:
defmodule MyApp.Users.User do
use Ecto.Schema
use Pow.Ecto.Schema
schema "users" do
field :custom, :string
pow_user_fields()
timestamps()
end
def changeset(user_or_changeset, attrs) do
user
|> pow_changeset(attrs)
|> Ecto.Changeset.cast(attrs, [:custom])
|> Ecto.Changeset.validate_required([:custom])
end
end
Plugs
Pow.Plug.Session
Enables session based authorization. The user struct will be collected from an ETS table through a GenServer using a unique token generated for the session. The token will be reset every time the authorization level changes.
Pow.Plug.RequireAuthenticated
By default, this will redirect the user to the log in page if the user hasn’t been authenticated.
Pow.Plug.RequireNotAuthenticated
By default, this will redirect the user to the front page if the user is already authenticated.
Migrating from Coherence
If you’ve previously used Coherence, the migration is simple. You’ll have to remove all coherence files such as templates, views, and mailers, and remove all file modifications such as config.exs
, user.ex
, etc. After this, you can just follow the steps in Getting started, and then customize your configuration. Pow use your existing User
module.
LICENSE
(The MIT License)
Copyright (c) 2018 Dan Schultzer & the Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.