dara-core 1.22.4__py3-none-any.whl → 1.23.0__py3-none-any.whl

dara/core/auth/oidc/definitions.py

@@ -0,0 +1,312 @@
+from datetime import datetime, timedelta, timezone
+from secrets import token_urlsafe
+
+from pydantic import BaseModel, ConfigDict, Field
+
+JWK_CLIENT_REGISTRY_KEY = 'PyJWKClient'
+
+REFRESH_TOKEN_COOKIE_NAME = 'dara_refresh_token'
+
+
+class AuthCodeRequestBody(BaseModel):
+    """Request body for the SSO callback endpoint."""
+
+    auth_code: str
+    """The authorization code received from the IDP"""
+
+    state: str | None = None
+    """The state parameter for CSRF validation (optional for backward compatibility)"""
+
+
+class OIDCDiscoveryMetadata(BaseModel):
+    """
+    OpenID Provider Metadata as defined in OpenID Connect Discovery 1.0.
+    https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+    """
+
+    issuer: str = Field(
+        ...,
+        description='REQUIRED. URL using the https scheme with no query or fragment components that the OP asserts as its Issuer Identifier. If Issuer discovery is supported, this value MUST be identical to the issuer value returned by WebFinger. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.',
+    )
+
+    authorization_endpoint: str = Field(
+        ...,
+        description="REQUIRED. URL of the OP's OAuth 2.0 Authorization Endpoint. This URL MUST use the https scheme and MAY contain port, path, and query parameter components.",
+    )
+
+    token_endpoint: str = Field(
+        ...,
+        description="URL of the OP's OAuth 2.0 Token Endpoint. This is REQUIRED unless only the Implicit Flow is used. This URL MUST use the https scheme and MAY contain port, path, and query parameter components. Dara relies on the token flow so this is required.",
+    )
+
+    userinfo_endpoint: str | None = Field(
+        default=None,
+        description="RECOMMENDED. URL of the OP's UserInfo Endpoint. This URL MUST use the https scheme and MAY contain port, path, and query parameter components.",
+    )
+
+    jwks_uri: str = Field(
+        ...,
+        description="REQUIRED. URL of the OP's JWK Set document, which MUST use the https scheme. This contains the signing key(s) the RP uses to validate signatures from the OP. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server.",
+    )
+
+    registration_endpoint: str | None = Field(
+        default=None,
+        description="RECOMMENDED. URL of the OP's Dynamic Client Registration Endpoint, which MUST use the https scheme.",
+    )
+
+    scopes_supported: list[str] | None = Field(
+        default=None,
+        description='RECOMMENDED. JSON array containing a list of the OAuth 2.0 scope values that this server supports. The server MUST support the openid scope value. Servers MAY choose not to advertise some supported scope values even when this parameter is used.',
+    )
+
+    response_types_supported: list[str] = Field(
+        ...,
+        description='REQUIRED. JSON array containing a list of the OAuth 2.0 response_type values that this OP supports. Dynamic OpenID Providers MUST support the code, id_token, and the id_token token Response Type values.',
+    )
+
+    response_modes_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the OAuth 2.0 response_mode values that this OP supports. If omitted, the default for Dynamic OpenID Providers is ["query", "fragment"].',
+    )
+
+    grant_types_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the OAuth 2.0 Grant Type values that this OP supports. Dynamic OpenID Providers MUST support the authorization_code and implicit Grant Type values and MAY support other Grant Types. If omitted, the default value is ["authorization_code", "implicit"].',
+    )
+
+    acr_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the Authentication Context Class References that this OP supports.',
+    )
+
+    subject_types_supported: list[str] | None = Field(
+        default_factory=lambda: ['pairwise'],  # default to unique identifiers if not provided
+        description="""
+        REQUIRED. JSON array containing a list of the Subject Identifier types that this OP supports. Valid types include pairwise and public.
+        CONCESSION: Not provided by our internal IDP so marking as optional.
+        """,
+    )
+
+    id_token_signing_alg_values_supported: list[str] = Field(
+        ...,
+        description='REQUIRED. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT. The algorithm RS256 MUST be included. The value none MAY be supported but MUST NOT be used unless the Response Type used returns no ID Token from the Authorization Endpoint.',
+    )
+
+    id_token_encryption_alg_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT.',
+    )
+
+    id_token_encryption_enc_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for the ID Token to encode the Claims in a JWT.',
+    )
+
+    userinfo_signing_alg_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the UserInfo Endpoint to encode the Claims in a JWT. The value none MAY be included.',
+    )
+
+    userinfo_encryption_alg_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the UserInfo Endpoint to encode the Claims in a JWT.',
+    )
+
+    userinfo_encryption_enc_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the UserInfo Endpoint to encode the Claims in a JWT.',
+    )
+
+    request_object_signing_alg_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for Request Objects. These algorithms are used both when the Request Object is passed by value (using the request parameter) and when it is passed by reference (using the request_uri parameter). Servers SHOULD support none and RS256.',
+    )
+
+    request_object_encryption_alg_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference.',
+    )
+
+    request_object_encryption_enc_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference.',
+    )
+
+    token_endpoint_auth_methods_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of Client Authentication methods supported by this Token Endpoint. The options are client_secret_post, client_secret_basic, client_secret_jwt, and private_key_jwt. Other authentication methods MAY be defined by extensions. If omitted, the default is client_secret_basic.',
+    )
+
+    token_endpoint_auth_signing_alg_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the Token Endpoint for the signature on the JWT used to authenticate the Client at the Token Endpoint for the private_key_jwt and client_secret_jwt authentication methods. Servers SHOULD support RS256. The value none MUST NOT be used.',
+    )
+
+    display_values_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the display parameter values that the OpenID Provider supports.',
+    )
+
+    claim_types_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. JSON array containing a list of the Claim Types that the OpenID Provider supports. Values defined by this specification are normal, aggregated, and distributed. If omitted, the implementation supports only normal Claims.',
+    )
+
+    claims_supported: list[str] | None = Field(
+        default=None,
+        description='RECOMMENDED. JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for. Note that for privacy or other reasons, this might not be an exhaustive list.',
+    )
+
+    service_documentation: str | None = Field(
+        default=None,
+        description='OPTIONAL. URL of a page containing human-readable information that developers might want or need to know when using the OpenID Provider. In particular, if the OpenID Provider does not support Dynamic Client Registration, then information on how to register Clients needs to be provided in this documentation.',
+    )
+
+    claims_locales_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. Languages and scripts supported for values in Claims being returned, represented as a JSON array of BCP47 language tag values. Not all languages and scripts are necessarily supported for all Claim values.',
+    )
+
+    ui_locales_supported: list[str] | None = Field(
+        default=None,
+        description='OPTIONAL. Languages and scripts supported for the user interface, represented as a JSON array of BCP47 language tag values.',
+    )
+
+    claims_parameter_supported: bool | None = Field(
+        default=None,
+        description='OPTIONAL. Boolean value specifying whether the OP supports use of the claims parameter, with true indicating support. If omitted, the default value is false.',
+    )
+
+    request_parameter_supported: bool | None = Field(
+        default=None,
+        description='OPTIONAL. Boolean value specifying whether the OP supports use of the request parameter, with true indicating support. If omitted, the default value is false.',
+    )
+
+    request_uri_parameter_supported: bool | None = Field(
+        default=None,
+        description='OPTIONAL. Boolean value specifying whether the OP supports use of the request_uri parameter, with true indicating support. If omitted, the default value is true.',
+    )
+
+    require_request_uri_registration: bool | None = Field(
+        default=None,
+        description='OPTIONAL. Boolean value specifying whether the OP requires any request_uri values used to be pre-registered using the request_uris registration parameter. Pre-registration is REQUIRED when the value is true. If omitted, the default value is false.',
+    )
+
+    op_policy_uri: str | None = Field(
+        default=None,
+        description="OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about the OP's requirements on how the Relying Party can use the data provided by the OP. The registration process SHOULD display this URL to the person registering the Client if it is given.",
+    )
+
+    op_tos_uri: str | None = Field(
+        default=None,
+        description="OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about the OpenID Provider's terms of service. The registration process SHOULD display this URL to the person registering the Client if it is given.",
+    )
+
+    # OpenID Connect Session Management / RP-Initiated Logout fields
+    end_session_endpoint: str | None = Field(
+        default=None,
+        description='OPTIONAL. URL at the OP to which an RP can perform a redirect to request that the End-User be logged out at the OP. This URL MUST use the https scheme and MAY contain port, path, and query parameter components.',
+    )
+
+    check_session_iframe: str | None = Field(
+        default=None,
+        description='OPTIONAL. URL of an OP iframe that supports cross-origin communications for session state information with the RP Client, using the HTML5 postMessage API.',
+    )
+
+    # Allow additional fields as per spec: "Additional OpenID Provider Metadata parameters MAY also be used"
+    model_config = ConfigDict(extra='allow')
+
+
+class IdTokenClaims(BaseModel):
+    """
+    Standard OIDC ID Token claims as defined in OpenID Connect Core 1.0 Section 2.
+    https://openid.net/specs/openid-connect-core-1_0.html#IDToken
+
+    This model allows extra fields for provider-specific claims.
+    Subclass this to add custom claim extraction logic for specific IDPs.
+    """
+
+    # Required claims
+    iss: str = Field(..., description='Issuer Identifier')
+    sub: str = Field(..., description='Subject Identifier - unique identifier for the user')
+    aud: str | list[str] | None = Field(
+        default=None,
+        description="""
+    REQUIRED. Audience(s) that this ID Token is intended for.
+    It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value.
+    It MAY also contain identifiers for other audiences.
+    In the general case, the aud value is an array of case-sensitive strings.
+    In the common special case when there is one audience, the aud value MAY be a single case-sensitive string.
+
+    CONCESSION: Not provided by our internal IDP so marking as optional.
+    """,
+    )
+    exp: int | float = Field(..., description='Expiration time (Unix timestamp)')
+    iat: int | float = Field(..., description='Issued at time (Unix timestamp)')
+
+    # Optional but commonly used claims
+    auth_time: int | None = Field(default=None, description='Time of authentication (Unix timestamp)')
+    nonce: str | None = Field(default=None, description='Nonce value from the authentication request')
+    acr: str | None = Field(default=None, description='Authentication Context Class Reference')
+    amr: list[str] | None = Field(default=None, description='Authentication Methods References')
+    azp: str | None = Field(default=None, description='Authorized party')
+
+    # Standard profile claims (from scope: profile)
+    name: str | None = Field(default=None, description="End-User's full name")
+    given_name: str | None = Field(default=None, description="End-User's given name(s)")
+    family_name: str | None = Field(default=None, description="End-User's surname(s)")
+    middle_name: str | None = Field(default=None, description="End-User's middle name(s)")
+    nickname: str | None = Field(default=None, description="End-User's casual name")
+    preferred_username: str | None = Field(default=None, description="End-User's preferred username")
+    profile: str | None = Field(default=None, description='URL of the End-User profile page')
+    picture: str | None = Field(default=None, description='URL of the End-User profile picture')
+    website: str | None = Field(default=None, description='URL of the End-User web page or blog')
+    gender: str | None = Field(default=None, description="End-User's gender")
+    birthdate: str | None = Field(default=None, description="End-User's birthday (YYYY-MM-DD or YYYY)")
+    zoneinfo: str | None = Field(default=None, description="End-User's time zone (e.g., Europe/Paris)")
+    locale: str | None = Field(default=None, description="End-User's locale (e.g., en-US)")
+    updated_at: int | None = Field(default=None, description='Time the information was last updated (Unix timestamp)')
+
+    # Email claims (from scope: email)
+    email: str | None = Field(default=None, description="End-User's email address")
+    email_verified: bool | None = Field(default=None, description='Whether the email has been verified')
+
+    # Phone claims (from scope: phone)
+    phone_number: str | None = Field(default=None, description="End-User's phone number")
+    phone_number_verified: bool | None = Field(default=None, description='Whether the phone number has been verified')
+
+    # Address claim (from scope: address) - typically a JSON object
+    address: dict | None = Field(default=None, description="End-User's postal address")
+
+    # Groups claim (non-standard but common)
+    groups: list[str] | None = Field(default=None, description='Groups the user belongs to (non-standard claim)')
+
+    # Allow provider-specific claims
+    model_config = ConfigDict(extra='allow')
+
+
+# Expiration time for the state JWT
+STATE_EXPIRATION_MINUTES = 5
+
+
+class StateObject(BaseModel):
+    """
+    State object content used by Dara when sending `state` to the authorization endpoint of the IDP
+    """
+
+    nonce: str = Field(
+        default_factory=lambda: token_urlsafe(16),
+        description='Nonce value',
+    )
+    iat: datetime = Field(
+        default_factory=lambda: datetime.now(tz=timezone.utc),
+        description='Issued at time',
+    )
+    exp: datetime = Field(
+        default_factory=lambda: datetime.now(tz=timezone.utc) + timedelta(minutes=STATE_EXPIRATION_MINUTES),
+        description='Expiration time',
+    )
+    redirect_to: str | None = Field(
+        default=None,
+        description='Optional redirect to URL',
+    )

