Lightning.AuthProviders.Handler (Lightning v2.19.0-pre)

View Source

Module which wraps Oauth configuration and a WellKnown document into a convenient struct that can be used to authenticate users against any OIDC compliant provider.

Summary

Types

opts()
t()

Functions

authorize_url(handler, state, nonce)
from_model(model)

Returns a Handler from a given AuthConfig

get_token(handler, code)
get_userinfo(handler, token)
new(name, opts)

Create a new Provider struct, expects a name and opts

verify_id_token(handler, token, nonce)

Verifies the id_token returned by the token endpoint and returns its claims.

Types

opts()

@type opts() :: [
  client_id: String.t(),
  client_secret: String.t(),
  redirect_uri: String.t(),
  wellknown: Lightning.AuthProviders.WellKnown.t(),
  allow_unverified_email: boolean()
]

t()

@type t() :: %Lightning.AuthProviders.Handler{
  allow_unverified_email: boolean(),
  client: OAuth2.Client.t(),
  name: String.t(),
  wellknown: Lightning.AuthProviders.WellKnown.t()
}

Functions

authorize_url(handler, state, nonce)

@spec authorize_url(
  handler :: t(),
  state :: String.t(),
  nonce :: String.t()
) :: String.t()

from_model(model)

@spec from_model(model :: nil | Lightning.AuthProviders.AuthConfig.t()) ::
  {:ok, t()} | {:error, term()}

Returns a Handler from a given AuthConfig

get_token(handler, code)

@spec get_token(handler :: t(), code :: String.t()) ::
  {:ok, OAuth2.AccessToken.t()} | {:error, map() | atom()}

get_userinfo(handler, token)

@spec get_userinfo(handler :: t(), token :: OAuth2.AccessToken.t()) :: map()

new(name, opts)

@spec new(name :: String.t(), opts :: opts()) :: {:ok, t()} | {:error, term()}

Create a new Provider struct, expects a name and opts:

  • :client_id - The providers issued id
  • :client_secret - Secret for the client
  • :redirect_uri - The URI for redirecting after authentication, usually the callback url in the router.
  • :wellknown - A AuthProviders.WellKnown struct with the providers .well-known/openid-configuration.

verify_id_token(handler, token, nonce)

@spec verify_id_token(
  handler :: t(),
  token :: OAuth2.AccessToken.t(),
  nonce :: String.t() | nil
) :: {:ok, map()} | {:error, term()}

Verifies the id_token returned by the token endpoint and returns its claims.

Checks the JWT signature against the provider's JWKS (asymmetric algs only), then that iss matches the discovered issuer, aud contains our client id, the token is not expired, and nonce matches the value we sent. This is what lets the caller trust the token's identity claims (email, email_verified, sub) rather than an unauthenticated userinfo response.