Addict

Addict allows you to manage users authentication on your Phoenix Framework app easily.

What does it?

For now, it enables your users to register, login, logout and recover/reset their passwords.

On what does it depend?

Addict depends on:

• Phoenix Framework
• Ecto
• Mailgun (Don't have an account? Register for free and get 10000 e-mails per month included)

How can I get it started?

Addict is dependent on an ecto User Model and a Database connection interface.

The user model must have at least the following schema:

  id serial primary key,
  email varchar(200),
  username varchar(200),
  hash varchar(130),
  recovery_hash varchar(130),
  CONSTRAINT u_constraint UNIQUE (email)

There are some application configurations you must add to your configs.ex:

config :addict, not_logged_in_url: "/error",  # the URL where users will be redirected to
                db: MyApp.MyRepo,
                user: MyApp.MyUser,
                register_from_email: "Registration <welcome@yourawesomeapp.com>", # email registered users will receive from address
                register_subject: "Welcome to yourawesomeapp!", # email registered users will receive subject
                password_recover_from_email: "Password Recovery <no-reply@yourawesomeapp.com>",
                password_recover_subject: "You requested a password recovery link",
                email_templates: MyApp.MyEmailTemplates, # email templates for sending e-mails, more on this further down
                mailgun_domain: "yourawesomeapp.com",
                mailgun_key: "apikey-secr3tzapik3y"

The email_templates configuration should point to a module with the following structure:

defmodule MyApp.MyEmailTemplates do
  def register_template(user) do
    """
      <h1>This is the HTML the user will receive upon registering</h1>
      You can access the user attributes: #{user.email}
    """
  end

  def password_recovery_template(user) do
    """
      <h1>This is the HTML the user will receive upon requesting a new password</h1>
      You should provide a link to your app where the token will be processed:
      <a href="http://yourawesomeapp.com/recover_password?token=#{user.recovery_hash}">like this</a>
    """
  end
end

How can I use it?

Just add the following to your router.ex:

    post "/register", Addict.Controller, :register # required params: email, password, username
    post "/logout", Addict.Controller, :logout
    post "/login", Addict.Controller, :login # required params: email, password
    post "/recover_password", Addict.Controller, :recover_password # required params: email
    post "/reset_password", Addict.Controller, :reset_password # required params: token, password, password_confirmation

And use Addict.Plugs.Authenticated plug to validate requests on your controllers:

defmodule MyAwesomeApp.PageController do
  use Phoenix.Controller

  plug Addict.Plugs.Authenticated when action in [:foobar]
  plug :action

  def foobar(conn, _params) do
    render conn, "index.html"
  end

end

If the user is not logged in and requests for the above action, it will be redirected to not_logged_in_url.

TODO

• Validate user model fields
• Implement "Forgot and reset password" flow
• Add example app
• Invite users ability
• ... whatever else it will definitely come up

Contributing

Feel free to send your PR with improvements or corrections!

Special thanks to the folks at #elixir-lang on freenet for being so helpful every damn time!