README.md

oidcc

OpenID Connect client library for Erlang.

OpenID Certified by Jonatan Männchen at the Erlang Ecosystem Foundation of multiple Relaying Party conformance profiles of the OpenID Connect protocol: For details, check the Conformance Test Suite.

The refactoring for v3 and the certification is funded as an Erlang Ecosystem Foundation stipend entered by the Security Working Group.

A security audit was performed by SAFE-Erlang-Elixir more info HERE.

Supported Features

• Discovery ([ISSUER]/.well-known/openid-configuration)
• Client Registration
• Authorization (Code Flow)
  • Request Object
  • PKCE
  • Pushed Authorization Requests
  • Authorization Server Issuer Identification
• Token
  • Authorization: client_secret_basic, client_secret_post, client_secret_jwt, and private_key_jwt
  • Grant Types: authorization_code, refresh_token, jwt_bearer, and client_credentials
  • Automatic JWK Refreshing when needed
• Userinfo
  • JWT Response
  • Aggregated and Distributed Claims
• Token Introspection
• Logout
  • RP-Initiated
• JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)
• Demonstrating Proof of Possession (DPoP)
• OAuth 2 Purpose Request Parameter
• Profiles
  • FAPI 2.0 Security Profile
  • FAPI 2.0 Message Signing

Setup

Please note that the minimum supported Erlang OTP version is OTP26.

Erlang

directly

{ok, Pid} =
    oidcc_provider_configuration_worker:start_link(#{
        issuer => <<"https://accounts.google.com">>,
        name => {local, google_config_provider}
    }).

via supervisor

-behaviour(supervisor).

%% ...

init(_Args) ->
    SupFlags = #{strategy => one_for_one},
    ChildSpecs = [
        #{
            id => oidcc_provider_configuration_worker,
            start =>
                {oidcc_provider_configuration_worker, start_link, [
                    #{
                        issuer => "https://accounts.google.com",
                        name => {local, myapp_oidcc_config_provider}
                    }
                ]},
            shutdown => brutal_kill
        }
    ],
    {ok, {SupFlags, ChildSpecs}}.

Elixir

directly

{:ok, _pid} =
  Oidcc.ProviderConfiguration.Worker.start_link(%{
    issuer: "https://accounts.google.com",
    name: Myapp.OidccConfigProvider
  })

via Supervisor

Supervisor.init(
  [
    {Oidcc.ProviderConfiguration.Worker,
     %{
       issuer: "https://accounts.google.com",
       name: Myapp.OidccConfigProvider
     }}
  ],
  strategy: :one_for_one
)

Usage

Companion libraries

oidcc offers integrations for various libraries:

• oidcc_cowboy - Integrations for cowboy
• oidcc_plug - Integrations for plug and phoenix
• phx_gen_oidcc - Setup Generator for phoenix
• ueberauth_oidcc - Integration for ueberauth

Erlang

%% Create redirect URI for authorization
{ok, RedirectUri} = oidcc:create_redirect_url(
    myapp_oidcc_config_provider,
    <<"client_id">>,
    <<"client_secret">>,
    #{redirect_uri => <<"https://example.com/callback">>}
),

%% Redirect user to `RedirectUri`

%% Retrieve `code` query / form param from redirect back

%% Exchange code for token
{ok, Token} =
    oidcc:retrieve_token(
        AuthCode,
        myapp_oidcc_config_provider,
        <<"client_id">>,
        <<"client_secret">>,
        #{redirect_uri => <<"https://example.com/callback">>}
    ),

%% Load userinfo for token
{ok, Claims} =
    oidcc:retrieve_userinfo(
        Token,
        myapp_oidcc_config_provider,
        <<"client_id">>,
        <<"client_secret">>,
        #{}
    ),

%% Load introspection for access token
{ok, Introspection} =
    oidcc:introspect_token(
        Token,
        myapp_oidcc_config_provider,
        <<"client_id">>,
        <<"client_secret">>,
        #{}
    ),

%% Refresh token when it expires
{ok, RefreshedToken} =
    oidcc:refresh_token(
        Token,
        myapp_oidcc_config_provider,
        <<"client_id">>,
        <<"client_secret">>,
        #{}
    ).

for more details, see https://hexdocs.pm/oidcc/oidcc.html

Elixir

# Create redirect URI for authorization
{:ok, redirect_uri} =
  Oidcc.create_redirect_url(
    Myapp.OidccConfigProvider,
    "client_id",
    "client_secret",
    %{redirect_uri: "https://example.com/callback"}
  )

# Redirect user to `redirect_uri`

# Retrieve `code` query / form param from redirect back

# Exchange code for token
{:ok, token} =
  Oidcc.retrieve_token(
    auth_code,
    Myapp.OidccConfigProvider,
    "client_id",
    "client_secret",
    %{redirect_uri: "https://example.com/callback"}
  )

# Load userinfo for token
{:ok, claims} =
  Oidcc.retrieve_userinfo(
    token,
    Myapp.OidccConfigProvider,
    "client_id",
    "client_secret",
    %{expected_subject: "sub"}
  )

# Load introspection for access token
{:ok, introspection} =
  Oidcc.introspect_token(
    token,
    Myapp.OidccConfigProvider,
    "client_id",
    "client_secret"
  )

# Refresh token when it expires
{:ok, refreshed_token} =
  Oidcc.refresh_token(
    token,
    Myapp.OidccConfigProvider,
    "client_id",
    "client_secret"
  )

for more details, see https://hexdocs.pm/oidcc/Oidcc.html