dara/core/auth/oidc/routes.py

@@ -0,0 +1,147 @@
+"""
+Copyright 2023 Impulse Innovations Limited
+
+
+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.
+"""
+
+from typing import cast
+
+import jwt
+from fastapi import Depends, HTTPException, Response
+
+from dara.core.auth.definitions import (
+    BAD_REQUEST_ERROR,
+    EXPIRED_TOKEN_ERROR,
+    INVALID_TOKEN_ERROR,
+)
+from dara.core.auth.oidc.settings import OIDCSettings, get_oidc_settings
+from dara.core.auth.utils import sign_jwt
+from dara.core.http import post
+from dara.core.logging import dev_logger
+
+from .definitions import REFRESH_TOKEN_COOKIE_NAME, AuthCodeRequestBody
+from .utils import decode_id_token, get_token_from_idp
+
+
+@post('/auth/sso-callback', authenticated=False)
+async def sso_callback(
+    body: AuthCodeRequestBody, response: Response, oidc_settings: OIDCSettings = Depends(get_oidc_settings)
+):
+    """
+    Handle the OIDC authorization callback.
+
+    This endpoint is called after the user authenticates with the IDP. It:
+    1. Validates the state parameter (CSRF protection) if provided
+    2. Exchanges the authorization code for tokens at the IDP's token endpoint
+    3. Verifies the ID token and extracts user information
+    4. Issues a Dara session token and sets the refresh token cookie
+
+    Per OpenID Connect Core 1.0 Section 3.1.2.5 (Authorization Code Flow).
+
+    :param body: Request body containing auth_code and optional state
+    :param response: FastAPI response object (for setting cookies)
+    :param settings: Application settings
+    :return: Token response containing the session token
+    """
+    from dara.core.internal.registries import auth_registry
+
+    from .config import OIDCAuthConfig
+
+    # Verify the app is configured for OIDC
+    auth_config = auth_registry.get('auth_config')
+    if not isinstance(auth_config, OIDCAuthConfig):
+        raise HTTPException(
+            status_code=400,
+            detail=BAD_REQUEST_ERROR('Cannot use sso-callback for non-OIDC auth configuration'),
+        )
+
+    auth_config = cast(OIDCAuthConfig, auth_config)
+
+    # Validate state parameter if provided (CSRF protection)
+    if body.state:
+        try:
+            auth_config.verify_state(body.state)
+        except jwt.ExpiredSignatureError as e:
+            dev_logger.error('State parameter expired', error=e)
+            raise HTTPException(status_code=400, detail=BAD_REQUEST_ERROR('State parameter expired')) from e
+        except jwt.InvalidTokenError as e:
+            dev_logger.error('Invalid state parameter', error=e)
+            raise HTTPException(status_code=400, detail=BAD_REQUEST_ERROR('Invalid state parameter')) from e
+
+    try:
+        # Exchange authorization code for tokens per RFC 6749 Section 4.1.3
+        oidc_tokens = await get_token_from_idp(
+            auth_config,
+            {
+                'grant_type': 'authorization_code',
+                'code': body.auth_code,
+                'redirect_uri': oidc_settings.redirect_uri,
+            },
+        )
+
+        # Ensure we received an ID token
+        if not oidc_tokens.id_token:
+            raise HTTPException(
+                status_code=401,
+                detail=INVALID_TOKEN_ERROR,
+            )
+
+        # Decode and verify the ID token
+        claims = decode_id_token(oidc_tokens.id_token)
+
+        # Fetch userinfo if enabled and we have an access token
+        userinfo = None
+        if oidc_settings.use_userinfo and oidc_tokens.access_token:
+            userinfo = await auth_config.fetch_userinfo(oidc_tokens.access_token)
+
+        # Extract user data from claims (handles both standard OIDC and Causalens identity claim)
+        user_data = auth_config.extract_user_data(claims, userinfo=userinfo)
+
+        # Verify user has access based on groups
+        auth_config.verify_user_access(user_data)
+
+        # Create a Dara session token wrapping the ID token data
+        session_token = sign_jwt(
+            identity_id=user_data.identity_id,
+            identity_name=user_data.identity_name,
+            identity_email=user_data.identity_email,
+            groups=user_data.groups or [],
+            id_token=oidc_tokens.id_token,
+            exp=int(claims.exp),
+        )
+
+        # Set refresh token cookie if provided
+        if oidc_tokens.refresh_token:
+            response.set_cookie(
+                key=REFRESH_TOKEN_COOKIE_NAME,
+                value=oidc_tokens.refresh_token,
+                secure=True,
+                httponly=True,
+                samesite='strict',
+            )
+
+        return {'token': session_token}
+
+    except jwt.ExpiredSignatureError as e:
+        dev_logger.error('Expired Token Signature', error=e)
+        raise HTTPException(status_code=401, detail=EXPIRED_TOKEN_ERROR) from e
+    except jwt.PyJWTError as e:
+        dev_logger.error('Invalid Token', error=e)
+        raise HTTPException(status_code=401, detail=INVALID_TOKEN_ERROR) from e
+    except HTTPException:
+        # Re-raise HTTP exceptions as-is
+        raise
+    except Exception as err:
+        dev_logger.error('Auth Error', error=err)
+        raise HTTPException(status_code=500, detail=BAD_REQUEST_ERROR('Authentication failed')) from err

