# Sentry
"Sentry provides a set of helpers and conventions that will guide you in leveraging Elixir modules to build a simple, robust authorization system." - Inspired by [elabs/pundit](https://github.com/elabs/pundit)
## TODOs
- Generators
- JWT
## Installation
Add sentry to your list of dependencies in `mix.exs`:
```elixir
def deps do
[{:sentry, "~> 0.2"}]
end
```
Ensure sentry is started before your application:
```elixir
def application do
[applications: [:sentry]]
end
```
Ensure your `User` model and `users` table has the following fields:
- `:encrypted_password` field
- a user identification field. Defaults to `email`
- and a virtual password field. Defaults to `password`
```elixir
# web/models/user.ex
defmodule MyApp.User do
use MyApp.Web, :model
schema "users" do
field :email, :string
field :encrypted_password, :string
field :password, :string, virtual: true
field :password_confirmation, :string, virtual: true
...
timestamps
end
end
```
Configure Ueberauth and Sentry in `config/config.exs`
```elixir
# config/config.exs
# Ueberauth
config :ueberauth, Ueberauth,
providers: [
identity: {Ueberauth.Strategy.Identity, [
callback_methods: ["POST"]
]}
]
# Sentry
config :sentry, Sentry,
repo: MyApp.Repo,
model: MyApp.User # you may use a different model as you like
# uid_field: :some_id_field \\ defaults to :email
# password_field: :some_pw_field \\ defaults to :password
```
## Authentication
Sentry leverages [ueberauth](https://github.com/ueberauth/ueberauth) for the authentication layer with an addition of bcrypt encryption when storing and authenticating user.
Sentry provides useful helpers for working with users on your system
- `Sentry.Authenticator.attempt/1`
- `Sentry.Authenticator.logout/1`
- `Sentry.Authenticator.encrypt_password/1`
- `Sentry.Authenticator.logged_in?/1`
- `Sentry.Authenticator.current_user/1`
here's an example use case
```elixir
# web/controllers/auth_controller.ex
defmodule MyApp.AuthController do
use MyApp.Web, :controller
use Sentry, :authenticator
alias MyApp.User
def request(conn, %{"provider" => "identity"} = _params) do
render(conn, callback_url: callback_url(conn),
changeset: User.changeset(%User{}))
end
def request(conn, _params) do
conn
|> put_status(:not_found)
|> render(MyApp.ErrorView, "404.html")
end
def callback(%{ assigns: %{ ueberauth_failure: fails } } = conn, _) do
conn
|> put_flash(:error, "Failed to authenticate.")
|> redirect(to: "/")
end
def callback(conn, %{"provider" => "identity"}) do
# attempts to authorize user
# once authorized you can then access the user info with
# `Sentry.Authenticator.current_user/1`
# or check if logged in with `Sentry.Authenticator.logged_in?/1`
case attempt(conn) do
{:ok, conn} ->
conn
|> put_flash(:info, "You've successfully logged in")
|> redirect(to: "/")
{:error, reason} ->
conn
|> put_flash(:error, reason)
|> redirect(to: request_path(conn))
end
end
def delete(conn, _params) do
conn
|> put_flash(:info, "You've been logged out!")
|> logout()
|> redirect(to: "/")
end
end
```
```elixir
# web/router.ex
defmodule MyApp.Router do
...
pipeline :auth do
plug Ueberauth
end
scope "/auth", MyApp do
pipe_through [:browser, :auth]
get "/logout", AuthController, :delete
get "/:provider", AuthController, :request
get "/:provider/callback", AuthController, :callback
post "/:provider/callback", AuthController, :callback
end
end
```
```elixir
# web/view/layout_view.ex
defmodule MyApp.LayoutView do
use MyApp.Web, :view
# this adds the logged_in?/1 and current_user/1 helper to the view
use Sentry, :view
end
```
```elixir
# web/templates/auth/request.html.eex
<%= form_for @changeset, @callback_url, fn f -> %>
<%= if f.errors != [] do %>
<div class="alert alert-danger">
<p>Oops, something went wrong! Please check the errors below:</p>
<ul>
<%= for {attr, message} <- f.errors do %>
<li><%= humanize(attr) %> <%= message %></li>
<% end %>
</ul>
</div>
<% end %>
<div class="form-group">
<label>Email</label>
<%= text_input f, :email, class: "form-control" %>
</div>
<div class="form-group">
<label>Password</label>
<%= password_input f, :password, class: "form-control" %>
</div>
<div class="form-group">
<%= submit "Login", class: "btn btn-primary" %>
</div>
<% end %>
```
## Authorization
For authorization, we have the following functions for dealing with it
- `Sentry.Authorizer.authorize/2`
- `Sentry.Authorizer.authorize_changeset/3`
- `Sentry.Authorizer.authorize!/2`
- `Sentry.Authorizer.authorize_changeset!/3`
The bang functions follows Elixir's [convention](http://elixir-lang.org/getting-started/try-catch-and-rescue.html#errors) of throwing exceptions and returning values instead of returning tuples like {:ok, result} or {:error, reason}
```elixir
# web/controllers/auth_controller.ex
defmodule MyApp.AuthController do
use MyApp.Web, :controller
use Sentry, :authenticator
alias MyApp.User
def request(conn, %{"provider" => "identity"} = _params) do
# you may pass an optional second parameter as
# a data that is then accessable on the `AuthPolicy.request/2` action
case authorize(conn) do
{:ok, conn} ->
render(conn, callback_url: callback_url(conn),
changeset: User.changeset(%User{}))
{:error, reason} ->
conn
|> put_flash(:error, reason)
|> redirect(to: "/")
end
end
def request(conn, _params) do
conn
|> put_status(:not_found)
|> render(MyApp.ErrorView, "404.html")
end
def callback(%{ assigns: %{ ueberauth_failure: fails } } = conn, _) do
conn
|> put_flash(:error, "Failed to authenticate.")
|> redirect(to: "/")
end
def callback(conn, %{"provider" => "identity"}) do
# attempts to authorize user
# once authorized you can then access the user info with
# `Sentry.Authenticator.current_user/1`
# or check if logged in with `Sentry.Authenticator.logged_in?/1`
case attempt(conn) do
{:ok, conn} ->
conn
|> put_flash(:info, "You've successfully logged in")
|> redirect(to: "/")
{:error, reason} ->
conn
|> put_flash(:error, reason)
|> redirect(to: request_path(conn))
end
end
def delete(conn, _params) do
conn
|> put_flash(:info, "You've been logged out!")
|> logout()
|> redirect(to: "/")
end
end
```
or you can use it as a plug function or even cleaner module
```elixir
defmod MyApp.AuthController do
...
plug :authorize_action when action in [:request]
def request(conn, _params) do
...
end
def authorize_action (conn, _options) do
case authorize(conn) do
{:ok, conn} ->
conn
{:error, reason} ->
conn
|> put_flash(:error, reason)
|> redirect(to: "/")
end
end
end
```
```elixir
# web/policies/auth_policy.ex
defmodule MyApp.AuthPolicy do
use Sentry, :authenticator
def request(conn, options) do
# `logged_in?/1` is a helper function from
# `Sentry.Authenticator` that checks if a user is logged in
if logged_in?(conn) do
{:ok, conn}
else
{:error, "You're already logged in"}
end
end
end
```
### Authorizing resource/changeset
If you are working on resource/changeset, you might want to use the `Sentry.Authorizer.authorize_changeset/2` function as it will use a policy based on the model name
you can also use `authorize_changeset/2` with plugs.
```elixir
# web/controllers/user_controller.ex
defmodule PostController do
use Sentry, :authorizer
alias MyApp.Post
def update(conn, %{"id" => id, "post" => post_params}) do
changeset = Post.changeset(post, post_params)
# you can pass an optional third argument as an
# atom to override the function
# to be executed on the policy for example:
# authorize_changeset(conn, changeset, :belongs_to_current_user)
# this will instead run the
# `PostPolicy.belongs_to_current_user/2` action
authorize_changeset(conn, changeset)
end
end
```
```elixir
# web/policies/post_policy.ex
defmodule PostPolicy do
use Sentry, :authenticator
def update(conn, changeset) do
...
end
def belongs_to_current_user(conn,
%Ecto.Changeset{params: %{user_id: user_id}}) do
if current_user(conn).id === user_id do
{:ok, conn}
else
{:error, "You're not authorized to edit this post}
end
end
end
```
## License
Sentry is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)
