pywry.auth.providers¶

OAuth2 provider abstractions and concrete implementations.

OAuthProvider (ABC)¶

pywry.auth.providers.OAuthProvider ¶

OAuthProvider(client_id: str, client_secret: str = '', scopes: list[str] | None = None, authorize_url: str = '', token_url: str = '', userinfo_url: str = '', revocation_url: str = '')

Bases: ABC

Abstract base class for OAuth2 providers.

PARAMETER	DESCRIPTION
`client_id`	The OAuth2 client ID. TYPE: `str`
`client_secret`	The OAuth2 client secret (empty string for public clients). TYPE: `str` DEFAULT: `''`
`scopes`	Requested OAuth2 scopes. TYPE: `list[str]` DEFAULT: `None`
`authorize_url`	The provider's authorization endpoint. TYPE: `str` DEFAULT: `''`
`token_url`	The provider's token exchange endpoint. TYPE: `str` DEFAULT: `''`
`userinfo_url`	The provider's userinfo endpoint (optional for non-OIDC). TYPE: `str` DEFAULT: `''`
`revocation_url`	The provider's token revocation endpoint (RFC 7009). TYPE: `str` DEFAULT: `''`

Initialize OAuth provider.

Functions¶

close `async` ¶

close() -> None

Close the shared HTTP client. Call from app shutdown lifecycle.

build_authorize_url ¶

build_authorize_url(redirect_uri: str, state: str, pkce: PKCEChallenge | None = None, extra_params: dict[str, str] | None = None) -> str

Build the full authorization URL.

PARAMETER	DESCRIPTION
`redirect_uri`	The callback URL to redirect to after authorization. TYPE: `str`
`state`	CSRF protection nonce. TYPE: `str`
`pkce`	PKCE challenge for public clients. TYPE: `PKCEChallenge` DEFAULT: `None`
`extra_params`	Additional query parameters. TYPE: `dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	The full authorization URL.

exchange_code `abstractmethod` `async` ¶

exchange_code(code: str, redirect_uri: str, pkce_verifier: str | None = None, nonce: str | None = None) -> OAuthTokenSet

Exchange authorization code for tokens.

PARAMETER	DESCRIPTION
`code`	The authorization code from the callback. TYPE: `str`
`redirect_uri`	The redirect URI used in the authorization request. TYPE: `str`
`pkce_verifier`	The PKCE code verifier if PKCE was used. TYPE: `str` DEFAULT: `None`
`nonce`	The nonce sent in the authorize request (for ID token validation). TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`OAuthTokenSet`	The token set from the provider.

RAISES	DESCRIPTION
`TokenError`	If the code exchange fails.

refresh_tokens `abstractmethod` `async` ¶

refresh_tokens(refresh_token: str) -> OAuthTokenSet

Refresh an expired access token.

PARAMETER	DESCRIPTION
`refresh_token`	The refresh token. TYPE: `str`

RETURNS	DESCRIPTION
`OAuthTokenSet`	A new token set with a fresh access token.

RAISES	DESCRIPTION
`TokenRefreshError`	If the refresh fails.

get_userinfo `async` ¶

get_userinfo(access_token: str) -> dict[str, Any]

Fetch user profile information from the provider.

PARAMETER	DESCRIPTION
`access_token`	A valid access token. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	User profile data from the provider.

revoke_token `async` ¶

revoke_token(token: str) -> bool

Revoke a token at the provider (RFC 7009).

Posts to the revocation_url if one is configured. Subclasses with non-standard revocation APIs should override.

PARAMETER	DESCRIPTION
`token`	The token to revoke (access or refresh). TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if revocation succeeded, False if no endpoint is configured or the request failed.

GenericOIDCProvider¶

pywry.auth.providers.GenericOIDCProvider ¶

GenericOIDCProvider(client_id: str, client_secret: str = '', issuer_url: str = '', scopes: list[str] | None = None, authorize_url: str = '', token_url: str = '', userinfo_url: str = '', revocation_url: str = '', *, require_id_token_validation: bool = True)

Bases: OAuthProvider

Generic OpenID Connect provider.

Supports auto-discovery from /.well-known/openid-configuration if an issuer_url is provided.

PARAMETER	DESCRIPTION
`client_id`	The OAuth2 client ID. TYPE: `str`
`client_secret`	The OAuth2 client secret. TYPE: `str` DEFAULT: `''`
`issuer_url`	The OIDC issuer URL (used for auto-discovery). TYPE: `str` DEFAULT: `''`
`scopes`	Requested scopes (defaults to `["openid", "email", "profile"]`). TYPE: `list[str]` DEFAULT: `None`

Initialize OIDC provider.

Functions¶

validate_id_token `async` ¶

validate_id_token(id_token: str, nonce: str | None = None) -> dict[str, Any]

Validate an OIDC ID token.

Checks signature (via JWKS), issuer, audience, expiry, and nonce.

PARAMETER	DESCRIPTION
`id_token`	The raw ID token JWT string. TYPE: `str`
`nonce`	Expected nonce value (if one was sent in the authorize request). TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	The validated claims from the ID token.

RAISES	DESCRIPTION
`TokenError`	If validation fails for any reason.

exchange_code `async` ¶

exchange_code(code: str, redirect_uri: str, pkce_verifier: str | None = None, nonce: str | None = None) -> OAuthTokenSet

Exchange authorization code for tokens via OIDC token endpoint.

PARAMETER	DESCRIPTION
`code`	The authorization code from the callback. TYPE: `str`
`redirect_uri`	The redirect URI used in the authorization request. TYPE: `str`
`pkce_verifier`	The PKCE code verifier if PKCE was used. TYPE: `str` DEFAULT: `None`
`nonce`	The nonce sent in the authorize request (for ID token validation). TYPE: `str` DEFAULT: `None`

refresh_tokens `async` ¶

refresh_tokens(refresh_token: str) -> OAuthTokenSet

Refresh tokens via OIDC token endpoint.

revoke_token `async` ¶

revoke_token(token: str) -> bool

Revoke a token via the OIDC revocation endpoint.

Triggers endpoint auto-discovery before delegating to the base implementation.

close `async` ¶

close() -> None

Close the shared HTTP client. Call from app shutdown lifecycle.

build_authorize_url ¶

build_authorize_url(redirect_uri: str, state: str, pkce: PKCEChallenge | None = None, extra_params: dict[str, str] | None = None) -> str

Build the full authorization URL.

PARAMETER	DESCRIPTION
`redirect_uri`	The callback URL to redirect to after authorization. TYPE: `str`
`state`	CSRF protection nonce. TYPE: `str`
`pkce`	PKCE challenge for public clients. TYPE: `PKCEChallenge` DEFAULT: `None`
`extra_params`	Additional query parameters. TYPE: `dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	The full authorization URL.

