Discovery Policy¶

Configurable security policy for OpenID Connect discovery validation.

Policy Configuration¶

`DiscoveryPolicy(require_https=True, allow_http_on_loopback=True, validate_issuer=True, validate_endpoints=True, require_key_set=True, additional_endpoint_base_addresses=list(), authority=None)` `dataclass` ¶

Configurable security policy for discovery document validation.

Controls how strictly the library validates discovery documents and their endpoints. The default is strict (production-safe).

Attributes:

Name	Type	Description
`require_https`	`bool`	Require HTTPS for the discovery endpoint and all advertised endpoints. Set `False` for development against HTTP servers.
`allow_http_on_loopback`	`bool`	Allow HTTP when the host is `localhost`, `127.0.0.1`, or `::1`. Only applies when `require_https` is `True`.
`validate_issuer`	`bool`	Validate the `issuer` field in the discovery document.
`validate_endpoints`	`bool`	Validate that advertised endpoint URLs are well-formed.
`require_key_set`	`bool`	Require a `jwks_uri` in the discovery document.
`additional_endpoint_base_addresses`	`list[str]`	Extra base URLs that advertised endpoints are allowed to use (for multi-domain or CDN setups).
`authority`	`str \| None`	Expected authority (scheme + host) for endpoint validation. When `None`, derived from the discovery URL.

Endpoint Parsing¶

`DiscoveryEndpoint(url, authority)` `dataclass` ¶

Parsed discovery endpoint URL with extracted authority.

Attributes:

Name	Type	Description
`url`	`str`	The full discovery URL (with well-known path appended if not already present).
`authority`	`str`	The scheme + host portion of the URL.

`parse_discovery_url(url)` ¶

Parse a discovery URL and extract its authority.

If the URL does not end with the well-known path, it is appended automatically.

Parameters:

Name	Type	Description	Default
`url`	`str`	The discovery endpoint URL or base issuer URL.	required

Returns:

Type	Description
`DiscoveryEndpoint`	DiscoveryEndpoint with the full URL and extracted authority.

Raises:

Type	Description
`ConfigurationException`	If the URL is malformed.

Utilities¶

`validate_url_scheme(url, policy)` ¶

Validate a URL's scheme against the discovery policy.

Parameters:

Name	Type	Description	Default
`url`	`str \| None`	The URL to validate.	required
`policy`	`DiscoveryPolicy`	The discovery policy to apply.	required

Raises:

Type	Description
`ConfigurationException`	If the URL scheme violates the policy.

`is_loopback(host)` ¶

Check if a host is a loopback address.

Recognizes localhost, 127.0.0.1, ::1, and 127.x.x.x addresses. Uses ipaddress for safe parsing so that DNS names like 127.evil.com are not matched.

Discovery Policy¶

Policy Configuration¶