auth

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

Why?

Letting people authenticate 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 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.

What's In It For Me?

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

• All code for authentication in your app is nicely contained & organized in a single place.
• An order of magnitude less code than any other auth system and all code is well documented, tested & maintained.
• Whenever there is an update in the underlying modules (dependencies) we update and throughly tested in a timely manner.
• All personally identifiable information is securely stored in a logically separate place from your main application so you have extra security.
• You only have to update one thing and your app continues to work as expected.

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?

• Email+Password - 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!

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.
You will see an error similar to: issues/157. See the 3^rd 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 [email protected]: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.
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:

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)
• GitHub OAuth2 Authentication: https://github.com/dwyl/elixir-auth-github
• Google OAuth Authentication: https://github.com/dwyl/elixir-auth-google

Email + Password Registration / Login

This diagram depicts the flow:

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

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.

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.

Troubleshooting

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

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

• Auth Boss: https://github.com/teesloane/Auth-Boss
• Introduction to OAuth2: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2