vestibule_oidc

OpenID Connect Discovery support for auto-configuring strategies.

This module implements OIDC Discovery 1.0 to automatically fetch provider configuration from a well-known endpoint and build a Strategy from the discovered endpoints.

Usage

// Auto-discover and create a strategy in one step:
import vestibule_oidc
let assert Ok(strategy) = vestibule_oidc.discover("https://accounts.google.com")

// Or fetch configuration separately for inspection:
let assert Ok(config) = vestibule_oidc.fetch_configuration("https://accounts.google.com")
let strategy = vestibule_oidc.strategy_from_config(config, "my-provider")

Types

OidcConfig

Configuration discovered from an OpenID Connect provider’s /.well-known/openid-configuration endpoint.

pub type OidcConfig

Functions

authorization_endpoint

Get the authorization endpoint URL for an OIDC configuration.

pub fn authorization_endpoint(OidcConfig) -> String

build_authorization_code_request

Build an OIDC authorization-code token request without sending it.

pub fn build_authorization_code_request(
  OidcConfig,
  config.ClientConfig,
  String,
  option.Option(String)
) -> Result(provider_support.SecureRequest, error.AuthError(a))

build_discovery_request

Build an OIDC discovery request without sending it.

The returned request is opaque and can only be sent with provider_support.send_public, which performs DNS validation and address pinning immediately before connecting.

pub fn build_discovery_request(String) -> Result(provider_support.SecureRequest, error.AuthError(a))

build_refresh_token_request

Build an OIDC refresh-token request without sending it.

pub fn build_refresh_token_request(
  OidcConfig,
  config.ClientConfig,
  String
) -> Result(provider_support.SecureRequest, error.AuthError(a))

build_user_info_request

Build an OIDC userinfo request without sending it.

pub fn build_user_info_request(
  OidcConfig,
  credential.Credentials
) -> Result(provider_support.SecureRequest, error.AuthError(a))

discover

Discover an OIDC provider and build a strategy in one step.

Fetches the discovery document from the issuer’s well-known endpoint, then constructs a strategy using the discovered configuration. The issuer’s hostname is used as the provider name.

pub fn discover(String) -> Result(strategy.Strategy(a), error.AuthError(a))

discovery_url

Build the OpenID Connect discovery URL for an issuer URL.

Per OIDC Discovery, path-based issuers insert /.well-known/openid-configuration between the host and issuer path.

pub fn discovery_url(String) -> Result(String, error.AuthError(a))

fetch_configuration

Fetch the OpenID Connect configuration from a provider’s discovery endpoint.

Constructs the well-known URL from the issuer, makes a GET request, parses the JSON response, and validates that the issuer field in the response matches the provided issuer_url (a security requirement per the OIDC spec).

Dynamic issuer URLs are sent through Vestibule’s secure transport, which requires public HTTPS, validates every DNS answer, pins the connection, and disables redirects.

pub fn fetch_configuration(String) -> Result(OidcConfig, error.AuthError(a))

filter_default_scopes

Filter scopes to only include the standard OIDC scopes that the provider supports.

Supported helper for custom OIDC strategy authors.

pub fn filter_default_scopes(List(String)) -> List(String)

issuer

Get the issuer identifier for an OIDC configuration.

pub fn issuer(OidcConfig) -> String

new_config

Construct a validated OIDC configuration.

The issuer and endpoint URLs must use HTTPS and target a publicly-routable host. Loopback (localhost, 127.0.0.1, [::1]), private, and link-local addresses are rejected: these endpoints come from a provider-controlled discovery document and are called server-side with an Authorization header, so permitting internal hosts would enable SSRF.

pub fn new_config(
  issuer: String,
  authorization_endpoint: String,
  token_endpoint: String,
  userinfo_endpoint: String,
  scopes_supported: List(String)
) -> Result(OidcConfig, error.AuthError(a))

parse_authorization_code_response

Parse an OIDC authorization-code HTTP response without performing I/O.

pub fn parse_authorization_code_response(response.Response(String)) -> Result(strategy.ExchangeResult, error.AuthError(a))

parse_discovery_document

Parse an OIDC discovery JSON document into an OidcConfig.

Supported parsing helper for custom OIDC strategy authors. Extracts the required fields from the standard OpenID Connect discovery response.

pub fn parse_discovery_document(String) -> Result(OidcConfig, error.AuthError(a))

parse_discovery_response

Parse and validate an OIDC discovery HTTP response without performing I/O.

In addition to parsing the document and validating all discovered endpoints, this enforces the OIDC requirement that the returned issuer matches the issuer used to construct the request.

pub fn parse_discovery_response(
  String,
  response.Response(String)
) -> Result(OidcConfig, error.AuthError(a))

parse_refresh_token_response

Parse an OIDC refresh-token HTTP response without performing I/O.

pub fn parse_refresh_token_response(response.Response(String)) -> Result(credential.Credentials, error.AuthError(a))

parse_token_response

Parse a standard OAuth2/OIDC token response.

Supported parsing helper for custom OIDC strategy authors. Handles both success and error responses.

pub fn parse_token_response(String) -> Result(credential.Credentials, error.AuthError(a))

parse_user_info_response

Parse an OIDC userinfo HTTP response without performing I/O.

pub fn parse_user_info_response(response.Response(String)) -> Result(#(String, user_info.UserInfo), error.AuthError(a))

parse_userinfo_response

Parse a standard OIDC userinfo response into a uid and UserInfo.

Supported parsing helper for custom OIDC strategy authors. Maps standard OIDC claims to UserInfo fields:

• sub -> uid
• name -> name
• email -> email
• preferred_username -> nickname
• picture -> image

pub fn parse_userinfo_response(String) -> Result(#(String, user_info.UserInfo), error.AuthError(a))

scopes_supported

Get the scopes supported by an OIDC configuration.

pub fn scopes_supported(OidcConfig) -> List(String)

strategy_from_config

Build a Strategy from a discovered OidcConfig.

The resulting strategy uses standard OIDC/OAuth2 flows:

• Authorization code flow for authentication
• Standard token exchange
• Userinfo endpoint for user claims

The provider_name is used as the strategy’s provider identifier.

pub fn strategy_from_config(
  OidcConfig,
  String
) -> strategy.Strategy(a)

token_endpoint

Get the token endpoint URL for an OIDC configuration.

pub fn token_endpoint(OidcConfig) -> String

userinfo_endpoint

Get the userinfo endpoint URL for an OIDC configuration.

pub fn userinfo_endpoint(OidcConfig) -> String