arize-phoenix 10.0.4__py3-none-any.whl → 12.28.1__py3-none-any.whl

phoenix/server/api/routers/__init__.py

@@ -1,10 +1,10 @@
-from .auth import router as auth_router
+from .auth import create_auth_router
 from .embeddings import create_embeddings_router
 from .oauth2 import router as oauth2_router
 from .v1 import create_v1_router
 
 __all__ = [
-    "auth_router",
+    "create_auth_router",
     "create_embeddings_router",
     "create_v1_router",
     "oauth2_router",

phoenix/server/api/routers/auth.py

@@ -1,21 +1,14 @@
 import asyncio
+import logging
 import secrets
 from datetime import datetime, timedelta, timezone
 from functools import partial
-from pathlib import Path
+from typing import TYPE_CHECKING
 from urllib.parse import urlencode, urlparse, urlunparse
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.orm import joinedload
-from starlette.status import (
-    HTTP_204_NO_CONTENT,
-    HTTP_401_UNAUTHORIZED,
-    HTTP_403_FORBIDDEN,
-    HTTP_404_NOT_FOUND,
-    HTTP_422_UNPROCESSABLE_ENTITY,
-    HTTP_503_SERVICE_UNAVAILABLE,
-)
 
 from phoenix.auth import (
     DEFAULT_SECRET_LENGTH,
@@ -28,6 +21,7 @@ from phoenix.auth import (
     delete_oauth2_state_cookie,
     delete_refresh_token_cookie,
     is_valid_password,
+    sanitize_email,
     set_access_token_cookie,
     set_refresh_token_cookie,
     validate_password_format,
@@ -36,9 +30,9 @@ from phoenix.config import (
     get_base_url,
     get_env_disable_basic_auth,
     get_env_disable_rate_limit,
-    get_env_host_root_path,
 )
 from phoenix.db import models
+from phoenix.server.api.routers.ldap import get_or_create_ldap_user
 from phoenix.server.bearer_auth import PhoenixUser, create_access_and_refresh_tokens
 from phoenix.server.email.types import EmailSender
 from phoenix.server.rate_limiters import ServerRateLimiter, fastapi_ip_rate_limiter
@@ -50,6 +44,12 @@ from phoenix.server.types import (
     TokenStore,
     UserId,
 )
+from phoenix.server.utils import prepend_root_path
+
+if TYPE_CHECKING:
+    from phoenix.server.ldap import LDAPAuthenticator
+
+logger = logging.getLogger(__name__)
 
 rate_limiter = ServerRateLimiter(
     per_second_rate_limit=0.2,
@@ -57,73 +57,92 @@ rate_limiter = ServerRateLimiter(
     partition_seconds=60,
     active_partitions=2,
 )
-login_rate_limiter = fastapi_ip_rate_limiter(
-    rate_limiter,
-    paths=[
+
+
+def create_auth_router(ldap_enabled: bool = False) -> APIRouter:
+    """Create auth router with all authentication endpoints.
+
+    Creates a fresh router instance each time to avoid global state issues
+    (e.g., route accumulation in tests).
+
+    Security: Only registers the /ldap/login endpoint when LDAP is actually configured.
+    This prevents information disclosure and reduces attack surface.
+
+    Args:
+        ldap_enabled: Whether LDAP authentication is configured
+
+    Returns:
+        APIRouter: Authentication router with all endpoints registered
+    """
+    # Build rate limiter paths based on configuration
+    rate_limited_paths = [
         "/auth/login",
         "/auth/logout",
         "/auth/refresh",
         "/auth/password-reset-email",
         "/auth/password-reset",
-    ],
-)
+    ]
+    if ldap_enabled:
+        rate_limited_paths.append("/auth/ldap/login")
+
+    login_rate_limiter = fastapi_ip_rate_limiter(rate_limiter, paths=rate_limited_paths)
+    auth_dependencies = [Depends(login_rate_limiter)] if not get_env_disable_rate_limit() else []
 
-auth_dependencies = [Depends(login_rate_limiter)] if not get_env_disable_rate_limit() else []
-router = APIRouter(prefix="/auth", include_in_schema=False, dependencies=auth_dependencies)
+    router = APIRouter(prefix="/auth", include_in_schema=False, dependencies=auth_dependencies)
 
+    # Register all authentication endpoints
+    router.add_api_route("/login", _login, methods=["POST"])
+    router.add_api_route("/logout", _logout, methods=["GET"])
+    router.add_api_route("/refresh", _refresh_tokens, methods=["POST"])
+    router.add_api_route("/password-reset-email", _initiate_password_reset, methods=["POST"])
+    router.add_api_route("/password-reset", _reset_password, methods=["POST"])
 
-@router.post("/login")
-async def login(request: Request) -> Response:
+    # Conditionally add LDAP endpoint only if configured
+    if ldap_enabled:
+        router.add_api_route("/ldap/login", _ldap_login, methods=["POST"])
+
+    return router
+
+
+async def _login(request: Request) -> Response:
+    """Authenticate user via email/password and return access/refresh tokens."""
     if get_env_disable_basic_auth():
-        raise HTTPException(status_code=HTTP_403_FORBIDDEN)
-    assert isinstance(access_token_expiry := request.app.state.access_token_expiry, timedelta)
-    assert isinstance(refresh_token_expiry := request.app.state.refresh_token_expiry, timedelta)
-    token_store: TokenStore = request.app.state.get_token_store()
+        raise HTTPException(status_code=403)
     data = await request.json()
     email = data.get("email")
     password = data.get("password")
 
     if not email or not password:
-        raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail="Email and password required")
+        raise HTTPException(status_code=401, detail="Email and password required")
+
+    # Sanitize email by trimming and lowercasing
+    email = sanitize_email(email)
 
     async with request.app.state.db() as session:
         user = await session.scalar(
-            select(models.User).filter_by(email=email).options(joinedload(models.User.role))
+            select(models.User)
+            .where(func.lower(models.User.email) == email)
+            .options(joinedload(models.User.role))
         )
         if (
             user is None
             or (password_hash := user.password_hash) is None
             or (salt := user.password_salt) is None
         ):
-            raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail=LOGIN_FAILED_MESSAGE)
+            raise HTTPException(status_code=401, detail=LOGIN_FAILED_MESSAGE)
 
     loop = asyncio.get_running_loop()
     password_is_valid = partial(
         is_valid_password, password=password, salt=salt, password_hash=password_hash
     )
     if not await loop.run_in_executor(None, password_is_valid):
-        raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail=LOGIN_FAILED_MESSAGE)
+        raise HTTPException(status_code=401, detail=LOGIN_FAILED_MESSAGE)
 
-    access_token, refresh_token = await create_access_and_refresh_tokens(
-        token_store=token_store,
-        user=user,
-        access_token_expiry=access_token_expiry,
-        refresh_token_expiry=refresh_token_expiry,
-    )
-    response = Response(status_code=HTTP_204_NO_CONTENT)
-    response = set_access_token_cookie(
-        response=response, access_token=access_token, max_age=access_token_expiry
-    )
-    response = set_refresh_token_cookie(
-        response=response, refresh_token=refresh_token, max_age=refresh_token_expiry
-    )
-    return response
+    return await _create_auth_response(request, user)
 
 
-@router.post("/logout")
-async def logout(
-    request: Request,
-) -> Response:
+async def _logout(request: Request) -> Response:
+    """Log out user by revoking tokens and clearing cookies."""
     token_store: TokenStore = request.app.state.get_token_store()
     user_id = None
     if isinstance(user := request.user, PhoenixUser):
@@ -138,7 +157,9 @@ async def logout(
         user_id = subject
     if user_id:
         await token_store.log_out(user_id)
-    response = Response(status_code=HTTP_204_NO_CONTENT)
+    redirect_path = "/logout" if get_env_disable_basic_auth() else "/login"
+    redirect_url = prepend_root_path(request.scope, redirect_path)
+    response = Response(status_code=302, headers={"Location": redirect_url})
     response = delete_access_token_cookie(response)
     response = delete_refresh_token_cookie(response)
     response = delete_oauth2_state_cookie(response)
@@ -146,12 +167,10 @@ async def logout(
     return response
 
 
-@router.post("/refresh")
-async def refresh_tokens(request: Request) -> Response:
-    assert isinstance(access_token_expiry := request.app.state.access_token_expiry, timedelta)
-    assert isinstance(refresh_token_expiry := request.app.state.refresh_token_expiry, timedelta)
+async def _refresh_tokens(request: Request) -> Response:
+    """Refresh access and refresh tokens."""
     if (refresh_token := request.cookies.get(PHOENIX_REFRESH_TOKEN_COOKIE_NAME)) is None:
-        raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail="Missing refresh token")
+        raise HTTPException(status_code=401, detail="Missing refresh token")
     token_store: TokenStore = request.app.state.get_token_store()
     refresh_token_claims = await token_store.read(Token(refresh_token))
     if (
@@ -161,9 +180,9 @@ async def refresh_tokens(request: Request) -> Response:
         or (user_id := int(refresh_token_claims.subject)) is None
         or (expiration_time := refresh_token_claims.expiration_time) is None
     ):
-        raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail="Invalid refresh token")
-    if expiration_time.timestamp() < datetime.now().timestamp():
-        raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail="Expired refresh token")
+        raise HTTPException(status_code=401, detail="Invalid refresh token")
+    if expiration_time.timestamp() <= datetime.now(timezone.utc).timestamp():
+        raise HTTPException(status_code=401, detail="Expired refresh token")
     await token_store.revoke(refresh_token_id)
 
     if (
@@ -181,30 +200,22 @@ async def refresh_tokens(request: Request) -> Response:
                 select(models.User).filter_by(id=user_id).options(joinedload(models.User.role))
             )
         ) is None:
