arize-phoenix 9.6.1__tar.gz → 10.0.0__tar.gz

{arize_phoenix-9.6.1 → arize_phoenix-10.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arize-phoenix
-Version: 9.6.1
+Version: 10.0.0
 Summary: AI Observability and Evaluation
 Project-URL: Documentation, https://docs.arize.com/phoenix/
 Project-URL: Issues, https://github.com/Arize-ai/phoenix/issues

{arize_phoenix-9.6.1 → arize_phoenix-10.0.0}/src/phoenix/auth.py

@@ -7,15 +7,16 @@ from enum import Enum, auto
 from hashlib import pbkdf2_hmac
 from typing import Any, Literal, Optional, Protocol
 
+from starlette.datastructures import Secret
 from starlette.responses import Response
 from typing_extensions import TypeVar
 
-from phoenix.config import get_env_phoenix_use_secure_cookies
+from phoenix.config import get_env_cookies_path, get_env_phoenix_use_secure_cookies
 
 ResponseType = TypeVar("ResponseType", bound=Response)
 
 
-def compute_password_hash(*, password: str, salt: bytes) -> bytes:
+def compute_password_hash(*, password: Secret, salt: bytes) -> bytes:
     """
     Salts and hashes a password using PBKDF2, HMAC and SHA256.
 
@@ -26,11 +27,11 @@ def compute_password_hash(*, password: str, salt: bytes) -> bytes:
         bytes: the hashed password
     """
     assert salt
-    password_bytes = password.encode("utf-8")
+    password_bytes = str(password).encode("utf-8")
     return pbkdf2_hmac("sha256", password_bytes, salt, NUM_ITERATIONS)
 
 
-def is_valid_password(*, password: str, salt: bytes, password_hash: bytes) -> bool:
+def is_valid_password(*, password: Secret, salt: bytes, password_hash: bytes) -> bool:
     """
     Determines whether the password is valid by salting and hashing the password
     and comparing against the existing hash value.
@@ -131,6 +132,7 @@ def _set_cookie(
         httponly=True,
         samesite=samesite,
         max_age=int(cookie_max_age.total_seconds()),
+        path=get_env_cookies_path(),
     )
     return response
 

{arize_phoenix-9.6.1 → arize_phoenix-10.0.0}/src/phoenix/config.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import logging
 import os
 import re
@@ -7,16 +9,18 @@ from datetime import timedelta
 from enum import Enum
 from importlib.metadata import version
 from pathlib import Path
-from typing import Any, Optional, Union, cast, overload
+from typing import TYPE_CHECKING, Any, NamedTuple, Optional, Union, cast, overload
 from urllib.parse import quote_plus, urljoin, urlparse
 
 import wrapt
 from email_validator import EmailNotValidError, validate_email
-from starlette.datastructures import URL
+from starlette.datastructures import URL, Secret
 
 from phoenix.utilities.logging import log_a_list
+from phoenix.utilities.re import parse_env_headers
 
-from .utilities.re import parse_env_headers
+if TYPE_CHECKING:
+    from phoenix.server.oauth2 import OAuth2Clients
 
 logger = logging.getLogger(__name__)
 
@@ -138,6 +142,11 @@ ENV_PHOENIX_SERVER_INSTRUMENTATION_OTLP_TRACE_COLLECTOR_GRPC_ENDPOINT = (
 
 # Authentication settings
 ENV_PHOENIX_ENABLE_AUTH = "PHOENIX_ENABLE_AUTH"
+ENV_PHOENIX_DISABLE_BASIC_AUTH = "PHOENIX_DISABLE_BASIC_AUTH"
+"""
+Forbid login via password and disable the creation of local users, which log in via passwords.
+This can be helpful in setups where authentication is handled entirely through OAUTH2.
+"""
 ENV_PHOENIX_DISABLE_RATE_LIMIT = "PHOENIX_DISABLE_RATE_LIMIT"
 ENV_PHOENIX_SECRET = "PHOENIX_SECRET"
 """
@@ -160,6 +169,7 @@ be updated manually in the application.
 """
 ENV_PHOENIX_API_KEY = "PHOENIX_API_KEY"
 ENV_PHOENIX_USE_SECURE_COOKIES = "PHOENIX_USE_SECURE_COOKIES"
+ENV_PHOENIX_COOKIES_PATH = "PHOENIX_COOKIES_PATH"
 ENV_PHOENIX_ACCESS_TOKEN_EXPIRY_MINUTES = "PHOENIX_ACCESS_TOKEN_EXPIRY_MINUTES"
 """
 The duration, in minutes, before access tokens expire.
@@ -555,7 +565,7 @@ def _bool_val(env_var: str, default: Optional[bool] = None) -> Optional[bool]:
     assert (lower := value.lower()) in (
         "true",
         "false",
-    ), f"{env_var} must be set to TRUE or FALSE (case-insensitive)"
+    ), f"{env_var} must be set to TRUE or FALSE (case-insensitive). Got: {value}"
     return lower == "true"
 
 
