acmadauth.handlers module

Keycloak OIDC Device Flow Handler

class acmadauth.handlers.KeycloakOIDCDeviceFlowHandler(realm_url, client_id, client_secret=None, scopes='openid profile email offline_access', verify_tls=True, timeout=10)

Bases: object

Handler for Keycloak OIDC Device Flow.

Parameters:

  • realm_url (str) – The Keycloak realm URL.

  • client_id (str) – The client ID.

  • client_secret (str | None) – The client secret, if applicable.

  • scopes (str) – The scopes to request. Default is “openid profile email offline_access”.

  • verify_tls (bool) – Whether to verify TLS certificates. Default is True.

  • timeout (int) – The HTTP request timeout in seconds. Default is 10.

__get_error_from_response(r)

Extract error from HTTP response if present.

Parameters:

r (Response) – The HTTP response.

Return type:

str | None

Returns:

The error string if present, None otherwise.

__handle_verification_url(open_browser, show_qr, show_url, login_url_callback, verification_uri, user_code, complete)
__make_token_request(device_code, client_secret_post, token_url, client)

Make the token request to the token endpoint.

Parameters:

  • device_code – The device code.

  • client_secret_post – Whether to send client_secret in the POST body instead of using HTTP Basic

  • token_url – The token endpoint URL.

  • client – The HTTPX client.

Returns:

The HTTP response from the token endpoint.

_get_discovery()

Fetch and cache the OIDC discovery document. :rtype: dict[str, Any] :returns: The OIDC discovery document.

_token_auth()

Keycloak supports client_secret_basic and client_secret_post (per your config). If client_secret is set, we’ll use HTTP Basic, which is widely supported.

Return type:

Auth | UseClientDefault

Returns:

The HTTP BasicAuth object if client_secret is set, None otherwise.

ensure_tokens(cache, *, open_browser=False, show_qr=True, show_url=True, login_url_callback=None)

Load cached tokens, refresh if needed, otherwise run device flow.

Parameters:

  • cache (TokenCache) – The token cache to use.

  • open_browser (bool) – Whether to open the browser automatically during device flow.

  • show_qr (bool) – Whether to display a QR code for the device flow URL.

  • show_url (bool) – Whether to display the device flow URL.

  • login_url_callback (Callable[[str], None] | None) – Optional callback function to handle the login URL. (e.g. if the url needs to be shown in a GUI)

Return type:

TokenSet

Returns:

The valid token set.

Raises:

DeviceAuthError – If device authorization or token refresh fails.

poll_token_endpoint(device_code, interval, expires_in, client_secret_post=False)

Poll the token endpoint for tokens using the device code.

Parameters:

  • device_code (str) – The device code obtained from the device authorization response.

  • interval (int) – The polling interval in seconds.

  • expires_in (int) – The expiration time of the device code in seconds.

  • client_secret_post (bool) – Whether to send client_secret in the POST body instead of using HTTP Basic Auth.

Return type:

TokenSet

Returns:

The token set obtained from the token endpoint.

refresh(refresh_token)

Refresh tokens using the refresh token.

Parameters:

refresh_token (str) – The refresh token.

Return type:

TokenSet

Returns:

The new token set obtained from the token endpoint.

Raises:

DeviceAuthError – If the refresh operation fails.

start_device_authorization()

Start the device authorization flow.

Return type:

dict[str, Any]

Returns:

The device authorization response.