get_userinfo `async` ¶

get_userinfo(access_token: str) -> dict[str, Any]

Fetch user profile information from the provider.

PARAMETER	DESCRIPTION
`access_token`	A valid access token. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	User profile data from the provider.

GoogleProvider¶

pywry.auth.providers.GoogleProvider ¶

GoogleProvider(client_id: str, client_secret: str = '', scopes: list[str] | None = None)

Bases: GenericOIDCProvider

Google OAuth2 provider with preset endpoints.

PARAMETER	DESCRIPTION
`client_id`	Google OAuth2 client ID. TYPE: `str`
`client_secret`	Google OAuth2 client secret. TYPE: `str` DEFAULT: `''`
`scopes`	Requested scopes (defaults to openid, email, profile). TYPE: `list[str]` DEFAULT: `None`

Initialize Google provider.

Functions¶

build_authorize_url ¶

build_authorize_url(redirect_uri: str, state: str, pkce: PKCEChallenge | None = None, extra_params: dict[str, str] | None = None) -> str

Build Google authorization URL with access_type=offline.

close `async` ¶

close() -> None

Close the shared HTTP client. Call from app shutdown lifecycle.

exchange_code `async` ¶

exchange_code(code: str, redirect_uri: str, pkce_verifier: str | None = None, nonce: str | None = None) -> OAuthTokenSet

Exchange authorization code for tokens via OIDC token endpoint.

PARAMETER	DESCRIPTION
`code`	The authorization code from the callback. TYPE: `str`
`redirect_uri`	The redirect URI used in the authorization request. TYPE: `str`
`pkce_verifier`	The PKCE code verifier if PKCE was used. TYPE: `str` DEFAULT: `None`
`nonce`	The nonce sent in the authorize request (for ID token validation). TYPE: `str` DEFAULT: `None`

refresh_tokens `async` ¶

refresh_tokens(refresh_token: str) -> OAuthTokenSet

Refresh tokens via OIDC token endpoint.

get_userinfo `async` ¶

get_userinfo(access_token: str) -> dict[str, Any]

Fetch user profile information from the provider.

PARAMETER	DESCRIPTION
`access_token`	A valid access token. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	User profile data from the provider.

revoke_token `async` ¶

