Plugoid

OpenID Connect Plug for Phoenix

Plugoid lets you protect some routes with OpenID Connect authentication, for instance:

defmodule PlugoidDemoWeb.Router do
  use PlugoidDemoWeb, :router
  use Plugoid.RedirectURI

  pipeline :oidc_auth do
    plug Plugoid,
      issuer: "https://repentant-brief-fishingcat.gigalixirapp.com",
      client_id: "client1",
      client_config: PlugoidDemo.OpenIDConnect.Client
  end

  scope "/private", PlugoidDemoWeb do
    pipe_through :browser
    pipe_through :oidc_auth

    get "/", PageController, :index
    post "/", PageController, :index
  end
end

Documentation

• Full documentation on hex.pm
• Quick start guide
• plugoid_demo: a demo application using Plugoid

Installation

def deps do
  [
    {:plugoid, "~> 0.6.0"},
    {:hackney, "~> 1.0"}
  ]
end

The hackney dependency is used as the default adapter for Tesla (for outbound HTTP requests). Another one can be used instead (see https://github.com/teamon/tesla#adapters) and then has to be configured in your config.exs:

config :tesla, adapter: Tesla.Adapter.AnotherOne

When to use it

Possible uses are:

• when you entirely delegate user authentication to an external OpenID Connect Provider (OP)
• when you want to integrate with third-party providers ("social login"). Note that:
  • this library and the library it uses are very strict and might fail with some social login providers that don't strictly follows the standard
  • it has not been tested with any public OpenID Connect Provider (social login provider)
  • it does not support pure OAuth2 authentication providers

Project status

The implementation of the standard is comprehsensive but as for all security related libraries, care should be taken when assessing it. This library is not (yet?) widely used and has received little scrutiny by other programmers or security specialists.

This project is also looking for contributors. Feel free to take a look at issues opened in the following projects:

• Plugoid issues
• OIDC issues
• OAuth2TokenManager issues

Protocol support

• OpenID Connect Core 1.0 incorporating errata set 1
  • 3. Authentication
    • authorization code flow:
      • "code" response type
    • implicit flow:
      • "id_token" response type
      • "id_token token" response type
    • hybrid flow:
      • "code id_token" response type
      • "code token" response type
      • "code id_token token" response type
  • 4. Initiating Login from a Third Party
  • 5. Claims
    • 5.3. UserInfo Endpoint (via OAuth2TokenManager)
    • 5.4. Requesting Claims using Scope Values
    • 5.5. Requesting Claims using the "claims" Request Parameter, including special handling of:
      • "acr"
      • "auth_time"
  • 6. Passing Request Parameters as JWTs
  • 9. Client Authentication (via TeslaOAuth2ClientAuth)
    • "client_secret_basic"
    • "client_secret_post"
    • "client_secret_jwt"
    • "private_key_jwt"
    • "none"
  • 12. Using Refresh Tokens (via OAuth2TokenManager)
• OpenID Connect Discovery 1.0 incorporating errata set 1
• OAuth 2.0 Multiple Response Type Encoding Practices
• OAuth 2.0 Form Post Response Mode
• RFC7636 - Proof Key for Code Exchange by OAuth Public Clients
• RFC9207 - OAuth 2.0 Authorization Server Issuer Identification