-            raise HTTPException(status_code=HTTP_404_NOT_FOUND, detail="User not found")
-    access_token, refresh_token = await create_access_and_refresh_tokens(
-        token_store=token_store,
-        user=user,
-        access_token_expiry=access_token_expiry,
-        refresh_token_expiry=refresh_token_expiry,
-    )
-    response = Response(status_code=HTTP_204_NO_CONTENT)
-    response = set_access_token_cookie(
-        response=response, access_token=access_token, max_age=access_token_expiry
-    )
-    response = set_refresh_token_cookie(
-        response=response, refresh_token=refresh_token, max_age=refresh_token_expiry
-    )
-    return response
+            raise HTTPException(status_code=404, detail="User not found")
 
+    return await _create_auth_response(request, user)
 
-@router.post("/password-reset-email")
-async def initiate_password_reset(request: Request) -> Response:
+
+async def _initiate_password_reset(request: Request) -> Response:
+    """Send password reset email to user."""
     if get_env_disable_basic_auth():
-        raise HTTPException(status_code=HTTP_403_FORBIDDEN)
+        raise HTTPException(status_code=403)
     data = await request.json()
     if not (email := data.get("email")):
         raise MISSING_EMAIL
+
+    # Sanitize email by trimming and lowercasing
+    email = sanitize_email(email)
+
     sender: EmailSender = request.app.state.email_sender
     if sender is None:
         raise SMTP_UNAVAILABLE
