Models¶

Package litestar_auth.models exposes the reference User and OAuthAccount ORM models plus the side-effect-free mixins behind the bundled model family. Names are loaded lazily (PEP 562) when accessed on the package.

Import paths¶

Use Configuration as the canonical ORM setup guide for token bootstrap lifecycle, custom model families, SQLAlchemyUserDatabase, and the supported password-column hook. Use the Custom user + OAuth cookbook when the application owns the user table.

Avoid from litestar_auth.models import User (or the user submodule) in apps that already map table user to a custom model. That import registers the bundled reference mapper and conflicts with an app-owned mapping. Likewise, importing OAuthAccount from litestar_auth.models.oauth only keeps the reference User lazy; when the app owns a different user class, table, or registry, prefer an OAuthAccountMixin subclass that points back at the custom user contract.

import_token_orm_models() remains the canonical explicit helper for bundled token metadata bootstrap and Alembic-style autogenerate. LitestarAuth.on_app_init() now calls the same helper lazily for plugin-managed runtime when bundled DB-token models are active, so no extra import side effect is required only to make the plugin work.

For custom SQLAlchemy models, compose the mixins on your own declarative base instead of copying columns or relationship wiring from the reference classes. Configuration covers the full support matrix and migration notes.

UserModelMixin hook¶

UserModelMixin keeps the runtime attribute contract on hashed_password. When an app-owned user table uses a different SQL column name, set auth_hashed_password_column_name on the custom user class instead of redefining hashed_password = mapped_column(...):

class LegacyUser(UserModelMixin, UserAuthRelationshipMixin, AppUUIDBase):
    __tablename__ = "legacy_user"
    auth_hashed_password_column_name = "password_hash"

BaseUserManager, SQLAlchemyUserDatabase, and JWT password fingerprinting still read and write user.hashed_password; only the SQL column name changes. Direct field redefinition remains compatibility-only for older models that already depend on it.

UserAuthRelationshipMixin hooks¶

UserAuthRelationshipMixin keeps the bundled inverse relationship contract by default: back_populates="user" on access_tokens, refresh_tokens, and oauth_accounts, with SQLAlchemy's normal loader behavior and inferred foreign-key linkage. Override only the narrow class hooks the mixin documents:

• auth_access_token_model, auth_refresh_token_model, auth_oauth_account_model point those inverse relationships at custom mapped classes, or to None when a branch is intentionally omitted.
• auth_token_relationship_lazy forwards one optional lazy= setting to both token collections.
• auth_oauth_account_relationship_lazy forwards one optional lazy= setting to oauth_accounts.
• auth_oauth_account_relationship_foreign_keys forwards one optional foreign_keys= hint to oauth_accounts.

The mixin does not accept arbitrary relationship() kwargs. For behavior outside those hooks, keep an app-owned explicit relationship definition.

Canonical oauth_account shape¶

The library table (bundled OAuthAccount) includes at least:

• id — UUID primary key (from UUIDBase)
• user_id — FK to user.id, not null
• oauth_name — String(100)
• account_id — String(255)
• account_email — String(320)
• access_token — EncryptedString-backed (length 2048), Fernet when a key is configured
• expires_at — integer epoch or null
• refresh_token — optional, same encryption type as access token
• Unique constraint uq_oauth_account_provider_identity on (oauth_name, account_id)

Token encryption uses litestar_auth.oauth_encryption and OAuthConfig.oauth_token_encryption_key (see OAuth guide).

For audit columns (created_at / updated_at), use one mapped class per table; see OAuth guide — audit columns.

42
43
44
45
46
47
48
49
50
51
52

@declared_attr.directive
def __table_args__(cls) -> tuple[UniqueConstraint]:  # noqa: N805, PLW3201
    """Create the provider-identity uniqueness constraint for each subclass.

    Returns:
        The unique constraint tuple for ``(oauth_name, account_id)``.
    """
    constraint_name = cls.auth_provider_identity_constraint_name
    if constraint_name is None:
        constraint_name = f"uq_{cls.__tablename__}_provider_identity"
    return (UniqueConstraint("oauth_name", "account_id", name=constraint_name),)

76
77
78
79
80
81
82
83
84
85
86
87