@@ -573,8 +583,7 @@ def _float_val(env_var: str, default: Optional[float] = None) -> Optional[float]
         return float(value)
     except ValueError:
         raise ValueError(
-            f"Invalid value for environment variable {env_var}: {value}. "
-            f"Value must be a number."
+            f"Invalid value for environment variable {env_var}: {value}. Value must be a number."
         )
 
 
@@ -592,8 +601,7 @@ def _int_val(env_var: str, default: Optional[int] = None) -> Optional[int]:
         return int(value)
     except ValueError:
         raise ValueError(
-            f"Invalid value for environment variable {env_var}: {value}. "
-            f"Value must be an integer."
+            f"Invalid value for environment variable {env_var}: {value}. Value must be an integer."
         )
 
 
@@ -631,6 +639,13 @@ def get_env_enable_auth() -> bool:
     return _bool_val(ENV_PHOENIX_ENABLE_AUTH, False)
 
 
+def get_env_disable_basic_auth() -> bool:
+    """
+    Gets the value of the ENV_PHOENIX_DISABLE_BASIC_AUTH environment variable.
+    """
+    return _bool_val(ENV_PHOENIX_DISABLE_BASIC_AUTH, False)
+
+
 def get_env_disable_rate_limit() -> bool:
     """
     Gets the value of the PHOENIX_DISABLE_RATE_LIMIT environment variable.
@@ -638,29 +653,29 @@ def get_env_disable_rate_limit() -> bool:
     return _bool_val(ENV_PHOENIX_DISABLE_RATE_LIMIT, False)
 
 
-def get_env_phoenix_secret() -> Optional[str]:
+def get_env_phoenix_secret() -> Secret:
     """
     Gets the value of the PHOENIX_SECRET environment variable
     and performs validation.
     """
     phoenix_secret = getenv(ENV_PHOENIX_SECRET)
     if phoenix_secret is None:
-        return None
+        return Secret("")
     from phoenix.auth import REQUIREMENTS_FOR_PHOENIX_SECRET
 
     REQUIREMENTS_FOR_PHOENIX_SECRET.validate(phoenix_secret, "Phoenix secret")
-    return phoenix_secret
+    return Secret(phoenix_secret)
 
 
-def get_env_phoenix_admin_secret() -> Optional[str]:
+def get_env_phoenix_admin_secret() -> Secret:
     """
     Gets the value of the PHOENIX_ADMIN_SECRET environment variable
     and performs validation.
     """
     phoenix_admin_secret = getenv(ENV_PHOENIX_ADMIN_SECRET)
     if phoenix_admin_secret is None:
-        return None
-    if (phoenix_secret := get_env_phoenix_secret()) is None:
+        return Secret("")
+    if not (phoenix_secret := get_env_phoenix_secret()):
         raise ValueError(
             f"`{ENV_PHOENIX_ADMIN_SECRET}` must be not be set without "
             f"setting `{ENV_PHOENIX_SECRET}`."
@@ -668,17 +683,24 @@ def get_env_phoenix_admin_secret() -> Optional[str]:
     from phoenix.auth import REQUIREMENTS_FOR_PHOENIX_SECRET
 
     REQUIREMENTS_FOR_PHOENIX_SECRET.validate(phoenix_admin_secret, "Phoenix secret")
-    if phoenix_admin_secret == phoenix_secret:
+    if phoenix_admin_secret == str(phoenix_secret):
         raise ValueError(
             f"`{ENV_PHOENIX_ADMIN_SECRET}` must be different from `{ENV_PHOENIX_SECRET}`"
         )
-    return phoenix_admin_secret
+    return Secret(phoenix_admin_secret)
 
 
-def get_env_default_admin_initial_password() -> str:
+def get_env_default_admin_initial_password() -> Secret:
     from phoenix.auth import DEFAULT_ADMIN_PASSWORD
 
-    return getenv(ENV_PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD) or DEFAULT_ADMIN_PASSWORD
+    return Secret(getenv(ENV_PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD) or DEFAULT_ADMIN_PASSWORD)
+
+
+def get_env_cookies_path() -> str:
+    """
+    Gets the value of the PHOENIX_COOKIE_PATH environment variable.
+    """
+    return getenv(ENV_PHOENIX_COOKIES_PATH, "/")
 
 
 def get_env_phoenix_use_secure_cookies() -> bool:
@@ -689,7 +711,15 @@ def get_env_phoenix_api_key() -> Optional[str]:
     return getenv(ENV_PHOENIX_API_KEY)
 
 
-def get_env_auth_settings() -> tuple[bool, Optional[str]]:
+class AuthSettings(NamedTuple):
+    enable_auth: bool
+    disable_basic_auth: bool
+    phoenix_secret: Secret
+    phoenix_admin_secret: Secret
+    oauth2_clients: OAuth2Clients
+
+
+def get_env_auth_settings() -> AuthSettings:
     """
     Gets auth settings and performs validation.
     """
@@ -700,7 +730,22 @@ def get_env_auth_settings() -> tuple[bool, Optional[str]]:
             f"`{ENV_PHOENIX_SECRET}` must be set when "
             f"auth is enabled with `{ENV_PHOENIX_ENABLE_AUTH}`"
         )
-    return enable_auth, phoenix_secret
+    phoenix_admin_secret = get_env_phoenix_admin_secret()
+    disable_basic_auth = get_env_disable_basic_auth()
+    from phoenix.server.oauth2 import OAuth2Clients
+
+    oauth2_clients = OAuth2Clients.from_configs(get_env_oauth2_settings())
+    if enable_auth and disable_basic_auth and not oauth2_clients:
+        raise ValueError(
+            "OAuth2 is the only supported auth method but no OAuth2 client configs are provided."
+        )
+    return AuthSettings(
+        enable_auth=enable_auth,
+        disable_basic_auth=disable_basic_auth,
+        phoenix_secret=phoenix_secret,
+        phoenix_admin_secret=phoenix_admin_secret,
+        oauth2_clients=oauth2_clients,
+    )
 
 
 def get_env_password_reset_token_expiry() -> timedelta:
@@ -839,6 +884,8 @@ class OAuth2ClientConfig:
     client_id: str
     client_secret: str
     oidc_config_url: str
+    allow_sign_up: bool
+    auto_login: bool
 
     @classmethod
     def from_env(cls, idp_name: str) -> "OAuth2ClientConfig":
@@ -870,6 +917,8 @@ class OAuth2ClientConfig:
                 f"An OpenID Connect configuration URL must be set for the {idp_name} OAuth2 IDP "
                 f"via the {oidc_config_url_env_var} environment variable"
             )
+        allow_sign_up = get_env_oauth2_allow_sign_up(idp_name)
+        auto_login = get_env_oauth2_auto_login(idp_name)
         parsed_oidc_config_url = urlparse(oidc_config_url)
         is_local_oidc_config_url = parsed_oidc_config_url.hostname in ("localhost", "127.0.0.1")
         if parsed_oidc_config_url.scheme != "https" and not is_local_oidc_config_url:
@@ -886,17 +935,52 @@ class OAuth2ClientConfig:
             client_id=client_id,
             client_secret=client_secret,
             oidc_config_url=oidc_config_url,
+            allow_sign_up=allow_sign_up,
+            auto_login=auto_login,
         )
 
 
 def get_env_oauth2_settings() -> list[OAuth2ClientConfig]:
     """