@@ -212,14 +223,14 @@ async def initiate_password_reset(request: Request) -> Response:
     async with request.app.state.db() as session:
         user = await session.scalar(
             select(models.User)
-            .filter_by(email=email)
+            .where(func.lower(models.User.email) == email)
             .options(
                 joinedload(models.User.password_reset_token).load_only(models.PasswordResetToken.id)
             )
         )
     if user is None or user.auth_method != "LOCAL":
         # Withold privileged information
-        return Response(status_code=HTTP_204_NO_CONTENT)
+        return Response(status_code=204)
     token_store: TokenStore = request.app.state.get_token_store()
     if user.password_reset_token:
         await token_store.revoke(PasswordResetTokenId(user.password_reset_token.id))
@@ -230,18 +241,18 @@ async def initiate_password_reset(request: Request) -> Response:
     )
     token, _ = await token_store.create_password_reset_token(password_reset_token_claims)
     url = urlparse(request.headers.get("referer") or get_base_url())
-    path = Path(get_env_host_root_path()) / "reset-password-with-token"
+    path = prepend_root_path(request.scope, "/reset-password-with-token")
     query_string = urlencode(dict(token=token))
-    components = (url.scheme, url.netloc, path.as_posix(), "", query_string, "")
+    components = (url.scheme, url.netloc, path, "", query_string, "")
     reset_url = urlunparse(components)
     await sender.send_password_reset_email(email, reset_url)
-    return Response(status_code=HTTP_204_NO_CONTENT)
+    return Response(status_code=204)
 
 
-@router.post("/password-reset")
-async def reset_password(request: Request) -> Response:
+async def _reset_password(request: Request) -> Response:
+    """Reset user password using a valid reset token."""
     if get_env_disable_basic_auth():
