satorbis_kit.auth.auth_oidc module

OIDCAuth — the single entry-point class for the notebook.

Responsibilities

  • Build the PKCE authorization URL

  • Launch the local callback server

  • Wait for the callback and exchange the code for tokens

  • Enforce that the authenticated identity matches the expected email

  • Return a valid access token, refreshing automatically if needed

  • Refresh tokens explicitly on demand

exception satorbis_kit.auth.auth_oidc.IdentityMismatchError[source]

Bases: Exception

Raised when the email in the returned token does not match the login_hint supplied to OIDCAuth.start_login().

This prevents a user from clearing the pre-filled email in the browser and authenticating as a different identity.

class satorbis_kit.auth.auth_oidc.OIDCAuth(environment: Environment | str | None = None, application: str | None = None, redirect_port: int = 4200, scopes: str = 'openid profile email offline_access', callback_timeout: int = 300, authorization_url: str | None = None, token_url: str | None = None, verify_jwt: bool = True)[source]

Bases: BaseAuth

Manages the full OIDC Authorization Code + PKCE flow against an OIDC provider, designed for use inside a Jupyter notebook.

Parameters:

  • environment – Target deployment environment. Accepts an Environment member, a plain string ("prod" or "dev"), or None. When None the value of the SATORBIS_ENV environment variable is used; if that is also absent, prod is the default. Example: OIDCAuth(environment="dev").

  • application – Application name used to look up a Zitadel project ID from the environment’s project_ids mapping. When a project ID is found, urn:zitadel:iam:org:project:id:{project_id}:aud is appended to the requested scopes so the token carries the project audience claim. Example: OIDCAuth(application="spatial_engine").

  • redirect_port – Local port for the OAuth callback server. Must match the redirect URI registered with the provider. Default: 4200.

  • scopes – Space-separated OIDC scopes. Include offline_access to receive a refresh token.

  • callback_timeout – Seconds to wait for the browser callback before raising TimeoutError. Default: 300 (5 minutes).

  • authorization_url – Optional. The authorization endpoint URL. If not provided, it will be discovered from the OIDC discovery document.

  • token_url – Optional. The token endpoint URL. If not provided, it will be discovered from the OIDC discovery document.

  • verify_jwt – If True, JWT signature verification is performed using the provider’s JWKS when enforcing email identity. Default: True.

authenticate() → TokenStore[source]

For interactive OIDC flows, use start_login() followed by await_callback(). This method is not directly applicable to interactive browser-based flows.

Raises:

NotImplementedError – Always. Use start_login() + await_callback() instead.

await_callback() → TokenStore[source]

Block until the browser callback is received, exchange the authorization code for tokens, then verify that the authenticated email matches the login_hint from start_login().

Raises:

  • RuntimeError – If start_login() has not been called first.

  • TimeoutError – If no callback is received within callback_timeout seconds.

  • IdentityMismatchError – If the authenticated user’s email does not match the expected login_hint. Tokens are not stored in this case.

refresh_token() → TokenStore[source]

Exchange the refresh token for a new access token (and possibly a new refresh token). Updates tokens in-place.

Providers with refresh token rotation return a new refresh token with each call, which is saved automatically.

Returns:

The updated token store.

Return type:

TokenStore

Raises:

ValueError – If no refresh token is available (e.g. offline_access scope was not requested).

start_login(login_hint: str = '') → str[source]

Generate the PKCE authorization URL and start the local callback server in a background thread.

The login_hint email is remembered and enforced in await_callback() — if the user authenticates as a different identity, IdentityMismatchError is raised and no tokens are stored.

Parameters:

login_hint – Email address to pre-fill on the provider login page. When provided, the authenticated token must match this email.

Returns:

The authorization URL. The user must open it in a browser.

Return type:

str