Elixir |> Phoenix |> Authentication

A Complete Authentication Solution for Phoenix Apps/APIs to get you up and running in the next 5 minutes.

Why?

Letting people login to your App/API is essential any time there is personalized content/functionality to display.

We needed an easy way of doing Login/Authentication for our projects that we could drop into any project and be up-and-running in minutes and avoid "re-inventing the wheel".

After much research and investigation, we decided to use a few existing Elixir modules together to form a re-useable "starter pack".

What's In It For Me?

As a developer, using this module you can rest assured that

all code for authentication in your app is nicely contained & organized in a *single place.
all the auth-related code is well documented, tested & maintained.
when ever there is an update in the underlying modules (dependencies) they will be updated and throughly tested in a timely manner.
All personally identifiable information is stored in a logically separate place from your application so you have added security.
you only have to update one thing and your app continues to work as expected.

What?

Auth "Strategies"

"Basic" - Username/Email and Password (enabled by default)
GitHub - Allow people to login with their GitHub Account using OAuth2
Google - Let people authenticate with the most popular auth system!

Tested

Our objective is to extensively test every aspect of this package so that we can rely on it for our high-traffic/security projects.

If you spot any area for improvement, please create an issue: https://github.com/dwyl/auth/issues so we can discuss. (thanks!)

Email Verification

Email is still the dominant way we communicate with people on the web.

Once the person has authenticated using their preferred method, send them an email to verify their "account". This acts as a "double-opt-in" and ensures that our app is able to contact the person in the future e.g: to reset a password or send an update/notification.

Why Email?

We don't think "Auth" can be done without some form of verification. We could send SMS or "Native" Notifications but both cost more than email.

How?

As the description suggests, this module is built for apps built with the Phoenix web framework.
If you or anyone on your team are new to Phoenix, we have an introductory tutorial: github.com/dwyl/learn-phoenix-framework

One Minute Setup

To start your Phoenix app:

Install dependencies with mix deps.get
Create and migrate your database with mix ecto.create && mix ecto.migrate
(ensure that PostgreSQL is running on your localhost before you run these commands)
Install Node.js dependencies with npm install
Start Phoenix endpoint with mix phoenix.server

Now you can visit localhost:4000 from your browser.

Ready to run in production? Please check our deployment guides.

Environment Variables?

This plugin checks for the presence of specific Environment Variables to enable each authentication provider.

An authentication provider (endpoint) will only work if the Environment Variable(s) for that service are present.

If you are new to Environment Variables, see: https://github.com/dwyl/learn-environment-variables

Email

This repo has two send email examples. One takes a string which becomes the body of the email, the other takes a html template. The two functions are defined in lib/email.ex. They use SES and Bamboo.

For these functions to work you must have defined the following env variables:

SMTP_USERNAME
SMTP_PASSWORD
SES_SERVER
SES_PORT

To understand more about how to set them up and how they work see the full tutorial here: https://github.com/dwyl/learn-phoenix-framework/blob/master/sending-emails.md

To test out the string email go to the endpoint: /email To test out the html template email go to the endpoint: /html-email

Using html gives you the ability to add an image. Inline styling gives you the ability to add colour, centering and padding like in the template in html_email/email.html.eex:

Google Auth

There were 900 Million people using GMail (in 2015, the last available public statistics) and 1.4 billion active Android devices (also 2015 stat) which are certainly higher now, so Google is by far the most popular "account" people have.

Offering people the option of logging into your App(s) using their Google Account makes a lot of sense.

To enable Google Auth you will need to have two Environment Variables set:

GOOGLE_CLIENT_ID=YourAppsClientId.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=SuperSecret

To get these Environment Variables, You will need to create an App on https://console.developers.google.com and get your CLIENT_ID & CLIENT_SECRET. We export these two variables prefixed with GOOGLE_ to distinguish them from other services.

Dependencies

This project builds on the fantastic work done many people in the Elixir/Phoenix community.

Phoenix default session handling (so your app handles sessions for authenticated users the same way the example apps in all the Phoenix docs)
'ueberauth' by @hassox & @scrogson & friends which is "inspired by" omniauth (from Ruby land).

The purpose of this project is to have a more "turnkey" solution rather than having the ingredients for the meal, we want the meal to be ready!

tl;dr

Frequently Asked/Answered Questions

Why NOT Use a Service Like Auth0, Cognito, Stormpath, etc?

There are several "Authentication-as-a-Service" providers which promise to solve all your auth worries with a few clicks. They are fine for people/projects who don't mind sending personally identifiable information to a 3rd party service. We care about privacy so we have to know exactly where the login details (Email Address, Name, etc.) of people using our apps is stored.

If you prefer to use (and pay for) one of the existing services and "not have to think about auth" then go for it!

This repo/project is for people who do want to think about auth, want to know where sensitive data is stored and want to be able to extend the code if they choose to.

Phoenix Has a Session System Already, Does this Use It?

Phoenix has a built-in mechanism for sessions: http://www.phoenixframework.org/docs/sessions

This project uses and extends it to support several 3rd party auth services.

Research

Google Authentication

visit: https://console.developers.google.com to get started

northkevin / auth Goto Github PK

auth's Introduction