-        raise HTTPException(status_code=HTTP_403_FORBIDDEN)
+        raise HTTPException(status_code=403)
     data = await request.json()
     if not (password := data.get("password")):
         raise MISSING_PASSWORD
@@ -250,7 +261,7 @@ async def reset_password(request: Request) -> Response:
         not (token := data.get("token"))
         or not isinstance((claims := await token_store.read(token)), PasswordResetTokenClaims)
         or not claims.expiration_time
-        or claims.expiration_time < datetime.now(timezone.utc)
+        or claims.expiration_time <= datetime.now(timezone.utc)
     ):
         raise INVALID_TOKEN
     assert (user_id := claims.subject)
@@ -258,7 +269,7 @@ async def reset_password(request: Request) -> Response:
         user = await session.scalar(select(models.User).filter_by(id=int(user_id)))
     if user is None or user.auth_method != "LOCAL":
         # Withold privileged information
-        return Response(status_code=HTTP_204_NO_CONTENT)
+        return Response(status_code=204)
     validate_password_format(password)
     user.password_salt = secrets.token_bytes(DEFAULT_SECRET_LENGTH)
     loop = asyncio.get_running_loop()
@@ -269,28 +280,83 @@ async def reset_password(request: Request) -> Response:
     async with request.app.state.db() as session:
         session.add(user)
         await session.flush()
-    response = Response(status_code=HTTP_204_NO_CONTENT)
+    response = Response(status_code=204)
     assert (token_id := claims.token_id)
     await token_store.revoke(token_id)
     await token_store.log_out(UserId(user.id))
     return response
 
 
+async def _ldap_login(request: Request) -> Response:
+    """Authenticate user via LDAP and return access/refresh tokens."""
+    # Use cached authenticator instance to avoid re-parsing TLS config on every request
+    authenticator: LDAPAuthenticator | None = getattr(request.app.state, "ldap_authenticator", None)
+
+    if not authenticator:
+        raise HTTPException(
+            status_code=503, detail="LDAP authentication is not configured on this server"
+        )
+
+    data = await request.json()
+    username = data.get("username")
+    password = data.get("password")
+
+    if not username or not password:
+        raise HTTPException(status_code=401, detail="Username and password required")
+
+    # Authenticate against LDAP (reused authenticator, already parsed TLS config)
+    user_info = await authenticator.authenticate(username, password)
+
+    if not user_info:
+        # Generic error message to prevent username enumeration
+        raise HTTPException(status_code=401, detail="Invalid username and/or password")
+
+    # Get or create user in Phoenix database
+    async with request.app.state.db() as session:
+        user = await get_or_create_ldap_user(session, user_info, authenticator.config)
+
+    return await _create_auth_response(request, user)
+
+
+async def _create_auth_response(request: Request, user: models.User) -> Response:
+    """
+    Creates access and refresh tokens for the user and sets them as cookies in the response.
+    """
+    token_store: TokenStore = request.app.state.get_token_store()
+    assert isinstance(access_token_expiry := request.app.state.access_token_expiry, timedelta)
+    assert isinstance(refresh_token_expiry := request.app.state.refresh_token_expiry, timedelta)
+
+    access_token, refresh_token = await create_access_and_refresh_tokens(
+        token_store=token_store,
+        user=user,
+        access_token_expiry=access_token_expiry,
+        refresh_token_expiry=refresh_token_expiry,
+    )
+    response = Response(status_code=204)
+    response = set_access_token_cookie(
+        response=response, access_token=access_token, max_age=access_token_expiry
+    )
+    response = set_refresh_token_cookie(
+        response=response, refresh_token=refresh_token, max_age=refresh_token_expiry
+    )
+    return response
+
+
 LOGIN_FAILED_MESSAGE = "Invalid email and/or password"
 
 MISSING_EMAIL = HTTPException(
-    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+    status_code=422,
     detail="Email required",
 )
 MISSING_PASSWORD = HTTPException(
-    status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+    status_code=422,
     detail="Password required",
 )
 SMTP_UNAVAILABLE = HTTPException(
-    status_code=HTTP_503_SERVICE_UNAVAILABLE,
+    status_code=503,
     detail="SMTP server not configured",
 )
 INVALID_TOKEN = HTTPException(
-    status_code=HTTP_401_UNAUTHORIZED,
+    status_code=401,
     detail="Invalid token",
 )