-    Get OAuth2 settings from environment variables.
-    """
+    Retrieves and validates OAuth2/OpenID Connect (OIDC) identity provider configurations from environment variables.
+
+    This function scans the environment for OAuth2 configuration variables and returns a list of
+    configured identity providers. It supports multiple identity providers simultaneously.
+
+    Environment Variable Pattern:
+        PHOENIX_OAUTH2_{IDP_NAME}_{CONFIG_TYPE}
 
+    Required Environment Variables for each IDP:
+        - PHOENIX_OAUTH2_{IDP_NAME}_CLIENT_ID: The OAuth2 client ID issued by the identity provider
+        - PHOENIX_OAUTH2_{IDP_NAME}_CLIENT_SECRET: The OAuth2 client secret issued by the identity provider
+        - PHOENIX_OAUTH2_{IDP_NAME}_OIDC_CONFIG_URL: The OpenID Connect configuration URL (must be HTTPS)
+
+    Optional Environment Variables:
+        - PHOENIX_OAUTH2_{IDP_NAME}_DISPLAY_NAME: A user-friendly name for the identity provider
+        - PHOENIX_OAUTH2_{IDP_NAME}_ALLOW_SIGN_UP: Whether to allow new user registration (defaults to True)
+        When set to False, the system will check if the user exists in the database by their email address.
+        If the user does not exist or has a password set, they will be redirected to the login page with
+        an error message.
+
+    Returns:
+        list[OAuth2ClientConfig]: A list of configured OAuth2 identity providers, sorted alphabetically by IDP name.
+            Each OAuth2ClientConfig contains the validated configuration for one identity provider.
+
+    Raises:
+        ValueError: If required environment variables are missing or invalid.
+            Specifically, if the OIDC configuration URL is not HTTPS (except for localhost).
+
+    Example:
+        To configure Google as an identity provider, set these environment variables:
+        PHOENIX_OAUTH2_GOOGLE_CLIENT_ID=your_client_id
+        PHOENIX_OAUTH2_GOOGLE_CLIENT_SECRET=your_client_secret
+        PHOENIX_OAUTH2_GOOGLE_OIDC_CONFIG_URL=https://accounts.google.com/.well-known/openid-configuration
+        PHOENIX_OAUTH2_GOOGLE_DISPLAY_NAME=Google (optional)
+        PHOENIX_OAUTH2_GOOGLE_ALLOW_SIGN_UP=true (optional, defaults to true)
+    """  # noqa: E501
     idp_names = set()
     pattern = re.compile(
-        r"^PHOENIX_OAUTH2_(\w+)_(DISPLAY_NAME|CLIENT_ID|CLIENT_SECRET|OIDC_CONFIG_URL)$"
+        r"^PHOENIX_OAUTH2_(\w+)_(DISPLAY_NAME|CLIENT_ID|CLIENT_SECRET|OIDC_CONFIG_URL|ALLOW_SIGN_UP|AUTO_LOGIN)$"  # noqa: E501
     )
     for env_var in os.environ:
         if (match := pattern.match(env_var)) is not None and (idp_name := match.group(1).lower()):
