5.2.9. xgt.OidcAuth

class xgt.OidcAuth(issuer: str = '', client_id: str = '', scopes: tuple[str, ...] | None = None, audience: str | None = None, use_server_audience: bool = False, ca_cert_path: str | None = None, cache_path: str | None = None, token_endpoint: str | None = None, device_authorization_endpoint: str | None = None, flow: str = 'auto', force_login: bool = False, open_browser: bool = True, authorization_endpoint: str | None = None, redirect_uri: str | None = None, callback_host: str = '127.0.0.1', callback_port: int = 8765, callback_timeout_seconds: int = 300, pkce: bool = True, client_secret: str | None = None)

Interactive OIDC authentication.

Experimental: The API of this class may change in future releases.

The default flow is ‘auto’: prefer browser-based authorization code + PKCE when the discovery document exposes an authorization endpoint, otherwise fall back to device flow when a device authorization endpoint is available.

Parameters:

  • flow (str) – One of ‘auto’, ‘auth_code’, or ‘device’.

  • force_login (bool) – Ignore any cached token and always start a new login flow.

  • open_browser (bool) – Automatically open the verification URL or authorization URL in the default browser. Set to False in headless environments where a browser is unavailable.

  • authorization_endpoint (Optional[str]) – Override the authorization endpoint URL. Used by authorization-code flow.

  • redirect_uri (Optional[str]) – Explicit redirect URI registered with the IdP. If omitted, a loopback redirect of the form http://127.0.0.1:{callback_port}/callback is used.

  • callback_host (str) – Host/interface for the temporary loopback listener.

  • callback_port (int) – Port for the temporary loopback listener.

  • callback_timeout_seconds (int) – Maximum time to wait for the browser redirect before failing.

  • pkce (bool) – When True, use PKCE for the authorization code flow. Set to False for providers that support auth-code flow but reject PKCE parameters.

  • client_secret (Optional[str]) – Optional client secret for the authorization code token exchange. Some providers require this field to be present even for localhost-style OAuth clients; OpenShift is one example.

Methods

resolved_cache_path()

Attributes

audience

Audience value for the token request.

authorization_endpoint

Override the authorization endpoint URL.

ca_cert_path

CA bundle to trust for OIDC HTTPS calls.

cache_path

Override the default on-disk token cache location.

callback_host

Host/interface for the temporary loopback listener.

callback_port

Port for the temporary loopback listener.

callback_timeout_seconds

Maximum seconds to wait for the browser redirect before failing.

client_id

OAuth2 client ID registered with the IdP.

client_secret

Optional client secret for the authorization code token exchange.

device_authorization_endpoint

Override the device authorization endpoint URL.

flow

'auto', 'auth_code', or 'device'.

force_login

When True, ignore any cached token and always start a new login flow.

issuer

OIDC issuer URL.

open_browser

When True, automatically open the browser for the login URL.

pkce

When True, use PKCE for the authorization code flow.

redirect_uri

Explicit redirect URI.

scopes

OAuth2 scopes to request.

token_endpoint

Override the token endpoint URL.

use_server_audience

When True and audience is None, retrieve the audience from the server's OIDC configuration.
audience: str | None = None

Audience value for the token request. Required by some IdPs (e.g. Auth0).

authorization_endpoint: str | None = None

Override the authorization endpoint URL. Used by authorization-code flow.

ca_cert_path: str | None = None

CA bundle to trust for OIDC HTTPS calls. Supports ‘~’ expansion.

cache_path: str | None = None

Override the default on-disk token cache location. Supports ‘~’ expansion.

callback_host: str = '127.0.0.1'

Host/interface for the temporary loopback listener.

callback_port: int = 8765

Port for the temporary loopback listener.

callback_timeout_seconds: int = 300

Maximum seconds to wait for the browser redirect before failing.

client_id: str = ''

OAuth2 client ID registered with the IdP. If empty, fetched from the server.

client_secret: str | None = None

Optional client secret for the authorization code token exchange.

device_authorization_endpoint: str | None = None

Override the device authorization endpoint URL. Only used by device flow.

flow: str = 'auto'

‘auto’, ‘auth_code’, or ‘device’.

Type:

Login flow to use

force_login: bool = False

When True, ignore any cached token and always start a new login flow.

issuer: str = ''

OIDC issuer URL. If empty, fetched from the server via GetOidcIssuer.

open_browser: bool = True

When True, automatically open the browser for the login URL.

pkce: bool = True

When True, use PKCE for the authorization code flow.

redirect_uri: str | None = None

Explicit redirect URI. If omitted, a loopback URI on callback_port is used.

scopes: tuple[str, ...] | None = None

OAuth2 scopes to request. If None, uses server-advertised or default scopes.

token_endpoint: str | None = None

Override the token endpoint URL.

use_server_audience: bool = False

When True and audience is None, retrieve the audience from the server’s OIDC configuration.