An authentication system generator for Phoenix 1.5+ applications.
The purpose of phx.gen.auth
is to generate a pre-built authentication system into
a Phoenix 1.5+ application that follows both security and elixir best practices. By generating
code into the user's application instead of using a library, the user has complete freedom
to modify the authentication system so it works best with their app. The following links
have more information regarding the motivation and design of the code this generates.
- José Valim's blog post - An upcoming authentication solution for Phoenix
- Original pull request on bare phoenix app
- Original design spec
phx.gen.auth
must be installed into a Phoenix 1.5+ application.
Once the installer is installed, a new project can be generated by running
$ mix phx.new my_app
Please note, the --no-ecto
and --no-html
options are not supported.
After running mix phx.new
, cd
into your application's directory (ex. my_app
).
-
Add
phx_gen_auth
to your list of dependencies inmix.exs
def deps do [ {:phx_gen_auth, "~> 0.4.0", only: [:dev], runtime: false}, ... ] end
-
Install and compile the dependencies
$ mix do deps.get, deps.compile
-
cd
into your project's web app directory (ex.apps/my_app_web
)$ cd apps/my_app_web
-
Add
phx_gen_auth
to your list of dependencies inmix.exs
def deps do [ {:phx_gen_auth, "~> 0.4.0", only: [:dev], runtime: false}, ... ] end
-
Install and compile the dependencies
$ mix do deps.get, deps.compile
From the root of your phoenix app (or apps/my_app_web
in an umbrella app), you
can install the authentication system with the following command
$ mix phx.gen.auth Accounts User users
This creates the templates,views, and controllers on the web namespace,
and a new MyApp.Accounts
context, in the application
namespace.
Verify the database connection details for the development and test environments in config/
so the migrator and tests can run properly. Then run the following to create the database
$ mix ecto.create
Next, let's install the dependencies and migrate the database
$ mix deps.get
$ mix ecto.migrate
Let's run the tests and make sure our new authentication system works as expected.
$ mix test
Finally, let's start the our phoenix server and try it out.
$ mix phx.server
If you've upgraded your app from Phoenix 1.4, you'll need to make the following update to test/support/conn_case.ex
to get mix test
to pass:
using do
quote do
# Import conveniences for testing with connections
import Plug.Conn
import Phoenix.ConnTest
+ import DemoWeb.ConnCase
alias DemoWeb.Router.Helpers, as: Routes
# The default endpoint for testing
@endpoint DemoWeb.Endpoint
end
end
To learn more about phx.gen.auth
, run the following command.
$ mix help phx.gen.auth
You can also look up the mix task in hexdocs.
Since mix phx.gen.auth
generates its code directly into your application, upgrading the version
of this library will not upgrade your application's current authentication logic.
To see the changes that have been made to the generator output since the version that was used in
your application, visit the CHANGELOG and click the [Diff]
links for each
version. These diffs will show you the changes to make to your application so it can be up to date
with the current generator output.
Copyright 2020 Dashbit, Aaron Renner
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.