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.
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.
Login for Elixir/Phoenix Apps/APIs which gives you a set of routes and a predictable usage pattern.
- 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!
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
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.
If you run
mix ecto.setupin 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.
git clone [email protected]:dwyl/auth.git && cd authmix deps.getThe 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.
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
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
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.
Ensure that PostgreSQL is running on your localhost before you run this command.
mix ecto.setupmix 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.
Visit localhost:4000/init to make sure that
all the environment variables are properly defined:
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
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.
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 built-in mechanism for sessions: http://www.phoenixframework.org/docs/sessions
This project uses and extends it to support several 3rd party auth services.
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.
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