phoenix/server/api/routers/ldap.py

@@ -0,0 +1,229 @@
+import logging
+import secrets
+from typing import cast
+
+from fastapi import HTTPException
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import joinedload
+
+from phoenix.auth import sanitize_email
+from phoenix.config import LDAPConfig
+from phoenix.db import models
+from phoenix.server.ldap import (
+    LDAP_CLIENT_ID_MARKER,
+    LDAPUserInfo,
+    generate_null_email_marker,
+    is_ldap_user,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def get_or_create_ldap_user(
+    session: AsyncSession,
+    user_info: LDAPUserInfo,
+    ldap_config: LDAPConfig,
+) -> models.User:
+    """
+    Retrieves an existing LDAP user or creates a new one.
+
+    User Identity Strategy:
+        Phoenix identifies LDAP users using a stable identifier. The strategy
+        depends on whether PHOENIX_LDAP_ATTR_UNIQUE_ID is configured:
+
+        1. If PHOENIX_LDAP_ATTR_UNIQUE_ID is set (e.g., "objectGUID" or "entryUUID"):
+           - Stores the immutable LDAP unique ID in oauth2_user_id
+           - Primary lookup by oauth2_user_id, fallback by email
+           - Survives: DN changes, email changes, renames, OU moves, domain consolidation
+           - This is how enterprise IAM systems (Okta, Azure AD Connect) work
+
+        2. Otherwise (default):
+           - oauth2_user_id is NULL (no redundant email storage)
+           - Lookup by email column directly
+           - Survives: DN changes, OU moves, renames
+           - Simple setup for most organizations
+
+    Null Email Marker Mode:
+        When PHOENIX_LDAP_ATTR_EMAIL is "null", the LDAP directory doesn't have
+        email attributes. In this mode:
+        - unique_id is required (enforced at config validation)
+        - Lookup is by unique_id only (no email fallback)
+        - A null email marker is generated: "\\ue000NULL(stopgap){md5(unique_id)}"
+
+    Admin-Provisioned Users:
+        Admins can pre-create users with oauth2_user_id=NULL. On first login,
+        the user is matched by email and oauth2_user_id is populated (if unique_id
+        is configured). Not supported in null email marker mode.
+    """
+    unique_id = user_info.unique_id  # Required when email is None
+
+    # Determine the email to use for lookup and storage
+    # If user_info.email is None, we're in null email marker mode
+    email: str | None = sanitize_email(user_info.email) if user_info.email else None
+
+    # Step 1: Look up user
+    # Strategy depends on whether unique_id is configured
+    user: models.User | None = None
+
+    if unique_id:
+        # Enterprise mode (or null email marker mode): lookup by unique_id first
+        user = await _lookup_by_unique_id(session, unique_id)
+
+        # Fallback: email lookup (handles migration to unique_id)
+        # Skip this in null email marker mode (no real email to look up)
+        if not user and email:
+            user = await _lookup_by_email(session, email)
+            if user:
+                # SECURITY: Only migrate if user has no existing unique_id.
+                # This prevents an email recycling attack where a new user with
+                # a recycled email address could hijack an old user's account.
+                #
+                # Scenario without this check:
+                #   1. User A leaves company (DB: email=john@corp.com, uuid=UUID-A)
+                #   2. User B joins with recycled email (LDAP: email=john@corp.com, uuid=UUID-B)
+                #   3. User B logs in, email lookup finds User A, UUID-B overwrites UUID-A
+                #   4. User B now has access to User A's data!
+                #
+                # With this check:
+                #   - User A already has uuid=UUID-A, so no migration happens
+                #   - User B is rejected (403) - admin must resolve the conflict
+                #   - Note: We can't create a new user because email is unique in DB
+                if user.oauth2_user_id is None:
+                    user.oauth2_user_id = unique_id
+                elif user.oauth2_user_id.lower() != unique_id.lower():
+                    # Email matches but unique_id differs - this is a DIFFERENT person
+                    # (e.g., email recycled to new employee).
+                    #
+                    # We cannot create a new user because email is unique in the database.
+                    # This requires admin intervention to resolve (e.g., delete/rename the
+                    # old account, or update the old account's unique_id).
+                    logger.error(
+                        f"LDAP account conflict: user_id={user.id} has different unique_id. "
+                        f"Admin must resolve (delete old account or update unique_id)."
+                    )
+                    raise HTTPException(
+                        status_code=401,
+                        detail="Invalid username and/or password",
+                    )
+                else:
+                    # Same unique_id (case-insensitive match) - normalize case in DB
+                    if user.oauth2_user_id != unique_id:
+                        user.oauth2_user_id = unique_id
+    elif email:
+        # Simple mode: lookup by email only (oauth2_user_id is NULL)
+        user = await _lookup_by_email(session, email)
+    # else: neither unique_id nor email - this shouldn't happen (config validation prevents it)
+
+    # Step 2: Validate role exists
+    role = await session.scalar(
+        select(models.UserRole).where(models.UserRole.name == user_info.role)
+    )
+    if not role:
+        raise HTTPException(
+            status_code=500,
+            detail="Role not found in database",
+        )
+
+    # Step 3: Update existing user attributes
+    if user:
+        # Sync email on every login (email may have changed in LDAP)
+        if email and user.email != email:
+            user.email = email
+
+        # Note: Do NOT sync username - it should remain stable
+        # Updating username could cause collisions if displayName changes in LDAP
+
+        # Update role if it changed
+        if user.role.name != role.name:
+            user.role = role
+        return user
+
+    # Step 4: Create new user (if sign-up is allowed)
+    if not ldap_config.allow_sign_up:
+        logger.info("LDAP user attempted to sign up but sign-up is not allowed")
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid username and/or password",
+        )
+
+    # Determine the email to store in the database
+    if email:
+        db_email = email
+        # Security: Check if email already exists with different auth method
+        existing_user = await session.scalar(
+            select(models.User).where(func.lower(models.User.email) == email.lower())
+        )
+        if existing_user and not is_ldap_user(existing_user.oauth2_client_id):
+            logger.error(
+                "Email already exists with different auth method: %s", existing_user.auth_method
+            )
+            raise HTTPException(
+                status_code=401,
+                detail="Invalid username and/or password",
+            )
+    else:
+        # Null email marker mode: generate deterministic marker from unique_id
+        # unique_id is guaranteed to be set (config validation ensures this)
+        if not unique_id:
+            raise ValueError("unique_id required when email is None")
+        db_email = generate_null_email_marker(unique_id)
+
+    # Username strategy: Try displayName first (user-friendly), handle collisions gracefully
+    username = user_info.display_name
+    existing_username = await session.scalar(
+        select(models.User).where(models.User.username == username)
+    )
+    if existing_username:
+        # Collision detected - append short suffix to make unique
+        username = f"{user_info.display_name} ({secrets.token_hex(3)})"
+
+    user = models.User(
+        email=db_email,
+        username=username,
+        role=role,
+        reset_password=False,
+        auth_method="OAUTH2",  # TODO: change to LDAP in future db migration
+        oauth2_client_id=LDAP_CLIENT_ID_MARKER,
+        oauth2_user_id=unique_id,  # None if unique_id not configured (use email column)
+    )
+    session.add(user)
+    return user
+
+
+async def _lookup_by_unique_id(session: AsyncSession, unique_id: str) -> models.User | None:
+    """Look up LDAP user by immutable unique ID (objectGUID, entryUUID, etc.).
+
+    Uses case-insensitive comparison because:
+    - UUIDs are case-insensitive per RFC 4122
+    - Older versions may have stored uppercase UUIDs
+    - Current code normalizes to lowercase
+
+    This ensures users aren't locked out due to case differences.
+    """
+    return cast(
+        models.User | None,
+        await session.scalar(
+            select(models.User)
+            .where(models.User.oauth2_client_id == LDAP_CLIENT_ID_MARKER)
+            .where(func.lower(models.User.oauth2_user_id) == unique_id.lower())
+            .options(joinedload(models.User.role))
+        ),
+    )
+
+
+async def _lookup_by_email(session: AsyncSession, email: str) -> models.User | None:
+    """Look up LDAP user by email (case-insensitive).
+
+    Note: Both sides of the comparison are lowercased to ensure consistent
+    matching regardless of what sanitize_email() does to the input.
+    """
+    return cast(
+        models.User | None,
+        await session.scalar(
+            select(models.User)
+            .where(models.User.oauth2_client_id == LDAP_CLIENT_ID_MARKER)
+            .where(func.lower(models.User.email) == email.lower())
+            .options(joinedload(models.User.role))
+        ),
+    )