revoke_token(token: str) -> bool

Revoke a token via the OIDC revocation endpoint.

Triggers endpoint auto-discovery before delegating to the base implementation.

validate_id_token `async` ¶

validate_id_token(id_token: str, nonce: str | None = None) -> dict[str, Any]

Validate an OIDC ID token.

Checks signature (via JWKS), issuer, audience, expiry, and nonce.

PARAMETER	DESCRIPTION
`id_token`	The raw ID token JWT string. TYPE: `str`
`nonce`	Expected nonce value (if one was sent in the authorize request). TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	The validated claims from the ID token.

RAISES	DESCRIPTION
`TokenError`	If validation fails for any reason.

GitHubProvider¶

pywry.auth.providers.GitHubProvider ¶

GitHubProvider(client_id: str, client_secret: str = '', scopes: list[str] | None = None)

Bases: OAuthProvider

GitHub OAuth2 provider.

GitHub uses a non-standard token exchange (no OIDC) and a separate API endpoint for user info.

PARAMETER	DESCRIPTION
`client_id`	GitHub OAuth2 client ID. TYPE: `str`
`client_secret`	GitHub OAuth2 client secret. TYPE: `str` DEFAULT: `''`
`scopes`	Requested scopes (defaults to `["read:user", "user:email"]`). TYPE: `list[str]` DEFAULT: `None`

Initialize GitHub provider.

Functions¶

exchange_code `async` ¶

exchange_code(code: str, redirect_uri: str, pkce_verifier: str | None = None, nonce: str | None = None) -> OAuthTokenSet

Exchange authorization code for a GitHub access token.

refresh_tokens `async` ¶

refresh_tokens(refresh_token: str) -> OAuthTokenSet

Refresh GitHub tokens (GitHub uses token rotation).

revoke_token `async` ¶

revoke_token(token: str) -> bool

Revoke a GitHub token via the Applications API.

Uses DELETE /applications/{client_id}/token with HTTP Basic authentication (client_id / client_secret).

PARAMETER	DESCRIPTION
`token`	The access token to revoke. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if GitHub accepted the revocation.

close `async` ¶

close() -> None

Close the shared HTTP client. Call from app shutdown lifecycle.

build_authorize_url ¶

build_authorize_url(redirect_uri: str, state: str, pkce: PKCEChallenge | None = None, extra_params: dict[str, str] | None = None) -> str

Build the full authorization URL.

PARAMETER	DESCRIPTION
`redirect_uri`	The callback URL to redirect to after authorization. TYPE: `str`
`state`	CSRF protection nonce. TYPE: `str`
`pkce`	PKCE challenge for public clients. TYPE: `PKCEChallenge` DEFAULT: `None`
`extra_params`	Additional query parameters. TYPE: `dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	The full authorization URL.

get_userinfo `async` ¶

get_userinfo(access_token: str) -> dict[str, Any]

Fetch user profile information from the provider.

PARAMETER	DESCRIPTION
`access_token`	A valid access token. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	User profile data from the provider.

MicrosoftProvider¶

pywry.auth.providers.MicrosoftProvider ¶

MicrosoftProvider(client_id: str, client_secret: str = '', tenant_id: str = 'common', scopes: list[str] | None = None)

Bases: GenericOIDCProvider

Microsoft / Azure AD OAuth2 provider.

PARAMETER	DESCRIPTION
`client_id`	Azure AD application (client) ID. TYPE: `str`
`client_secret`	Azure AD client secret. TYPE: `str` DEFAULT: `''`
`tenant_id`	Azure AD tenant ID (default "common" for multi-tenant). TYPE: `str` DEFAULT: `'common'`
`scopes`	Requested scopes. TYPE: `list[str]` DEFAULT: `None`

Initialize Microsoft provider.

Functions¶

close `async` ¶

close() -> None

Close the shared HTTP client. Call from app shutdown lifecycle.

build_authorize_url ¶

build_authorize_url(redirect_uri: str, state: str, pkce: PKCEChallenge | None = None, extra_params: dict[str, str] | None = None) -> str

Build the full authorization URL.

PARAMETER	DESCRIPTION
`redirect_uri`	The callback URL to redirect to after authorization. TYPE: `str`
`state`	CSRF protection nonce. TYPE: `str`
`pkce`	PKCE challenge for public clients. TYPE: `PKCEChallenge` DEFAULT: `None`
`extra_params`	Additional query parameters. TYPE: `dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	The full authorization URL.

exchange_code `async` ¶