@@ -904,6 +988,47 @@ def get_env_oauth2_settings() -> list[OAuth2ClientConfig]:
     return [OAuth2ClientConfig.from_env(idp_name) for idp_name in sorted(idp_names)]
 
 
+def get_env_oauth2_allow_sign_up(idp_name: str) -> bool:
+    """Retrieves the allow_sign_up setting for a specific OAuth2 identity provider.
+
+    This function determines whether new user registration is allowed for the specified identity provider.
+    When set to False, the system will check if the user exists in the database by their email address.
+    If the user does not exist or has a password set, they will be redirected to the login page with
+    an error message.
+
+    Parameters:
+        idp_name (str): The name of the identity provider (e.g., 'google', 'aws_cognito', 'microsoft_entra_id')
+
+    Returns:
+        bool: True if new user registration is allowed (default), False otherwise
+
+    Environment Variable:
+        PHOENIX_OAUTH2_{IDP_NAME}_ALLOW_SIGN_UP: Controls whether new user registration is allowed (defaults to True if not set)
+    """  # noqa: E501
+    env_var = f"PHOENIX_OAUTH2_{idp_name}_ALLOW_SIGN_UP".upper()
+    return _bool_val(env_var, True)
+
+
+def get_env_oauth2_auto_login(idp_name: str) -> bool:
+    """Retrieves the auto_login setting for a specific OAuth2 identity provider.
+
+    This function determines whether users should be automatically logged in when accessing the OAuth2
+    identity provider's login page. When set to True, users will be redirected to the identity provider's
+    login page without first seeing the application's login page.
+
+    Parameters:
+        idp_name (str): The name of the identity provider (e.g., 'google', 'aws_cognito', 'microsoft_entra_id')
+
+    Returns:
+        bool: True if auto-login is enabled, False otherwise (defaults to False if not set)
+
+    Environment Variable:
+        PHOENIX_OAUTH2_{IDP_NAME}_AUTO_LOGIN: Controls whether auto-login is enabled (defaults to False if not set)
+    """  # noqa: E501
+    env_var = f"PHOENIX_OAUTH2_{idp_name}_AUTO_LOGIN".upper()
+    return _bool_val(env_var, False)
+
+
 PHOENIX_DIR = Path(__file__).resolve().parent
 # Server config
 SERVER_DIR = PHOENIX_DIR / "server"
