Home

Awesome

<div align="center">

auth

A complete authentication solution for Phoenix Apps/APIs you can setup in 5 minutes.

<!-- ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/dwyl/auth/Elixir%20CI?label=build&style=flat-square) -->

codecov.io Hex.pm docs contributions welcome HitCount

<!-- uncomment when service is working ... [![Libraries.io dependency status](https://img.shields.io/librariesio/release/hex/auth?logoColor=brightgreen&style=flat-square)](https://libraries.io/hex/auth) [![Inline docs](http://inch-ci.org/github/dwyl/auth.svg?branch=master&style=flat-square)](http://inch-ci.org/github/dwyl/auth) --> </div>

Why?

Letting people authenticate is essential any time there is personalized content/functionality to display.<br /> We needed an easy way of doing Login/Authentication for our projects that we could drop into any project <br /> and be up-and-running in minutes without worrying about complexity or maintenance.

After much research, investigation and development, we created Auth; a re-useable "starter pack" for all our Auth needs. <br />

What's In It For Me?

As a developer, using this App you can rest assured that:

What?

Login for Elixir/Phoenix Apps/APIs which gives you a set of routes and a predictable usage pattern.

What Can People Use to Authenticate?

<!-- this section needs to be re-worded ... or removed! ### _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 (_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". <br /> This acts as a "double-opt-in" and ensures that our app is _able_ to contact the person in the future. <br /> 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. <br /> 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

5 Minute 5 Step Setup

Note the App will not compile/work until you have the required environment variables. <br /> You will see an error similar to: issues/157. See the 3<sup>rd</sup> step below.

If you run mix ecto.setup in step 4 without the required environment variables, even if you set them and try to run the command again, it will error. You will see this error in issues/266. Just delete the created database and run the command again.

1. Clone the project:

git clone git@github.com:dwyl/auth.git && cd auth

2. Install dependencies:

mix deps.get

3. Environment Variables

The Auth App checks for the presence of specific Environment Variables to enable each authentication provider.

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

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

If you want to enable a specific 3rd Party Authentication service, simply ensure that the relevant Environment Variables are defined.

Google Auth

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.

Full instructions to create your Google Auth App: create-google-app-guide.md

GitHub Auth

Similarly, for GitHub Auth, you will need to have these environment variables:

export GITHUB_CLIENT_ID=CreateGitHubApp
export GITHUB_CLIENT_SECRET=SuperSecret

Full instructions to create your GitHub App: create-github-app-guide.md

Full List of Environment Variables

For the full list of environment variables the Auth App expects, see: .env_sample

For completing the setup of the Auth App, you will need to have the ADMIN_EMAIL environment variable defined. <br /> And for sending emails you will need the SECRET_KEY_BASE and EMAIL_APP_URL defined.

4. Create and migrate your database:

Ensure that PostgreSQL is running on your localhost before you run this command.

mix ecto.setup

5. Start Phoenix App

mix phoenix.server

Note: It may take a minute to compile the app the first time. ⏳

Once the Phoenix App is compiled/running, you can visit localhost:4000 from your browser.

6. Check application status

Visit localhost:4000/init to make sure that all the environment variables are properly defined:

image

<br />

Dependencies

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

<br />

Email + Password Registration / Login

This diagram depicts the flow:

<img width="1470" alt="registration-login-email-password-flow-diagram" src="https://user-images.githubusercontent.com/194400/81224631-e8891b80-8fdf-11ea-8e75-e3751d407b38.png">

Edit this diagram

Email

When people register with their email address or authenticate with a 3rd party Authentication provider (e.g: Google), an email is sent to the email address welcoming them. The Auth App uses an external email service for sending emails: https://github.com/dwyl/email

app-services-diagram

Edit this diagram

The Email app provides a simplified interface for sending emails that ensures our main App can focus on it's core functionality.

<br /> <br />

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 "black box" 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, 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.

<br /><br />

Troubleshooting

If you see the following error error when visiting the status (or any other page): http://localhost:4000/status image

You forgot to create and export the SECRET_KEY_BASE environment variable.

Create a secret by running the following command in your terminal:

mix phx.gen.secret

Copy the output and export it, e.g:

export SECRET_KEY_BASE=mAfe8fGd3CgpiwKCnnulAhO2RjcSxuFlw6BGjBhRJCYo2Mthtmu/cdIvO3Mz1QU8

Where the long string is whatever was generated above. Once the SECRET_KEY_BASE environment variable is exported and you restart the app, it should work as expected.

Background Reading

If you are new to Authentication, we recommend checkout out these great resources

wake-sleeping-heroku-app