exchange_code(code: str, redirect_uri: str, pkce_verifier: str | None = None, nonce: str | None = None) -> OAuthTokenSet

Exchange authorization code for tokens via OIDC token endpoint.

PARAMETER	DESCRIPTION
`code`	The authorization code from the callback. TYPE: `str`
`redirect_uri`	The redirect URI used in the authorization request. TYPE: `str`
`pkce_verifier`	The PKCE code verifier if PKCE was used. TYPE: `str` DEFAULT: `None`
`nonce`	The nonce sent in the authorize request (for ID token validation). TYPE: `str` DEFAULT: `None`

refresh_tokens `async` ¶

refresh_tokens(refresh_token: str) -> OAuthTokenSet

Refresh tokens via OIDC token endpoint.

get_userinfo `async` ¶

get_userinfo(access_token: str) -> dict[str, Any]

Fetch user profile information from the provider.

PARAMETER	DESCRIPTION
`access_token`	A valid access token. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	User profile data from the provider.

revoke_token `async` ¶

revoke_token(token: str) -> bool

Revoke a token via the OIDC revocation endpoint.

Triggers endpoint auto-discovery before delegating to the base implementation.

validate_id_token `async` ¶

validate_id_token(id_token: str, nonce: str | None = None) -> dict[str, Any]

Validate an OIDC ID token.

Checks signature (via JWKS), issuer, audience, expiry, and nonce.

PARAMETER	DESCRIPTION
`id_token`	The raw ID token JWT string. TYPE: `str`
`nonce`	Expected nonce value (if one was sent in the authorize request). TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	The validated claims from the ID token.

RAISES	DESCRIPTION
`TokenError`	If validation fails for any reason.

Factory¶

pywry.auth.providers.create_provider_from_settings ¶

create_provider_from_settings(settings: Any) -> OAuthProvider

Create an OAuthProvider instance from OAuth2Settings.

PARAMETER	DESCRIPTION
`settings`	The OAuth2 configuration settings. TYPE: `OAuth2Settings`

RETURNS	DESCRIPTION
`OAuthProvider`	A configured provider instance.

RAISES	DESCRIPTION
`AuthenticationError`	If the provider type is unknown or settings are invalid.

pywry.auth.providers¶

OAuthProvider (ABC)¶

pywry.auth.providers.OAuthProvider ¶

Functions¶

close async ¶

build_authorize_url ¶

exchange_code abstractmethod async ¶

refresh_tokens abstractmethod async ¶

get_userinfo async ¶

revoke_token async ¶

GenericOIDCProvider¶

pywry.auth.providers.GenericOIDCProvider ¶

Functions¶

validate_id_token async ¶

exchange_code async ¶

refresh_tokens async ¶

revoke_token async ¶

close async ¶

build_authorize_url ¶

get_userinfo async ¶

GoogleProvider¶

pywry.auth.providers.GoogleProvider ¶

Functions¶

build_authorize_url ¶

close async ¶

exchange_code async ¶

refresh_tokens async ¶

get_userinfo async ¶

revoke_token async ¶

validate_id_token async ¶

GitHubProvider¶

pywry.auth.providers.GitHubProvider ¶

Functions¶

exchange_code async ¶

refresh_tokens async ¶

revoke_token async ¶

close async ¶

build_authorize_url ¶

get_userinfo async ¶

MicrosoftProvider¶

pywry.auth.providers.MicrosoftProvider ¶

Functions¶

close async ¶

build_authorize_url ¶

exchange_code async ¶

refresh_tokens async ¶

get_userinfo async ¶

revoke_token async ¶

validate_id_token async ¶

Factory¶

pywry.auth.providers.create_provider_from_settings ¶

close `async` ¶

exchange_code `abstractmethod` `async` ¶

refresh_tokens `abstractmethod` `async` ¶

get_userinfo `async` ¶

revoke_token `async` ¶

validate_id_token `async` ¶

exchange_code `async` ¶

refresh_tokens `async` ¶

revoke_token `async` ¶

close `async` ¶

get_userinfo `async` ¶

close `async` ¶

exchange_code `async` ¶

refresh_tokens `async` ¶

get_userinfo `async` ¶

revoke_token `async` ¶

validate_id_token `async` ¶

exchange_code `async` ¶

refresh_tokens `async` ¶

revoke_token `async` ¶

close `async` ¶

get_userinfo `async` ¶

close `async` ¶

exchange_code `async` ¶

refresh_tokens `async` ¶

get_userinfo `async` ¶

revoke_token `async` ¶

validate_id_token `async` ¶