@@ -1258,7 +1383,7 @@ def get_env_logging_mode() -> LoggingMode:
     except ValueError:
         raise ValueError(
             f"Invalid value `{logging_mode}` for env var `{ENV_LOGGING_MODE}`. "
-            f"Valid values are: {log_a_list([mode.value for mode in LoggingMode],'and')} "
+            f"Valid values are: {log_a_list([mode.value for mode in LoggingMode], 'and')} "
             "(case-insensitive)."
         )
 
@@ -1337,7 +1462,7 @@ def _get_logging_level(env_var: str, default_level: int) -> int:
     if logging_level.upper() not in valid_values:
         raise ValueError(
             f"Invalid value `{logging_level}` for env var `{env_var}`. "
-            f"Valid values are: {log_a_list(valid_values,'and')} (case-insensitive)."
+            f"Valid values are: {log_a_list(valid_values, 'and')} (case-insensitive)."
         )
     return levelNamesMapping[logging_level.upper()]
 

{arize_phoenix-9.6.1 → arize_phoenix-10.0.0}/src/phoenix/db/enums.py

@@ -4,9 +4,8 @@ from enum import Enum
 from sqlalchemy.orm import InstrumentedAttribute
 
 from phoenix.db import models
-from phoenix.db.models import AuthMethod
 
-__all__ = ["AuthMethod", "UserRole", "COLUMN_ENUMS"]
+__all__ = ["UserRole", "COLUMN_ENUMS"]
 
 
 class UserRole(Enum):

{arize_phoenix-9.6.1 → arize_phoenix-10.0.0}/src/phoenix/db/facilitator.py

