authable v0.6.2 Authable

Authable worker for OAuth2 provider implementation.

Usage

Please refer to hex docs for each module, function details and samples https://hexdocs.pm/authable.

Authentication

Authable supports 3 main authentication types by default using Plug.Conn. You can add or remove authentication types using configuration. On successful authentication, resource owner automatically set on conn.assigns[:current_user] immutable.

1) Sessions

Reads session for configured sessions keys and passes to the matched authenticator to authenticate.

2) Query Params

Reads query params for configured query_params keys and passes to the matched authenticator to authenticate.

3) Headers

Reads headers for configured headers keys and passes to the matched authenticator to authenticate.

Examples

Configure your application OAuth2 scopes on configuration. Then add import Authable.Plug.Authenticate with scopes into your controller.

  defmodule SomeModule.AppController do
    use SomeModule.Web, :controller
    plug Authable.Plug.Authenticate [scopes: ~w(read write)]

    def index(conn, _params) do
      # access to current user on successful authentication
      current_user = conn.assigns[:current_user]
      ...
    end
  end

  defmodule SomeModule.AppController do
    use SomeModule.Web, :controller
    use Authable.Plug.Authenticate

    plug Authable.Plug.Authenticate [scopes: ~w(read write)] when action in [:create]

    def index(conn, _params) do
      # anybody can call this action
      ...
    end

    def create(conn, _params) do
      # only logged in users can access this action
      current_user = conn.assigns[:current_user]
      ...
    end
  end

  # if you need to allow a resource only unauthorized then
  defmodule SomeModule.AppController do
    use SomeModule.Web, :controller
    plug Authable.Plug.UnauthorizedOnly when action in [:register]

    def register(conn, _params) do
      # only not logged in user can access this action
    end
  end

OAuth2 Authorization

Currently, authable library supports by default authorization code, client credentials, password, and refresh token OAuth2 authorizations. You can add or remove grant types using configuration.

Examples

To authorize a client for resources, all you need to do is calling OAuth2.authorize method with necessary params, on successful authorization Authable.Model.Token struct will return, on failure {:error, errors, http_status_code}.

  # For authorization_code grant type
  Authable.OAuth2.authorize(%{
    "grant_type" => "authorization_code",
    "client_id" => "52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e",
    "client_secret" => "Wi7Y_Q5LU4iIwJArgqXq2Q",
    "redirect_uri" => "http://localhost:4000/oauth2/callbacks",
    "code" => "W_hb8JEDmeYChsNfOGCmbQ",
    "scope" => "read" # optional
  %})

  # For client_credentials grant type
  Authable.OAuth2.authorize(%{
    "grant_type" => "client_credentials",
    "client_id" => "52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e",
    "client_secret" => "Wi7Y_Q5LU4iIwJArgqXq2Q",
    "scope" => "read" # optional
  %})

  # For password grant type
  Authable.OAuth2.authorize(%{
    "grant_type" => "password",
    "email" => "foo@example.com",
    "password" => "12345678",
    "client_id" => "52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e",
    "scope" => "read" # optional
  %})

  # For refresh_token grant type
  Authable.OAuth2.authorize(%{
    "grant_type" => "refresh_token",
    "client_id" => "52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e",
    "client_secret" => "Wi7Y_Q5LU4iIwJArgqXq2Q",
    "refresh_token" => "XJaVz3lCFC9IfifBriA-dw",
    "scope" => "read" # optional
  %})

How a ‘OAuth2 Resource Owner’ can authorize clients?

Authorizing client may mean installing client or giving permission to a client to make OAuth2 Authorization requests and allowing resources with selected scopes. To authorize a client for a resource owner, you need to call OAuth2.authorize_app function.

Examples

  Authable.OAuth2.authorize_app(user, %{
    "client_id" => "52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e",
    "redirect_uri" => "http://localhost:4000/oauth2/callbacks",
    "scope" => "read,write"
  %})

Summary

Functions

Callback implementation for c:Application.start/2

Functions

start(type, args)

Callback implementation for c:Application.start/2.