{"id":15010091,"url":"https://github.com/dwyl/auth","last_synced_at":"2025-05-16T12:07:27.313Z","repository":{"id":30600766,"uuid":"34155961","full_name":"dwyl/auth","owner":"dwyl","description":"🚪 🔐 UX-focussed Turnkey Authentication Solution for Web Apps/APIs (Documented, Tested \u0026 Maintained)","archived":false,"fork":false,"pushed_at":"2025-03-31T13:57:48.000Z","size":1369,"stargazers_count":137,"open_issues_count":52,"forks_count":8,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-02T08:07:44.120Z","etag":null,"topics":["auth","authentication","elixir","email","oauth","oauth2","phoenix","separation-of-concerns"],"latest_commit_sha":null,"homepage":"https://authdemo.fly.dev","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dwyl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-18T06:57:08.000Z","updated_at":"2025-01-24T05:43:41.000Z","dependencies_parsed_at":"2023-01-14T17:17:52.191Z","dependency_job_id":"a0a84059-6e47-475a-b73f-4ac35e6cf671","html_url":"https://github.com/dwyl/auth","commit_stats":{"total_commits":772,"total_committers":9,"mean_commits":85.77777777777777,"dds":"0.12823834196891193","last_synced_commit":"cbeedace69af42acb604137c5b5a5acbac6a58f1"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Fauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Fauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Fauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwyl%2Fauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dwyl","download_url":"https://codeload.github.com/dwyl/auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018032,"owners_count":21034045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth","authentication","elixir","email","oauth","oauth2","phoenix","separation-of-concerns"],"created_at":"2024-09-24T19:30:03.369Z","updated_at":"2025-04-09T10:02:25.080Z","avatar_url":"https://github.com/dwyl.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# `auth`\n\nA ***complete authentication solution*** for **Phoenix** Apps/APIs\nyou can setup in ***5 minutes***.\n\n\u003c!-- ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/dwyl/auth/Elixir%20CI?label=build\u0026style=flat-square) --\u003e\n[![codecov.io](https://img.shields.io/codecov/c/github/dwyl/auth/master.svg?style=flat-square)](http://codecov.io/github/dwyl/auth?branch=master)\n[![Hex.pm](https://img.shields.io/hexpm/v/auth?color=brightgreen\u0026style=flat-square)](https://hex.pm/packages/auth)\n[![docs](https://img.shields.io/badge/docs-maintained-brightgreen?style=flat-square)](https://hexdocs.pm/auth/api-reference.html)\n[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat-square)](https://github.com/dwyl/auth/issues)\n[![HitCount](http://hits.dwyl.com/dwyl/auth.svg)](http://hits.dwyl.com/dwyl/auth)\n\u003c!-- uncomment when service is working ...\n[![Libraries.io dependency status](https://img.shields.io/librariesio/release/hex/auth?logoColor=brightgreen\u0026style=flat-square)](https://libraries.io/hex/auth)\n[![Inline docs](http://inch-ci.org/github/dwyl/auth.svg?branch=master\u0026style=flat-square)](http://inch-ci.org/github/dwyl/auth)\n--\u003e\n\n\u003c/div\u003e\n\n## Why?\n\nLetting people authenticate is *essential* any time\nthere is _personalized_ content/functionality to display.\u003cbr /\u003e\nWe needed an *easy* way of doing Login/Authentication for our projects\nthat we could drop into any project \u003cbr /\u003e\nand be up-and-running in _minutes_\nwithout worrying about complexity or maintenance.\n\nAfter much research, investigation and development,\nwe created **`Auth`**;\na re-useable \"starter pack\"\nfor _all_ our Auth needs. \u003cbr /\u003e\n\n\n\n### What's In It For Me?\n\nAs a developer, _using_ this App you can _rest assured_ that:\n\n+   [x] **All code** for **authentication** in _your_ app\nis **nicely contained \u0026 organized** in a ***single place***.\n+   [x] An order of magnitude less code than any other auth system\nand all code is ***well documented, tested \u0026 maintained***.\n+   [x] Whenever there is an update in the underlying modules (_dependencies_)\nwe **update** and throughly tested in a ***timely manner***.\n+   [x] All ***personally identifiable information*** is securely stored\nin a logically separate place from your main application\nso you have extra security.\n+   [x] You only have to **update _one_ thing**\nand your app continues to work as expected.\n\n## What?\n\nLogin for Elixir/Phoenix Apps/APIs which gives you a set of routes\nand a predictable usage pattern.\n\n### What Can People Use to Authenticate?\n\n+   **Email+Password** - Email and Password (_enabled by default_)\n+   **GitHub** - Allow people to login with their GitHub Account using OAuth2\n+   **Google** - Let people authenticate with the most popular auth system!\n\n\u003c!-- this section needs to be re-worded ... or removed!\n\n### _Tested_\n\n\nOur *objective* is to **_extensively_ test every aspect** of this package\nso that we can *rely* on it for our *high-traffic/security* projects.\n\nIf you spot _any_ area for improvement, please create an issue:\nhttps://github.com/dwyl/auth/issues (_thanks!_)\n\n### Email Verification\n\nEmail is _still_ the _dominant_ way we communicate with people on the web.\n\nOnce the person has authenticated using their preferred method,\nsend them an email to verify their \"account\". \u003cbr /\u003e\nThis acts as a \"double-opt-in\" and ensures that our app is _able_\nto contact the person in the future. \u003cbr /\u003e\ne.g: to reset a password or send an update/notification.\n\n#### Why Email?\n\nWe don't think \"Auth\" _can_ be done without _some_ form of verification. \u003cbr /\u003e\nWe could send SMS or \"Native\" Notifications but both _cost more_ than email.\n\n--\u003e\n\n# How?\n\nAs the description suggests, this module is built for apps built with the\n[**Phoenix**](https://github.com/dwyl/learn-phoenix-framework) web framework.  \nIf you or *anyone* on your team are new to Phoenix, we\nhave an **introductory tutorial**:\n[github.com/dwyl/**learn-phoenix-framework**](https://github.com/dwyl/learn-phoenix-framework)\n\n\n\n\n## 5 Minute 5 Step Setup\n\n\u003e **Note** the App will **_not_ compile/work** \nuntil you have the **required environment variables**. \u003cbr /\u003e\nYou will see an error similar to: \n[**issues/157**](https://github.com/dwyl/auth/issues/157).\nSee the 3\u003csup\u003erd\u003c/sup\u003e step below.\n\n\u003e If you run `mix ecto.setup` in step 4 without the \nrequired environment variables,\neven if you set them and try to run the command again,\nit will error.\nYou will see this error in\n[**issues/266**](https://github.com/dwyl/auth/issues/266).\nJust delete the created database and run the command again.\n\n\n### 1. Clone the project:\n\n```sh\ngit clone git@github.com:dwyl/auth.git \u0026\u0026 cd auth\n```\n\n### 2. Install dependencies:\n\n```sh\nmix deps.get\n```\n\n### 3. Environment Variables\n\nThe Auth App checks for the presence of\n_specific **Environment Variables**_\nto enable each authentication provider.\n\n\u003e If you are totally new to Environment Variables,\nsee: [github.com/dwyl/**learn-environment-variables**](https://github.com/dwyl/learn-environment-variables)\n\nAn authentication provider (_endpoint_) will only work\nif the Environment Variable(s) for that service are present.\n\nIf you want to enable a specific 3rd Party Authentication service,\nsimply ensure that the relevant Environment Variables are defined.\n\n\n#### Google Auth\n\nTo enable Google Auth\nyou will need to have two Environment Variables set:\n```sh\nGOOGLE_CLIENT_ID=YourAppsClientId.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=SuperSecret\n```\nTo *get* these Environment Variables,\nYou will need to create an App on https://console.developers.google.com\nand get your `CLIENT_ID` \u0026 `CLIENT_SECRET`.\n\nFull instructions to create your Google Auth App:\n[create-google-app-guide.md](https://github.com/dwyl/elixir-auth-google/blob/master/create-google-app-guide.md)\n\n\n#### GitHub Auth\n\nSimilarly, for GitHub Auth,\nyou will need to have these environment variables:\n```sh\nexport GITHUB_CLIENT_ID=CreateGitHubApp\nexport GITHUB_CLIENT_SECRET=SuperSecret\n```\n\nFull instructions to create your GitHub App:\n[create-github-app-guide.md](https://github.com/dwyl/elixir-auth-github/blob/master/create-github-app-guide.md)\n\n#### Full List of Environment Variables\n\nFor the _full_ list of environment variables\nthe `Auth` App expects, see:\n[`.env_sample`](https://github.com/dwyl/auth/blob/master/.env_sample)\n\n\nFor completing the setup of the `Auth` App,\nyou will need to have the `ADMIN_EMAIL`\nenvironment variable defined. \u003cbr /\u003e\nAnd for sending emails you will need the\n`SECRET_KEY_BASE` and `EMAIL_APP_URL` defined.\n\n\n### 4. Create and migrate your database:\n\n\u003e Ensure that PostgreSQL is running\n  on your localhost before you\n  run this command.\n\n```sh\nmix ecto.setup\n```\n\n### 5. Start Phoenix App\n\n```sh\nmix phoenix.server\n```\n\n**Note**: It may take a minute to compile the app the first time. ⏳\n\nOnce the Phoenix App is compiled/running,\nyou can visit [`localhost:4000`](http://localhost:4000) from your browser.\n\n\n### 6. Check application status\n\nVisit [`localhost:4000/init`](http://localhost:4000/init) to make sure that\nall the environment variables are properly defined:\n\n![image](https://user-images.githubusercontent.com/194400/152709372-6496b83d-4a8a-4a14-ba5f-f41645fe8c1c.png)\n\n\n\u003cbr /\u003e\n\n### Dependencies\n\nThis project builds on the _fantastic_ work done _many_\npeople in the Elixir/Phoenix community.\n\n\n+   Phoenix default session handling\n(_so your app handles sessions for authenticated users the same way\n  the example apps in all the Phoenix docs_)\n+   GitHub OAuth2 Authentication: \u003chttps://github.com/dwyl/elixir-auth-github\u003e\n+   Google OAuth Authentication: \u003chttps://github.com/dwyl/elixir-auth-google\u003e\n\n\n\u003cbr /\u003e\n\n### Email + Password Registration / Login\n\nThis diagram depicts the flow:\n\n\u003cimg width=\"1470\" alt=\"registration-login-email-password-flow-diagram\" src=\"https://user-images.githubusercontent.com/194400/81224631-e8891b80-8fdf-11ea-8e75-e3751d407b38.png\"\u003e\n\n[Edit this diagram](https://docs.google.com/presentation/d/1PUKzbRQOEgHaOmaEheU7T3AHQhRT8mhGuqVKotEJkM0/edit#slide=id.g7745f61495_0_0)\n\n\n\n### Email\n\nWhen people register with their `email` address\nor authenticate with a 3rd party Authentication provider (e.g: Google),\nan email is sent to the `email` address welcoming them.\nThe `Auth` App uses an external email service\nfor sending emails:\n  \u003chttps://github.com/dwyl/email\u003e\n\n![app-services-diagram](https://user-images.githubusercontent.com/194400/77526292-41628180-6e82-11ea-8044-dacbc57ba895.png)\n\n[Edit this diagram](https://docs.google.com/presentation/d/1PUKzbRQOEgHaOmaEheU7T3AHQhRT8mhGuqVKotEJkM0/edit#slide=id.g71eb641cbd_0_0)\n\nThe Email app provides a simplified interface for sending emails\nthat ensures our main App can focus on it's core functionality.\n\n\u003cbr /\u003e \u003cbr /\u003e\n\n## Frequently Asked/Answered Questions\n\n### Why NOT Use a Service Like Auth0, Cognito, Stormpath, etc?\n\nThere are _several_ \"Authentication-as-a-Service\" providers\nwhich promise to solve all your auth worries with a few clicks.\nThey are _fine_ for people/projects who _don't_ mind\nsending personally identifiable information to a 3rd party service.\nWe care about privacy so we _have_ to know _exactly_ where\nthe login details (_Email Address, Name, etc._) of people _using_\nour apps is _stored_.\n\nIf you prefer to use (_and pay for_)\none of the existing\n[\"black box\"](https://en.wikipedia.org/wiki/Black_box)\nservices\nand \"not have to think about auth\" then go for it!\n\n_This_ repo/project is for people who _do_ want to think about auth,\nwant to _know_ where sensitive data is stored and want to\nbe able to extend the code if they choose to.\n\n### Phoenix Has a Session System, Does this _Use_ It?\n\nPhoenix has a built-in mechanism for sessions:\n  \u003chttp://www.phoenixframework.org/docs/sessions\u003e\n\nThis project _uses_ and _extends_ it to support several 3rd party auth services.\n\n\u003cbr /\u003e\u003cbr /\u003e\n\n### Troubleshooting\n\nIf you see the following error error \nwhen visiting the status (_or any other page_):\nhttp://localhost:4000/status\n![image](https://user-images.githubusercontent.com/194400/152191803-e7127118-7107-40aa-aaa7-a4618726b689.png)\n\nYou forgot to create and export the \n`SECRET_KEY_BASE`\nenvironment variable.\n\nCreate a [secret](https://hexdocs.pm/phoenix/Mix.Tasks.Phx.Gen.Secret.html)\nby running the following command in your terminal:\n\n```sh\nmix phx.gen.secret\n```\n\nCopy the output and export it, e.g:\n\n```sh\nexport SECRET_KEY_BASE=mAfe8fGd3CgpiwKCnnulAhO2RjcSxuFlw6BGjBhRJCYo2Mthtmu/cdIvO3Mz1QU8\n```\n\nWhere the long string \nis whatever was generated above.\nOnce the \n`SECRET_KEY_BASE`\nenvironment variable is exported\nand you restart the app,\nit should work as expected.\n\n\n\n## Background Reading\n\nIf you are new to Authentication, \nwe recommend checkout out these great resources\n\n+   Auth Boss: \u003chttps://github.com/teesloane/Auth-Boss\u003e\n+   Introduction to OAuth2: \u003chttps://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2\u003e\n\n![wake-sleeping-heroku-app](https://dwylauth.herokuapp.com/ping)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwyl%2Fauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdwyl%2Fauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwyl%2Fauth/lists"}