@@ -26,6 +26,7 @@ from phoenix.auth import (
 from phoenix.config import (
     get_env_admins,
     get_env_default_admin_initial_password,
+    get_env_disable_basic_auth,
 )
 from phoenix.db import models
 from phoenix.db.constants import DEFAULT_PROJECT_TRACE_RETENTION_POLICY_ID
@@ -111,7 +112,7 @@ async def _ensure_user_roles(db: DbSessionFactory) -> None:
         if (system_role := UserRole.SYSTEM.value) not in existing_roles and (
             system_role_id := role_ids.get(system_role)
         ) is not None:
-            system_user = models.User(
+            system_user = models.LocalUser(
                 user_role_id=system_role_id,
                 username=DEFAULT_SYSTEM_USERNAME,
                 email=DEFAULT_SYSTEM_EMAIL,
@@ -128,7 +129,7 @@ async def _ensure_user_roles(db: DbSessionFactory) -> None:
             compute = partial(compute_password_hash, password=password, salt=salt)
             loop = asyncio.get_running_loop()
             hash_ = await loop.run_in_executor(None, compute)
-            admin_user = models.User(
+            admin_user = models.LocalUser(
                 user_role_id=admin_role_id,
                 username=DEFAULT_ADMIN_USERNAME,
                 email=DEFAULT_ADMIN_EMAIL,
@@ -168,6 +169,7 @@ async def _ensure_admins(
     """
     if not (admins := get_env_admins()):
         return
+    disable_basic_auth = get_env_disable_basic_auth()
     async with db() as session:
         existing_emails = set(
             await session.scalars(
@@ -195,16 +197,23 @@ async def _ensure_admins(
             select(models.UserRole.id).filter_by(name=UserRole.ADMIN.value)
         )
         assert admin_role_id is not None, "Admin role not found in database"
+        user: models.User
         for email, username in admins.items():
-            values = dict(
-                user_role_id=admin_role_id,
-                username=username,
-                email=email,
-                password_salt=secrets.token_bytes(DEFAULT_SECRET_LENGTH),
-                password_hash=secrets.token_bytes(DEFAULT_SECRET_LENGTH),
-                reset_password=True,
-            )
-            await session.execute(insert(models.User).values(values))
+            if not disable_basic_auth:
+                user = models.LocalUser(
+                    email=email,
+                    username=username,
+                    password_salt=secrets.token_bytes(DEFAULT_SECRET_LENGTH),
+                    password_hash=secrets.token_bytes(DEFAULT_SECRET_LENGTH),
+                )
+            else:
+                user = models.OAuth2User(
+                    email=email,
+                    username=username,
+                )
+            user.user_role_id = admin_role_id
+            session.add(user)
+        await session.flush()
     if email_sender is None:
         return
     for exc in await gather(

arize_phoenix-10.0.0/src/phoenix/db/migrations/versions/6a88424799fe_update_users_with_auth_method.py

@@ -0,0 +1,179 @@
+"""Add auth_method column to users table and migrate existing authentication data.
+
+This migration:
+1. Adds a new 'auth_method' column to the users table that indicates whether a user
+   authenticates via local password ('LOCAL') or external OAuth2 ('OAUTH2')
+2. Migrates existing authentication data to populate the new column:
+   - Sets 'LOCAL' for users with password_hash
+   - Sets 'OAUTH2' for users with OAuth2 credentials
+3. Adds appropriate constraints to ensure data integrity:
+   - NOT NULL constraint on auth_method
+   - 'valid_auth_method': ensures only 'LOCAL' or 'OAUTH2' values
+   - 'local_auth_has_password_no_oauth': ensures LOCAL users have password credentials and
+     do not have OAuth2 credentials
+   - 'non_local_auth_has_no_password': ensures OAUTH2 users do not have password credentials
+4. Removes legacy constraints that are replaced by the new column:
+   - 'password_hash_and_salt': ensures password_hash and password_salt are consistent
+   - 'exactly_one_auth_method': replaced by auth_method column and its constraints
+   - 'oauth2_client_id_and_user_id': replaced by auth_method column and its constraints
+5. Drops redundant single column indices:
+   - 'ix_users_oauth2_client_id' and 'ix_users_oauth2_user_id' are removed as they are
+     redundant with the unique constraint 'uq_users_oauth2_client_id_oauth2_user_id',
+     which already provides the necessary composite index for lookups
+
+The migration uses batch_alter_table to ensure compatibility with both SQLite and PostgreSQL.
+This approach allows us to:
+- Add the column as nullable initially
+- Update the values based on existing authentication data
+- Make the column NOT NULL after populating
+- Add appropriate constraints
+- Remove legacy constraints
+- Drop redundant indices
+
+The downgrade path:
+1. Recreates the legacy constraints:
+   - 'password_hash_and_salt': ensures password_hash and password_salt are consistent
+   - 'exactly_one_auth_method': ensures exactly one auth method is set
+   - 'oauth2_client_id_and_user_id': ensures OAuth2 credentials are consistent
+2. Removes the auth_method column and its associated constraints
+3. Recreates the single column indices to maintain backward compatibility:
+   - 'ix_users_oauth2_client_id'
+   - 'ix_users_oauth2_user_id'
+
+Revision ID: 6a88424799fe
+Revises: 8a3764fe7f1a
+Create Date: 2025-05-01 08:08:22.700715
+
+"""  # noqa: E501
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "6a88424799fe"
+down_revision: Union[str, None] = "8a3764fe7f1a"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade the database schema to include the auth_method column.
+
+    This function:
+    1. Adds the auth_method column as nullable
+    2. Populates the column based on existing authentication data:
+       - 'LOCAL' for users with password_hash
+       - 'OAUTH2' for users with OAuth2 credentials
+    3. Makes the column NOT NULL after populating
+    4. Adds CHECK constraints to ensure data integrity:
+       - 'valid_auth_method': ensures only 'LOCAL' or 'OAUTH2' values
+       - 'local_auth_has_password_no_oauth': ensures LOCAL users have password credentials and
+          do not have OAuth2 credentials
+       - 'non_local_auth_has_no_password': ensures OAUTH2 users do not have password credentials
+    5. Removes legacy constraints that are replaced by the new column:
+       - 'password_hash_and_salt'
+       - 'exactly_one_auth_method'
+       - 'oauth2_client_id_and_user_id'
+    6. Drops redundant single column indices:
+       - 'ix_users_oauth2_client_id' and 'ix_users_oauth2_user_id' are removed as they are
+         redundant with the unique constraint 'uq_users_oauth2_client_id_oauth2_user_id',
+         which already provides the necessary composite index for lookups
+
+    The implementation uses batch_alter_table for compatibility with both
+    SQLite and PostgreSQL databases.
+
+    Raises:
+        sqlalchemy.exc.SQLAlchemyError: If database operations fail
+    """  # noqa: E501
+    with op.batch_alter_table("users") as batch_op:
+        # For SQLite, first add the column as nullable
+        batch_op.add_column(sa.Column("auth_method", sa.String, nullable=True))
+
+    with op.batch_alter_table("users") as batch_op:
+        batch_op.execute("""
+            UPDATE users
+            SET auth_method = CASE
+            WHEN password_hash IS NOT NULL THEN 'LOCAL' ELSE 'OAUTH2' END
+        """)
+        # Make the column non-nullable
+        batch_op.alter_column("auth_method", nullable=False, existing_nullable=True)
+
+        # Drop both old constraints as they're now redundant
+        batch_op.drop_constraint("password_hash_and_salt", type_="check")
+        batch_op.drop_constraint("exactly_one_auth_method", type_="check")
+        batch_op.drop_constraint("oauth2_client_id_and_user_id", type_="check")
+
+        # Drop redundant single column indices, because a composite index already
+        # exists in the uniqueness constraint for (client_id, user_id)
+        batch_op.drop_index("ix_users_oauth2_client_id")
+        batch_op.drop_index("ix_users_oauth2_user_id")
+
+        # Add CHECK constraint to ensure only valid values are allowed
+        batch_op.create_check_constraint(
+            "valid_auth_method",
+            "auth_method IN ('LOCAL', 'OAUTH2')",
+        )
+        batch_op.create_check_constraint(
+            "local_auth_has_password_no_oauth",
+            "auth_method != 'LOCAL' "
+            "OR (password_hash IS NOT NULL AND password_salt IS NOT NULL "
+            "AND oauth2_client_id IS NULL AND oauth2_user_id IS NULL)",
+        )
+        batch_op.create_check_constraint(
+            "non_local_auth_has_no_password",
+            "auth_method = 'LOCAL' OR (password_hash IS NULL AND password_salt IS NULL)",
+        )
+
+
+def downgrade() -> None:
+    """Downgrade the database schema by removing the auth_method column.
+
+    This function:
+    1. Recreates the legacy constraints that were removed in the upgrade:
+       - 'password_hash_and_salt': ensures password_hash and password_salt are consistent
+       - 'exactly_one_auth_method': ensures exactly one auth method is set
+       - 'oauth2_client_id_and_user_id': ensures OAuth2 credentials are consistent
+    2. Removes the auth_method column and its associated CHECK constraints:
+       - 'non_local_auth_has_no_password'
+       - 'local_auth_has_password_no_oauth'
+       - 'valid_auth_method'
+    3. Recreates the single column indices to maintain backward compatibility:
+       - 'ix_users_oauth2_client_id'
+       - 'ix_users_oauth2_user_id'
+
+    The implementation uses batch_alter_table to ensure compatibility with both
+    SQLite and PostgreSQL databases.
+
+    Raises:
+        sqlalchemy.exc.SQLAlchemyError: If database operations fail
+    """  # noqa: E501
+    # Use batch_alter_table for SQLite compatibility
+    # This ensures the downgrade works on both SQLite and PostgreSQL
+    with op.batch_alter_table("users") as batch_op:
+        # Drop the CHECK constraint and column
+        batch_op.drop_constraint("non_local_auth_has_no_password", type_="check")
+        batch_op.drop_constraint("local_auth_has_password_no_oauth", type_="check")
+        batch_op.drop_constraint("valid_auth_method", type_="check")
+
+        # Recreate single column indices
+        batch_op.create_index("ix_users_oauth2_user_id", ["oauth2_user_id"])
+        batch_op.create_index("ix_users_oauth2_client_id", ["oauth2_client_id"])
+
+        # Recreate both old constraints that were dropped in upgrade
+        batch_op.create_check_constraint(
+            "oauth2_client_id_and_user_id",
+            "(oauth2_client_id IS NULL) = (oauth2_user_id IS NULL)",
+        )
+        batch_op.create_check_constraint(
+            "exactly_one_auth_method",
+            "(password_hash IS NULL) != (oauth2_client_id IS NULL)",
+        )
+        batch_op.create_check_constraint(
+            "password_hash_and_salt",
+            "(password_hash IS NULL) = (password_salt IS NULL)",
+        )
+
+        # Remove added column
+        batch_op.drop_column("auth_method")