dara/core/auth/oidc/settings.py

@@ -0,0 +1,60 @@
+import os
+from functools import lru_cache
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class OIDCSettings(BaseSettings):
+    """
+    OIDC-specific settings, prefixed with SSO_.
+    """
+
+    # Required, using field with default=... to have pyright not complain about missing values
+    client_id: str = Field(default=...)
+    client_secret: str = Field(default=...)
+    redirect_uri: str = Field(default=...)
+    groups: str = Field(default=...)
+
+    # Optional
+    issuer_url: str = 'https://login.causalens.com/api/authentication'
+    jwks_lifespan: int = 86400  # 1 day
+    jwt_algo: str = 'ES256'
+    scopes: str = 'openid'
+    verify_audience: bool = False
+    extra_audience: list[str] | None = None
+    allowed_identity_id: str | None = None
+    use_userinfo: bool = False
+    """If True, fetch additional claims from the userinfo endpoint when an access token is available."""
+
+    model_config = SettingsConfigDict(env_file='.env', extra='allow', env_prefix='sso_')
+
+    @model_validator(mode='after')
+    def apply_audience_env_overrides(self):
+        """
+        If SSO_AUDIENCE_CLIENT_ID and SSO_AUDIENCE_CLIENT_SECRET are set,
+        override client_id/client_secret and enable verify_audience (unless explicitly disabled).
+        """
+        # Get directly from environment — pydantic doesn't automatically read arbitrary ones
+        audience_id = os.getenv('SSO_AUDIENCE_CLIENT_ID')
+        audience_secret = os.getenv('SSO_AUDIENCE_CLIENT_SECRET')
+        verify_override = os.getenv('SSO_VERIFY_AUDIENCE')
+
+        if audience_id and audience_secret and (verify_override is None or verify_override.lower() != 'false'):
+            self.client_id = audience_id
+            self.client_secret = audience_secret
+            self.verify_audience = True
+
+        return self
+
+
+@lru_cache
+def get_oidc_settings():
+    """
+    Get a cached instance of the OIDC settings, loading values from the .env if present.
+    """
+    # Test purposes - if DARA_TEST_FLAG is set then override env with .env.test
+    if os.environ.get('DARA_TEST_FLAG', None) is not None:
+        return OIDCSettings(_env_file='.env.test')  # type: ignore
+
+    return OIDCSettings()

