Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aaronrenner/phx_gen_auth

An authentication system generator for Phoenix 1.5 applications.
https://github.com/aaronrenner/phx_gen_auth

authentication phoenix

Last synced: about 1 month ago
JSON representation

An authentication system generator for Phoenix 1.5 applications.

Awesome Lists containing this project

README 

        
# Phx.Gen.Auth



An authentication system generator for Phoenix 1.5 applications.



**Note: This project is no longer maintained as `mix phx.gen.auth` has been merged into Phoenix v1.6.**



## Overview



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](https://dashbit.co/blog/a-new-authentication-solution-for-phoenix)

* [Original pull request on bare phoenix app][auth pr]

* [Original design spec](https://github.com/dashbitco/mix_phx_gen_auth_demo/blob/auth/README.md)



## Usage



### Generating a Phoenix 1.5 app



`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.



### Installation



After running `mix phx.new`, `cd` into your application's directory (ex. `my_app`).



#### Basic installation



1. Add `phx_gen_auth` to your list of dependencies in `mix.exs`



    ```elixir

    def deps do

      [

        {:phx_gen_auth, "~> 0.7", only: [:dev], runtime: false},

        ...

      ]

    end

    ```

1. Install and compile the dependencies



    ```

    $ mix do deps.get, deps.compile

    ```



#### Umbrella installation



1. `cd` into your project's web app directory (ex. `apps/my_app_web`)



    ```

    $ cd apps/my_app_web

    ```

1. Add `phx_gen_auth` to your list of dependencies in `mix.exs`



    ```elixir

    def deps do

      [

        {:phx_gen_auth, "~> 0.7", only: [:dev], runtime: false},

        ...

      ]

    end

    ```

1. Install and compile the dependencies



    ```

    $ mix do deps.get, deps.compile

    ```



### Running the generator



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][phoenix contexts guide], 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 our phoenix server and try it out.



    $ mix phx.server



#### Note on apps upgraded from Phoenix 1.4



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:



```diff

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

```



### Changing id types



By default, this generator uses the same type of id fields as the rest of the

application. To override this configuration, the generator accepts `--binary-id`

and `--no-binary-id` flags.



    $ mix phx.gen.auth Accounts User users --binary-id



More information about these options are available in the

[documentation](https://hexdocs.pm/phx_gen_auth/Mix.Tasks.Phx.Gen.Auth.html#module-binary-ids).



### Learning more



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](https://hexdocs.pm/phx_gen_auth).



## Upgrading



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](CHANGELOG.md) 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.



## License



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](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.



[phoenix contexts guide]: https://hexdocs.pm/phoenix/contexts.html

[auth pr]: https://github.com/dashbitco/mix_phx_gen_auth_demo/pull/1