@declared_attr
def user(cls) -> Mapped[Any]:  # noqa: N805
    """Map the relationship back to the configured user model.

    Returns:
        The relationship descriptor for the configured user model.
    """
    return relationship(
        cls.auth_user_model,
        back_populates=cls.auth_user_back_populates,
        foreign_keys=lambda: [cast("Mapped[Any]", cls.user_id)],
    )

54
55
56
57
58
59
60
61

@declared_attr
def user_id(cls) -> Mapped[uuid.UUID]:  # noqa: N805
    """Map the foreign key to the configured user table.

    Returns:
        The mapped ``user_id`` foreign-key column.
    """
    return mapped_column(ForeignKey(f"{cls.auth_user_table}.id"), nullable=False)

 97
 98
 99
100
101
102
103
104
105
106
107

@declared_attr
def access_tokens(cls):  # noqa: ANN202, N805
    """Map the inverse side of the configured access-token model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when access-token integration is disabled.
    """
    return cls._relationship(
        cls.auth_access_token_model,
        lazy=cls.auth_token_relationship_lazy,
    )

121
122
123
124
125
126
127
128
129
130
131
132

@declared_attr
def oauth_accounts(cls):  # noqa: ANN202, N805
    """Map the inverse side of the configured OAuth-account model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when OAuth-account integration is disabled.
    """
    return cls._relationship(
        cls.auth_oauth_account_model,
        lazy=cls.auth_oauth_account_relationship_lazy,
        foreign_keys=cls.auth_oauth_account_relationship_foreign_keys,
    )

109
110
111
112
113
114
115
116
117
118
119

@declared_attr
def refresh_tokens(cls):  # noqa: ANN202, N805
    """Map the inverse side of the configured refresh-token model when enabled.

    Returns:
        The relationship descriptor, or ``None`` when refresh-token integration is disabled.
    """
    return cls._relationship(
        cls.auth_refresh_token_model,
        lazy=cls.auth_token_relationship_lazy,
    )

43
44
45
46
47
48
49
50
51
52
53

@declared_attr
def hashed_password(cls) -> Mapped[str]:  # noqa: N805
    """Map the password-hash attribute to the configured SQL column name.

    Returns:
        The mapped ``hashed_password`` column.
    """
    column_name = cls.auth_hashed_password_column_name
    if column_name == "hashed_password":
        return mapped_column(String(length=255))
    return mapped_column(column_name, String(length=255))

74
75
76

def __dir__() -> list[str]:
    """Return public model names for discovery."""
    return sorted(__all__)

50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

def __getattr__(name: str) -> object:
    """Load lazy model exports on demand.

    Returns:
        The requested ORM model or mixin.

    Raises:
        AttributeError: If ``name`` is not a public export.
    """
    module_name = {
        "AccessTokenMixin": "litestar_auth.models.mixins",
        "OAuthAccount": "litestar_auth.models.oauth",
        "OAuthAccountMixin": "litestar_auth.models.mixins",
        "RefreshTokenMixin": "litestar_auth.models.mixins",
        "User": "litestar_auth.models.user",
        "UserAuthRelationshipMixin": "litestar_auth.models.mixins",
        "UserModelMixin": "litestar_auth.models.mixins",
    }.get(name)
    if module_name is None:
        msg = f"module {__name__!r} has no attribute {name!r}"
        raise AttributeError(msg)
    return getattr(import_module(module_name), name)

10
11
12
13
14
15
16
17
18
19
20
21

def import_token_orm_models() -> tuple[type[AccessToken], type[RefreshToken]]:
    """Return the bundled token ORM models for explicit and plugin-owned bootstrap.

    This remains the canonical public helper for metadata bootstrap and Alembic-style
    autogenerate flows. ``LitestarAuth.on_app_init()`` also calls it lazily when bundled
    DB-token models are active, so plugin-managed runtime no longer depends on a separate
    app-level import side effect. The helper keeps token-model discovery under
    ``litestar_auth.models`` without importing the reference ``User`` mapper.
    """
    db_models_module = importlib.import_module("litestar_auth.authentication.strategy.db_models")

    return db_models_module.import_token_orm_models()