dara/core/auth/oidc/utils.py

@@ -0,0 +1,162 @@
+"""
+Copyright 2023 Impulse Innovations Limited
+
+
+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.
+"""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from typing import TYPE_CHECKING
+
+import httpx
+import jwt
+from fastapi import HTTPException
+from pydantic import BaseModel, ConfigDict
+
+from dara.core.auth.definitions import OTHER_AUTH_ERROR
+from dara.core.logging import dev_logger
+
+from .definitions import JWK_CLIENT_REGISTRY_KEY, IdTokenClaims
+from .settings import get_oidc_settings
+
+if TYPE_CHECKING:
+    from .config import OIDCAuthConfig
+
+
+class OIDCTokenResponse(BaseModel):
+    """
+    Token response from the OIDC token endpoint per OIDC Core 1.0 Section 3.1.3.3
+    """
+
+    id_token: str
+
+    access_token: str | None = None
+    """
+    CONCESSION: Not used by Dara so accepting missing token here
+    """
+
+    refresh_token: str | None = None
+
+    token_type: str | None = None
+    """
+    CONCESSION: Not provided by our internal IDP so marking as optional.
+    Normally should be 'Bearer'
+    """
+
+    expires_in: int | None = None
+    scope: str | None = None
+
+    model_config = ConfigDict(extra='allow')
+
+
+def decode_id_token(id_token: str) -> IdTokenClaims:
+    """
+    Decode and verify a JWT ID token received from an OIDC provider.
+
+    Uses the registered PyJWKClient to fetch the signing key and verify the signature.
+
+    :param id_token: The raw JWT ID token string
+    :return: Decoded and validated ID token claims
+    :raises jwt.InvalidTokenError: If the token is invalid or signature verification fails
+    """
+    from dara.core.internal.registries import utils_registry
+
+    jwks_client: jwt.PyJWKClient = utils_registry.get(JWK_CLIENT_REGISTRY_KEY)
+    oidc_settings = get_oidc_settings()
+
+    # Build audience list for verification if enabled
+    audience = None
+    if oidc_settings.verify_audience:
+        audience = [oidc_settings.client_id]
+        if oidc_settings.extra_audience:
+            audience.extend(oidc_settings.extra_audience)
+
+    # Decode and verify the token
+    decoded = jwt.decode(
+        id_token,
+        jwks_client.get_signing_key_from_jwt(id_token).key,
+        algorithms=[oidc_settings.jwt_algo],
+        audience=audience,
+    )
+
+    return IdTokenClaims.model_validate(decoded)
+
+
+def handle_idp_error(response: httpx.Response) -> HTTPException:
+    """
+    Handle an error response from the IDP token endpoint.
+
+    :param response: The HTTP response from the IDP
+    :return: HTTPException to raise
+    """
+    exc = HTTPException(
+        status_code=401,
+        detail=OTHER_AUTH_ERROR('Identity provider authorization failed'),
+    )
+    try:
+        content = response.json()
+    except Exception:
+        content = response.text
+    dev_logger.error(
+        'IDP authorization failed',
+        exc,
+        {'idp_response_content': content, 'idp_response_status': response.status_code},
+    )
+    return exc
+
+
+async def get_token_from_idp(
+    auth_config: OIDCAuthConfig,
+    body: dict,
+) -> OIDCTokenResponse:
+    """
+    Request tokens from the OIDC provider's token endpoint.
+
+    Per RFC 6749 Section 4.1.3 (Authorization Code Grant) and Section 6 (Refreshing an Access Token),
+    the token request is sent to the token_endpoint using POST with application/x-www-form-urlencoded.
+
+    Client authentication uses HTTP Basic auth with client_id:client_secret per RFC 6749 Section 2.3.1.
+
+    :param auth_config: Current OIDC auth config (used to get token_endpoint from discovery)
+    :param body: Request body parameters (grant_type, code/refresh_token, redirect_uri, etc.)
+    :return: Token response containing access_token, id_token, refresh_token, etc.
+    :raises HTTPException: If the IDP returns an error
+    """
+    oidc_settings = get_oidc_settings()
+
+    # Get token endpoint from discovery
+    token_endpoint = auth_config.get_token_endpoint()
+
+    # Build Basic auth header: base64(client_id:client_secret)
+    credentials = f'{oidc_settings.client_id}:{oidc_settings.client_secret}'
+    encoded_credentials = b64encode(credentials.encode()).decode()
+
+    # Make the token request per RFC 6749
+    # Note: Using application/x-www-form-urlencoded as required by spec
+    response = await auth_config.client.post(
+        url=token_endpoint,
+        headers={
+            'Accept': 'application/json',
+            'Authorization': f'Basic {encoded_credentials}',
+            'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        data=body,  # httpx will encode as form data
+        timeout=10,
+    )
+
+    if response.status_code >= 400:
+        raise handle_idp_error(response)
+
+    return OIDCTokenResponse.model_validate(response.json())