Amur

Simple OAuth for Plug apps. Amur gives you a small OAuth callback flow and provider normalization layer. It is Plug-based and does not require Phoenix.

Installation

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

def deps do
  [
    {:amur, "~> 0.1.1"}
  ]
end

Setup

1. Add the dependency and configure your provider credentials.

config :amur,
  base_url: "http://localhost:4000",
  providers: [
    github: [
      client_id: System.fetch_env!("GITHUB_CLIENT_ID"),
      client_secret: System.fetch_env!("GITHUB_CLIENT_SECRET")
    ]
  ],
  on_success: &MyApp.AuthController.on_success/2,
  on_failure: &MyApp.AuthController.on_failure/2

1. Mount the router in your application router.

defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  scope "/auth", alias: false do
    pipe_through :browser
    forward "/", Amur.Router
  end
end

forward "/", Amur.Router inside a /auth scope mounts the auth endpoints under /auth:

• GET /auth/:provider — starts the OAuth flow.
• GET /auth/:provider/callback — handles the provider callback.
• GET /auth/logout — clears Amur's stored session params.

If you want a different base path, change the scope path. Keep the forward inside a pipeline that runs fetch_session and fetch_flash if your callbacks use session or flash helpers. The alias: false on the scope is required, otherwise Phoenix will rewrite it as YourAppWeb.Amur.Router.

1. Add an Auth Controller to handle the results of the authentication process.

defmodule MyApp.AuthController do
  import Plug.Conn
  import Phoenix.Controller

  def on_success(conn, user) do
    IO.inspect(user, label: "AUTH SUCCESS - #{user.provider}")
    conn
    |> put_flash(:info, "Logged in as #{user.email}")
    |> put_resp_header("location", "/")
    |> send_resp(302, "Redirecting...")
    |> halt()
  end

  def on_failure(conn, reason) do
    IO.inspect(reason, label: "AUTH FAILURE")
    conn
    |> put_flash(:error, "Authentication Error")
    |> put_resp_header("location", "/")
    |> send_resp(302, "Redirecting...")
    |> halt()
  end
end