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 3rd step below.
1. Clone the project:
git clone [email protected]:dwyl/auth.git && cd auth2. Install dependencies:
mix deps.get3. 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=SuperSecretTo 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=SuperSecretFull 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.setup5. Start Phoenix App
mix phoenix.serverNote: 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:
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
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.secretCopy the output and export it, e.g:
export SECRET_KEY_BASE=mAfe8fGd3CgpiwKCnnulAhO2RjcSxuFlw6BGjBhRJCYo2Mthtmu/cdIvO3Mz1QU8Where 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