okta-client-python 0.1.0__py3-none-any.whl

okta_client/__init__.py

@@ -0,0 +1,20 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+"""Okta Client SDK (Python)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("okta-client-python")
+except PackageNotFoundError:  # pragma: no cover - not installed
+    __version__ = "0.0.0-dev"
+
+__all__ = ["__version__", "authfoundation", "browser_signin", "directauth", "oauth2auth"]

okta_client/authfoundation/__init__.py

@@ -0,0 +1,197 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+"""Core networking, OAuth2 primitives, token models, and storage interfaces."""
+
+from .authentication import (
+    AuthenticationContext,
+    AuthenticationFlow,
+    AuthenticationListener,
+    AuthenticationState,
+    BaseAuthenticationFlow,
+    PKCEData,
+    StandardAuthenticationContext,
+    generate_pkce,
+)
+from .coalesced_result import CoalescedResult
+from .codable import Codable
+from .expires import Expires
+from .key_provider import (
+    DefaultKeyProvider,
+    KeyProvider,
+    LocalKeyProvider,
+    get_key_provider,
+    set_key_provider,
+)
+from .networking import (
+    APIAuthorization,
+    APIClient,
+    APIClientConfiguration,
+    APIClientListener,
+    APIContentType,
+    APIParsingContext,
+    APIRateLimit,
+    APIRequest,
+    APIRequestBody,
+    APIRequestBodyMixin,
+    APIRequestMethod,
+    APIResponse,
+    APIRetry,
+    BaseAPIRequest,
+    DefaultNetworkInterface,
+    HTTPRequest,
+    ListenerCollection,
+    NetworkInterface,
+    RawResponse,
+    RequestValue,
+    RequestValueConvertible,
+)
+from .oauth2 import (
+    JWK,
+    JWKS,
+    JWT,
+    ClientAssertionAuthorization,
+    ClientAuthorization,
+    ClientIdAuthorization,
+    ClientSecretAuthorization,
+    ConfigurationError,
+    ConfigurationFileNotFoundError,
+    ConfigurationParseError,
+    DefaultTokenHashValidator,
+    DefaultTokenValidator,
+    HasClaims,
+    IdTokenClaim,
+    IDTokenValidatorContext,
+    InvalidConfigurationError,
+    JWTBearerClaims,
+    JWTType,
+    JWTUsageContext,
+    JWTValidationContext,
+    OAuth2APIRequest,
+    OAuth2APIRequestCategory,
+    OAuth2ClientConfiguration,
+    OAuth2Error,
+    OAuth2TokenRequest,
+    OAuth2TokenRequestDefaults,
+    OpenIdConfiguration,
+    ProvidesOAuth2Parameters,
+    TokenHashValidator,
+    TokenInfo,
+    TokenValidator,
+    UserInfo,
+    get_access_token_validator,
+    get_device_secret_validator,
+    get_token_validator,
+    set_access_token_validator,
+    set_device_secret_validator,
+    set_token_validator,
+)
+from .oauth2.client import OAuth2Client, OAuth2ClientListener
+from .oauth2.refresh_token import RefreshTokenFlow, RefreshTokenRequest
+from .time_coordinator import (
+    DefaultTimeCoordinator,
+    TimeCoordinator,
+    get_time_coordinator,
+    set_time_coordinator,
+)
+from .token import (
+    GrantedTokenType,
+    Token,
+    TokenContext,
+)
+
+__all__ = [
+    "JWK",
+    "JWKS",
+    "JWT",
+    "APIAuthorization",
+    "APIClient",
+    "APIClientConfiguration",
+    "APIClientListener",
+    "APIContentType",
+    "APIParsingContext",
+    "APIRateLimit",
+    "APIRequest",
+    "APIRequestBody",
+    "APIRequestBodyMixin",
+    "APIRequestMethod",
+    "APIResponse",
+    "APIRetry",
+    "AuthenticationContext",
+    "AuthenticationFlow",
+    "AuthenticationListener",
+    "AuthenticationState",
+    "BaseAPIRequest",
+    "BaseAuthenticationFlow",
+    "ClientAssertionAuthorization",
+    "ClientAuthorization",
+    "ClientIdAuthorization",
+    "ClientSecretAuthorization",
+    "CoalescedResult",
+    "Codable",
+    "ConfigurationError",
+    "ConfigurationFileNotFoundError",
+    "ConfigurationParseError",
+    "DefaultKeyProvider",
+    "DefaultNetworkInterface",
+    "DefaultTimeCoordinator",
+    "DefaultTokenHashValidator",
+    "DefaultTokenValidator",
+    "Expires",
+    "GrantedTokenType",
+    "HTTPRequest",
+    "HasClaims",
+    "IDTokenValidatorContext",
+    "IdTokenClaim",
+    "InvalidConfigurationError",
+    "JWTBearerClaims",
+    "JWTType",
+    "JWTUsageContext",
+    "JWTValidationContext",
+    "KeyProvider",
+    "ListenerCollection",
+    "LocalKeyProvider",
+    "NetworkInterface",
+    "OAuth2APIRequest",
+    "OAuth2APIRequestCategory",
+    "OAuth2Client",
+    "OAuth2ClientConfiguration",
+    "OAuth2ClientListener",
+    "OAuth2Error",
+    "OAuth2TokenRequest",
+    "OAuth2TokenRequestDefaults",
+    "OpenIdConfiguration",
+    "PKCEData",
+    "ProvidesOAuth2Parameters",
+    "RawResponse",
+    "RefreshTokenFlow",
+    "RefreshTokenRequest",
+    "RequestValue",
+    "RequestValueConvertible",
+    "StandardAuthenticationContext",
+    "TimeCoordinator",
+    "Token",
+    "TokenContext",
+    "TokenHashValidator",
+    "TokenInfo",
+    "TokenValidator",
+    "UserInfo",
+    "generate_pkce",
+    "get_access_token_validator",
+    "get_device_secret_validator",
+    "get_key_provider",
+    "get_time_coordinator",
+    "get_token_validator",
+    "set_access_token_validator",
+    "set_device_secret_validator",
+    "set_key_provider",
+    "set_time_coordinator",
+    "set_token_validator",
+]

okta_client/authfoundation/authentication.py

@@ -0,0 +1,247 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Generic, Protocol, TypeVar, cast, runtime_checkable
+
+from .networking import ListenerCollection, RequestValue
+from .oauth2.parameters import OAuth2APIRequestCategory
+from .utils import base64url_encode
+
+ContextT = TypeVar("ContextT", bound="AuthenticationContext")
+
+
+class AuthenticationState(str, Enum):
+    """Lifecycle states for authentication flows."""
+    IDLE = "idle"
+    AUTHENTICATING = "authenticating"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class PKCEData:
+    """PKCE values used by authorization code flows."""
+    code_verifier: str
+    code_challenge: str
+    code_challenge_method: str = "S256"
+
+
+def generate_pkce() -> PKCEData:
+    """Generate a PKCE verifier/challenge pair using S256.
+
+    - ``code_verifier``: 32 random bytes, base64url-encoded (no padding).
+    - ``code_challenge``: SHA-256 hash of the verifier, base64url-encoded (no padding).
+    """
+    code_verifier = base64url_encode(os.urandom(32))
+    code_challenge = base64url_encode(hashlib.sha256(code_verifier.encode("ascii")).digest())
+    return PKCEData(
+        code_verifier=code_verifier,
+        code_challenge=code_challenge,
+        code_challenge_method="S256",
+    )
+
+
+@runtime_checkable
+class AuthenticationContext(Protocol):
+    """Protocol for per-session authentication context."""
+    @property
+    def acr_values(self) -> list[str] | None:
+        """ACR values requested for the session."""
+        ...
+
+    @property
+    def persist_values(self) -> Mapping[str, str] | None:
+        """Values to persist into token context, if any."""
+        ...
+
+    @property
+    def additional_parameters(self) -> Mapping[str, RequestValue] | None:
+        """Additional parameters for the session."""
+        ...
+
+    def parameters(self, category: OAuth2APIRequestCategory) -> Mapping[str, RequestValue] | None:
+        """Return OAuth2 parameters to include for the given request category."""
+        ...
+
+
+@runtime_checkable
+class AuthenticationListener(Protocol):
+    """Listener for authentication flow lifecycle events."""
+    def authentication_started(self, flow: AuthenticationFlow[Any]) -> None:
+        """Called when a flow starts authenticating."""
+        ...
+
+    def authentication_updated(self, flow: AuthenticationFlow[Any], context: AuthenticationContext) -> None:
+        """Called when a flow updates its context."""
+        ...
+
+    def authentication_completed(self, flow: AuthenticationFlow[Any], result: Any) -> None:
+        """Called when a flow completes successfully."""
+        ...
+
+    def authentication_failed(self, flow: AuthenticationFlow[Any], error: Exception) -> None:
+        """Called when a flow fails with an error."""
+        ...
+
+
+@dataclass(frozen=True)
+class StandardAuthenticationContext(AuthenticationContext):
+    """Default authentication context for OAuth2 flows."""
+
+    _acr_values: list[str] | None = None
+    _persist_values: Mapping[str, str] | None = None
+    _additional_parameters: Mapping[str, RequestValue] | None = None
+
+    @property
+    def acr_values(self) -> list[str] | None:
+        """ACR values requested for the session."""
+        return self._acr_values
+
+    @property
+    def persist_values(self) -> Mapping[str, str] | None:
+        """Values to persist into token context, if any."""
+        return self._persist_values
+
+    @property
+    def additional_parameters(self) -> Mapping[str, RequestValue] | None:
+        """Additional parameters for the session."""
+        return self._additional_parameters
+
+    def parameters(self, category: OAuth2APIRequestCategory) -> Mapping[str, RequestValue] | None:
+        """Return OAuth2 parameters contributed by this context."""
+        result: dict[str, RequestValue] = dict(self._additional_parameters or {})
+        if category == OAuth2APIRequestCategory.AUTHORIZATION and self._acr_values:
+            result["acr_values"] = " ".join(self._acr_values)
+        return result or None
+
+
+@runtime_checkable
+class AuthenticationFlow(Protocol, Generic[ContextT]):
+    """Protocol for authentication flows with start/resume/reset semantics."""
+    @property
+    def context(self) -> ContextT | None:
+        """Current session context, if any."""
+        ...
+
+    @property
+    def state(self) -> AuthenticationState:
+        """Current flow state."""
+        ...
+
+    @property
+    def is_authenticating(self) -> bool:
+        """Return True when authentication is in progress."""
+        ...
+
+    @property
+    def additional_parameters(self) -> Mapping[str, RequestValue] | None:
+        """Flow-level parameters applied to all requests."""
+        ...
+
+    @property
+    def listeners(self) -> ListenerCollection[AuthenticationListener]:
+        """Listener collection for flow events."""
+        ...
+
+    def reset(self) -> None:
+        """Reset flow state and context."""
+        ...
+
+    async def start(self, *args: Any, context: ContextT | None = None, **kwargs: Any) -> Any:
+        """Start authentication with optional context."""
+        ...
+
+    async def resume(self, *args: Any, context: ContextT, **kwargs: Any) -> Any:
+        """Resume authentication with additional context."""
+        ...
+
+
+class BaseAuthenticationFlow(Generic[ContextT]):
+    """Base class implementing common flow state and listener behavior."""
+    def __init__(self, additional_parameters: Mapping[str, RequestValue] | None = None) -> None:
+        """Initialize the flow with optional additional parameters."""
+        self._context: ContextT | None = None
+        self._state = AuthenticationState.IDLE
+        self._additional_parameters = additional_parameters
+        self._lock = asyncio.Lock()
+        self._listeners: ListenerCollection[AuthenticationListener] = ListenerCollection()
+
+    @property
+    def context(self) -> ContextT | None:
+        """Return the current context."""
+        return self._context
+
+    @property
+    def state(self) -> AuthenticationState:
+        """Return the current flow state."""
+        return self._state
+
+    @property
+    def is_authenticating(self) -> bool:
+        """Return True when the flow is authenticating."""
+        return self._state == AuthenticationState.AUTHENTICATING
+
+    @property
+    def additional_parameters(self) -> Mapping[str, RequestValue] | None:
+        """Return flow-level additional parameters."""
+        return self._additional_parameters
+
+    @property
+    def listeners(self) -> ListenerCollection[AuthenticationListener]:
+        """Return the listener collection."""
+        return self._listeners
+
+    def reset(self) -> None:
+        """Reset state and clear the current context."""
+        self._context = None
+        self._state = AuthenticationState.IDLE
+
+    async def _begin(self, context: ContextT | None) -> None:
+        """Begin a new authentication session and notify listeners."""
+        async with self._lock:
+            if self._state == AuthenticationState.AUTHENTICATING:
+                raise RuntimeError("Authentication already in progress")
+            self._context = context
+            self._state = AuthenticationState.AUTHENTICATING
+        flow = cast(AuthenticationFlow[Any], self)
+        for listener in self._listeners:
+            listener.authentication_started(flow)
+        if context is not None:
+            for listener in self._listeners:
+                listener.authentication_updated(flow, context)
+
+    def _update_context(self, context: ContextT) -> None:
+        """Update the current context and notify listeners."""
+        self._context = context
+        flow = cast(AuthenticationFlow[Any], self)
+        for listener in self._listeners:
+            listener.authentication_updated(flow, context)
+
+    def _complete(self, result: Any) -> None:
+        """Mark flow as completed and notify listeners."""
+        self._state = AuthenticationState.COMPLETED
+        flow = cast(AuthenticationFlow[Any], self)
+        for listener in self._listeners:
+            listener.authentication_completed(flow, result)
+
+    def _fail(self, error: Exception) -> None:
+        """Mark flow as failed and notify listeners."""
+        self._state = AuthenticationState.FAILED
+        flow = cast(AuthenticationFlow[Any], self)
+        for listener in self._listeners:
+            listener.authentication_failed(flow, error)

okta_client/authfoundation/coalesced_result.py

@@ -0,0 +1,113 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class CoalescedResult(Generic[T]):
+    """Coalesce concurrent async operations so only one in-flight task runs.
+
+    - Caches the last successful result.
+    - Errors are propagated to all awaiting callers and are not cached.
+    """
+
+    def __init__(self, *, ttl: float | None = None, time_provider: Callable[[], float] | None = None) -> None:
+        self._lock = asyncio.Lock()
+        self._active = False
+        self._value: T | None = None
+        self._fetched_at: float | None = None
+        self._ttl = ttl
+        self._time_provider = time_provider or time.time
+        self._waiters: list[asyncio.Future[T]] = []
+
+    @property
+    def is_active(self) -> bool:
+        return self._active
+
+    @property
+    def value(self) -> T | None:
+        return self._value
+
+    async def perform(
+        self,
+        operation: Callable[[], Awaitable[T]],
+        *,
+        reset: bool = False,
+    ) -> T:
+        """Perform the operation or await the in-flight result.
+
+        Args:
+            operation: Async callable that produces the result.
+            reset: If True, clears the cached value before proceeding.
+        """
+        future: asyncio.Future[T] | None = None
+        async with self._lock:
+            if reset:
+                self._value = None
+                self._fetched_at = None
+            if self._active:
+                loop = asyncio.get_running_loop()
+                future = loop.create_future()
+                self._waiters.append(future)
+            else:
+                if self._is_cache_valid():
+                    return self._value  # type: ignore[return-value]
+                self._active = True
+
+        if future is not None:
+            return await future
+
+        try:
+            result = await operation()
+        except Exception as exc:
+            await self._finish(error=exc)
+            raise
+        else:
+            await self._finish(result=result)
+            return result
+
+    async def _finish(self, result: T | None = None, error: Exception | None = None) -> None:
+        async with self._lock:
+            if error is None:
+                if self._ttl is not None and self._ttl <= 0:
+                    self._value = None
+                    self._fetched_at = None
+                else:
+                    self._value = result
+                    self._fetched_at = self._time_provider()
+            self._active = False
+            waiters = self._waiters
+            self._waiters = []
+
+        for waiter in waiters:
+            if waiter.done():
+                continue
+            if error is None:
+                waiter.set_result(result)  # type: ignore[arg-type]
+            else:
+                waiter.set_exception(error)
+
+    def _is_cache_valid(self) -> bool:
+        if self._value is None:
+            return False
+        if self._ttl is None:
+            return True
+        if self._ttl <= 0:
+            return False
+        if self._fetched_at is None:
+            return False
+        return (self._time_provider() - self._fetched_at) < self._ttl

okta_client/authfoundation/codable.py

@@ -0,0 +1,72 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+"""Serialization mixin for frozen dataclasses.
+
+Provides a lightweight ``Codable`` protocol (inspired by Swift's ``Codable``)
+that any :func:`~dataclasses.dataclass` can adopt to gain ``to_dict()`` /
+``from_dict()`` round-trip serialization without third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+
+class Codable:
+    """Mixin for frozen dataclasses that need dictionary (de)serialization.
+
+    Provides :meth:`to_dict` for serialization using :func:`dataclasses.asdict`
+    (with automatic :class:`~enum.Enum` → value conversion) and a
+    :meth:`from_dict` classmethod that subclasses override to reconstruct
+    nested types.
+
+    Usage::
+
+        @dataclass(frozen=True)
+        class MyModel(Codable):
+            name: str
+            kind: SomeEnum
+
+            @classmethod
+            def from_dict(cls, data: Mapping[str, Any]) -> "MyModel":
+                return cls(
+                    name=data["name"],
+                    kind=SomeEnum(data["kind"]),
+                )
+    """
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict suitable for JSON encoding.
+
+        Nested dataclasses are recursively converted to dicts.
+        :class:`~enum.Enum` members are reduced to their ``.value``.
+        """
+        return dataclasses.asdict(self, dict_factory=_enum_aware_dict_factory)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> Codable:
+        """Reconstruct an instance from a plain dict.
+
+        Subclasses **must** override this to handle nested dataclass and enum
+        fields that require type-aware reconstruction.
+        """
+        raise NotImplementedError(f"{cls.__name__} must implement from_dict()")
+
+
+def _enum_aware_dict_factory(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    """Dict factory for :func:`dataclasses.asdict` that converts enum values."""
+    return {
+        key: value.value if isinstance(value, Enum) else value
+        for key, value in pairs
+    }

okta_client/authfoundation/expires.py

@@ -0,0 +1,49 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from .time_coordinator import get_time_coordinator
+
+
+@runtime_checkable
+class Expires(Protocol):
+    """Protocol for objects that can expire based on issued time."""
+    @property
+    def expires_in(self) -> float:
+        """Return the lifetime in seconds."""
+        ...
+
+    @property
+    def issued_at(self) -> float | None:
+        """Return the issue time in seconds since epoch, if known."""
+        ...
+
+    @property
+    def expires_at(self) -> float | None:
+        """Return the calculated expiration time, if possible."""
+        if self.issued_at is None:
+            return None
+        return float(self.issued_at) + float(self.expires_in)
+
+    @property
+    def is_expired(self) -> bool:
+        """Return True when the object is expired."""
+        expires_at = self.expires_at
+        if expires_at is None:
+            return False
+        return get_time_coordinator().now() >= expires_at
+
+    @property
+    def is_valid(self) -> bool:
+        """Return True when the object is not expired."""
+        return not self.is_expired