KeenAuth

TODO: Add description

Installation

If available in Hex, the package can be installed by adding keen_auth to your list of dependencies in mix.exs:

def deps do
  [
    {:keen_auth, "~> 0.1.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/keen_auth.

Required steps

Starting from a new project with ecto

1. Add keen_auth dependency

2. Add configuration to config.exs

    common_auth_processor = DemoWeb.Auth.Processor
    
    config :keen_auth,
      # storage: KeenAuthDemoWeb.Auth.SessionStorage,
      strategies: [
        aad: [
          strategy: Assent.Strategy.AzureAD,
          mapper: KeenAuth.Mappers.AzureAD,
          processor: common_auth_processor,
          config: [
            tenant_id: "REPLACE_WITH_PROPPER_VALUE",
            client_id: "REPLACE_WITH_PROPPER_VALUE",
            client_secret: "REPLACE_WITH_PROPPER_VALUE",
            redirect_uri: "http://localhost:4000/aad/callback"
          ]
        ],
        github: [
          strategy: Assent.Strategy.Github,
          mapper: KeenAuth.Mappers.Github,
          processor: common_auth_processor,
          config: [
            client_id: "REPLACE_WITH_PROPPER_VALUE",
            client_secret: "REPLACE_WITH_PROPPER_VALUE",
            redirect_uri: "https://localhost:4000/auth/github/callback"
          ]
        ],
        facebook: [
          strategy: Assent.Strategy.Facebook,
          mapper: KeenAuth.Mappers.Facebook,
          processor: common_auth_processor,
          config: [
            client_id: "REPLACE_WITH_PROPPER_VALUE",
            client_secret: "REPLACE_WITH_PROPPER_VALUE",
            redirect_uri: "https://localhost:4000/auth/facebook/callback"
          ]
        ]

   then add plug KeenAuth.Plug to endpoint above router

3. Replace cookie session storage with ETS

   1. Make sure to create session ETS table when the application starts

       def start(_, _) do
           children = [
               # ...
           ]
       
           create_session_table()
       
           opts = [strategy: :one_for_one, name: Demo.Supervisor]
         Supervisor.start_link(children, opts)
       end
       
       defp create_session_table() do
         :ets.new(:session, [:named_table, :public, read_concurrency: true])
       end

   2. Reconfigure @session_options in endpoint.ex to ETS

       @session_options [
         store: :ets,
         table: :session,
         key: "_test_key",
         signing_salt: "EdtoEWM7"
       ]

4. Modify router

   1. Add this line to the beginning of router

       require KeenAuth

   2. Add following pipelines

       pipeline :authentication do
         plug :fetch_session
         plug :put_root_layout, {KeenAuthDemoWeb.LayoutView, :root}
       end
       
       pipeline :authorization do
         plug :fetch_session
         plug KeenAuth.Plug.FetchUser
       end

   3. Add /auth subroute

       scope "/auth" do
         pipe_through :authentication
       
         KeenAuth.authentication_routes()
       end

5. Enable HTTPS for development (as required by Facebook)

   1. mix phx.gen.cert

   2. Replace http configuration under Endpoint in config/dev.exs with https

       https: [
         ip: {127, 0, 0, 1},
         port: 4000,
         cipher_suite: :strong,
         keyfile: "priv/cert/selfsigned_key.pem",
         certfile: "priv/cert/selfsigned.pem"
       ],

Optional steps

• Add login buttons

  • Add /sign-in route to router

      get "/sign-in", PageController, :sign_in

  • Add sign_in route to PageController

      defmodule DemoWeb.PageController do
          alias KeenAuth.Config
          
          def sign_in(conn, _params) do
            if KeenAuth.authenticated?(conn) do
              redirect(conn, to: "/")
            else
              render(conn, "sign_in.html")
            end
          end
      end

  • Add sign_in.html.heex template

      <style>
          .sign-in-options {
                  display: flex;
                  justify-content: center;
                  align-items: center;
          }
      
          .sign-in-options .option {
                  flex: 1;
          }
      </style>
      
      <section class="row">
          <article class="column">
              <h2>Sign in options:</h2>
      
              <div class="sign-in-options">
                  <div class="option">
                      <a href={Routes.authentication_path(@conn, :new, :aad, redirect_to: "/")}>
                          Azure
                      </a>
                  </div>
                  <div class="option">
                      <a href={Routes.authentication_path(@conn, :new, :github, redirect_to: "/")}>
                          Github
                      </a>
                  </div>
                  <div class="option">
                      <a href={Routes.authentication_path(@conn, :new, :facebook, redirect_to: "/")}>
                          Facebook
                      </a>
                  </div>
              </div>
          </article>
      </section>

    1. Create processor module (DemoWeb.Auth.Processor) implementing KeenAuth.Processor behavior

        defmodule TestWeb.Auth.Processor do
          @behaviour KeenAuth.Processor
        
          import Plug.Conn, only: [put_session: 3]
        
          require Logger
        
          @impl true
          def process(conn, provider, response) do
            Logger.debug("Processing OAuth response for #{provider}", response: inspect(response))
        
            {:ok, put_session(conn, :oauth_response, response), response}
          end
        end