assent

# Assent

[![GitHub CI](https://github.com/pow-auth/assent/workflows/CI/badge.svg)](https://github.com/pow-auth/assent/actions?query=workflow%3ACI)
[![hexdocs.pm](https://img.shields.io/badge/api-docs-green.svg?style=flat)](https://hexdocs.pm/assent)
[![hex.pm](https://img.shields.io/hexpm/v/assent.svg?style=flat)](https://hex.pm/packages/assent)

<!-- MDOC !-->

Multi-provider authentication framework.

## Features

* Includes the following base strategies:
  * OAuth 1.0a - `Assent.Strategy.OAuth`
  * OAuth 2.0 - `Assent.Strategy.OAuth2`
  * OpenID Connect - `Assent.Strategy.OIDC`
* Includes the following provider strategies:
  * Apple Sign In - `Assent.Strategy.Apple`
  * Auth0 - `Assent.Strategy.Auth0`
  * Azure AD - `Assent.Strategy.AzureAD`
  * Basecamp - `Assent.Strategy.Basecamp`
  * Bitbucket - `Assent.Strategy.Bitbucket`
  * DigitalOcean - `Assent.Strategy.DigitalOcean`
  * Discord - `Assent.Strategy.Discord`
  * Facebook - `Assent.Strategy.Facebook`
  * GitHub - `Assent.Strategy.Github`
  * GitLab - `Assent.Strategy.Gitlab`
  * Google - `Assent.Strategy.Google`
  * LINE Login - `Assent.Strategy.LINE`
  * LinkedIn - `Assent.Strategy.Linkedin`
  * Slack - `Assent.Strategy.Slack`
  * Spotify - `Assent.Strategy.Spotify`
  * Strava - `Assent.Strategy.Strava`
  * Stripe Connect - `Assent.Strategy.Stripe`
  * Telegram - `Assent.Strategy.Telegram`
  * Twitch - `Assent.Strategy.Twitch`
  * Twitter - `Assent.Strategy.Twitter`
  * VK - `Assent.Strategy.VK`
  * Zitadel - `Assent.Strategy.Zitadel`

## Usage

A strategy consists of two phases: Request and callback. In the request phase, the user will be redirected to the auth provider for authentication and then returned to initiate the callback phase.

### Single provider

This is an example using the `Assent.Strategy.Github` strategy with `Plug`:

```elixir
defmodule GithubAuth do
  import Plug.Conn

  alias Assent.Strategy.Github

  defp config do
    [
      client_id: Application.fetch_env!(:my_app, :github, :client_id),
      client_secret: Application.fetch_env!(:my_app, :github, :client_secret),
      redirect_uri: "http://localhost:4000/auth/github/callback"
    ]
  end

  # http://localhost:4000/auth/github
  def request(conn) do
    config()
    |> Github.authorize_url()
    |> case do
      {:ok, %{url: url, session_params: session_params}} ->
        # Session params (used for OAuth 2.0 and OIDC strategies) will be
        # retrieved when user returns for the callback phase
        conn = put_session(conn, :session_params, session_params)

        # Redirect end-user to GitHub to authorize access to their account
        conn
        |> put_resp_header("location", url)
        |> send_resp(302, "")

      {:error, _error} ->
        # Something went wrong generating the request authorization URL
        send_resp(conn, 500, "Failed authorization")
    end
  end

  # http://localhost:4000/auth/github/callback
  def callback(conn) do
    # End-user will return to the callback URL with par