Authentication sessions

reauth.authentication_session

AuthenticationSession `dataclass`

AuthenticationSession(
    id: Any | None,
    token_identifier: str,
    token_verifier: str,
    expires_at: int,
    identity_id: Any | None,
    step: int = 0,
    amr: list[AuthenticationMethodReference] = list(),
    used_factors: list[str] = list(),
    context: dict[str, Any] | None = None,
)

id `instance-attribute`

id: Any | None

token_identifier `instance-attribute`

token_identifier: str

token_verifier `instance-attribute`

token_verifier: str

expires_at `instance-attribute`

expires_at: int

identity_id `instance-attribute`

identity_id: Any | None

step `class-attribute` `instance-attribute`

step: int = 0

amr `class-attribute` `instance-attribute`

amr: list[AuthenticationMethodReference] = (
    dataclasses.field(default_factory=list)
)

used_factors `class-attribute` `instance-attribute`

used_factors: list[str] = dataclasses.field(
    default_factory=list
)

context `class-attribute` `instance-attribute`

context: dict[str, Any] | None = None

is_expired

is_expired() -> bool

Check if the session has expired.

Returns:

Type	Description
`bool`	True if the session has expired, False otherwise.

AuthenticationSessionException

AuthenticationSessionException(message: str | None = None)

Bases: ReauthException

Base exception for authentication session errors.

InvalidSessionTokenException

InvalidSessionTokenException(message: str | None = None)

Bases: AuthenticationSessionException

Raised when a token is invalid or does not correspond to any session.

ExpiredSessionException

ExpiredSessionException(message: str | None = None)

Bases: AuthenticationSessionException

Raised when a session has expired.

UnavailableFactorException

UnavailableFactorException(message: str | None = None)

Bases: AuthenticationSessionException

Raised when trying to advance a session with a factor that is not available for the session.

IdentityNotAttachedException

IdentityNotAttachedException(message: str | None = None)

Bases: AuthenticationSessionException

Raised when trying to complete a session without an identity_id.

FactorsRemainingException

FactorsRemainingException(factors: set[FactorBase[Any]])

Bases: AuthenticationSessionException

Raised when trying to complete a session with remaining factors.

Attributes:

Name	Type	Description
`factors`		A set of the remaining factors instances.

factors `instance-attribute`

factors = factors

AuthenticationSessionService

AuthenticationSessionService(
    *,
    token_provider: TokenProvider,
    factors: set[FactorBase[Any]],
    lifetime: timedelta = datetime.timedelta(minutes=15),
)

Bases: ABC

Abstract base class for managing authentication sessions.

An authentication session represents a pre-auth state that can be used to authenticate a user, allowing to manage multi-factor authentication flows.

token_provider `instance-attribute`

token_provider = token_provider

factors `instance-attribute`

factors = factors

lifetime `instance-attribute`

lifetime = lifetime

start `async`

start(**context: Any) -> tuple[str, AuthenticationSession]

Start a fresh authentication session.

Parameters:

Name	Type	Description	Default
`**context`	`Any`	Optional keyword arguments for any additional data to store with the session (e.g., return_to="https://example.com/dashboard").	`{}`

Returns:

Type	Description
`tuple[str, AuthenticationSession]`	A tuple of (token, AuthenticationSession instance).

Raises:

Type	Description
`TokenGenerationException`	If credential generation repeatedly collides.

validate `async`

validate(token: str) -> AuthenticationSession

Validate a token and return the corresponding authentication session.

Parameters:

Name	Type	Description	Default
`token`	`str`	The token to validate.	required

Returns:

Type	Description
`AuthenticationSession`	The corresponding AuthenticationSession instance.

Raises:

Type	Description
`InvalidSessionTokenException`	If the token is invalid or does not correspond to any session.
`ExpiredSessionException`	If the session corresponding to the token has expired.

get_available_factors `async`

get_available_factors(
    authentication_session: AuthenticationSession,
) -> set[FactorBase[typing.Any]]

Get the set of available factors for a given authentication session.

Parameters:

Name	Type	Description	Default
`authentication_session`	`AuthenticationSession`	The AuthenticationSession instance to get available factors for.	required

Returns:

Type	Description
`set[FactorBase[Any]]`	A set of FactorBase instances representing the available factors for the session.

advance `async`

advance(
    token: str, identity_id: Any, factor: FactorBase[Any]
) -> AuthenticationSession

Advance an authentication session by marking a factor as completed.

Load and validate the session before checking factor availability.

Parameters:

Name	Type	Description	Default
`token`	`str`	The authentication session token.	required
`identity_id`	`Any`	The ID of the identity that has completed the factor.	required
`factor`	`FactorBase[Any]`	The FactorBase instance representing the factor that has been completed.	required

Returns:

Type	Description
`AuthenticationSession`	The updated AuthenticationSession instance.

Raises:

Type	Description
`InvalidSessionTokenException`	If the token does not correspond to a session.
`ExpiredSessionException`	If the session has expired.
`UnavailableFactorException`	If the factor is not available for the session.

complete `async`

complete(
    token: str,
) -> tuple[typing.Any, list[AuthenticationMethodReference]]

Complete an authentication session and return identity info.

Loads and validates the session, checks that it is complete (identity attached, no factors remaining), deletes it, and returns the identity_id and AMR list.

Parameters:

Name	Type	Description	Default
`token`	`str`	The authentication session token.	required

Returns:

Type	Description
`tuple[Any, list[AuthenticationMethodReference]]`	A tuple of (identity_id, amr) for creating a user session.

Raises:

Type	Description
`InvalidSessionTokenException`	If the token does not correspond to a session.
`ExpiredSessionException`	If the session has expired.
`IdentityNotAttachedException`	If no identity_id is attached to the session.
`FactorsRemainingException`	If there are still available factors.

insert `abstractmethod` `async`

insert(
    authentication_session: AuthenticationSession,
) -> typing.Any

Insert an authentication session into a persistent store.

Parameters:

Name	Type	Description	Default
`authentication_session`	`AuthenticationSession`	The AuthenticationSession instance to insert.	required

Returns:

Type	Description
`Any`	The ID of the inserted authentication session.

Raises:

Type	Description
`TokenIdentifierCollision`	If the identifier already exists in the store.

Implementation contract

Persist the session, enforce identifier uniqueness and return the record ID. On identifier collision, raise TokenIdentifierCollision without persisting changes and leave the transaction usable for retry. Leave commit and rollback to the caller.

get_by_token_identifier `abstractmethod` `async`

get_by_token_identifier(
    token_identifier: str,
) -> AuthenticationSession | None

Retrieve an authentication session by its token identifier from the persistent store.

Parameters:

Name	Type	Description	Default
`token_identifier`	`str`	The identifier of the token to look up.	required

Returns:

Type	Description
`AuthenticationSession \| None`	The corresponding AuthenticationSession instance, or None if not found.

Implementation contract

Match the supplied token identifier and return the session protected from competing mutations until the caller's transaction ends. Acquire protection before reading. Include expired sessions without validating them. Leave commit and rollback to the caller.

update `abstractmethod` `async`

update(
    authentication_session: AuthenticationSession,
) -> None

Update an authentication session in the persistent store.

Parameters:

Name	Type	Description	Default
`authentication_session`	`AuthenticationSession`	The AuthenticationSession instance to update.	required

Implementation contract

Persist the supplied session's state using its record ID. Use the same transaction that protected the lookup, leaving commit and rollback to the caller.

delete `abstractmethod` `async`

delete(
    authentication_session: AuthenticationSession,
) -> None

Delete an authentication session from the persistent store.

Parameters:

Name	Type	Description	Default
`authentication_session`	`AuthenticationSession`	The AuthenticationSession instance to delete.	required

Implementation contract

Delete the record identified by the supplied session's ID. Use the same transaction that protected the lookup, leaving commit and rollback to the caller.

Authentication sessions

reauth.authentication_session

AuthenticationSession dataclass

id instance-attribute

token_identifier instance-attribute

token_verifier instance-attribute

expires_at instance-attribute

identity_id instance-attribute

step class-attribute instance-attribute

amr class-attribute instance-attribute

used_factors class-attribute instance-attribute

context class-attribute instance-attribute

is_expired

AuthenticationSessionException

InvalidSessionTokenException

ExpiredSessionException

UnavailableFactorException

IdentityNotAttachedException

FactorsRemainingException

factors instance-attribute

AuthenticationSessionService

token_provider instance-attribute

factors instance-attribute

lifetime instance-attribute

start async

validate async

get_available_factors async

advance async

complete async

insert abstractmethod async

get_by_token_identifier abstractmethod async

update abstractmethod async

delete abstractmethod async

AuthenticationSession `dataclass`

id `instance-attribute`

token_identifier `instance-attribute`

token_verifier `instance-attribute`

expires_at `instance-attribute`

identity_id `instance-attribute`

step `class-attribute` `instance-attribute`

amr `class-attribute` `instance-attribute`

used_factors `class-attribute` `instance-attribute`

context `class-attribute` `instance-attribute`

factors `instance-attribute`

token_provider `instance-attribute`

factors `instance-attribute`

lifetime `instance-attribute`

start `async`

validate `async`

get_available_factors `async`

advance `async`

complete `async`

insert `abstractmethod` `async`

get_by_token_identifier `abstractmethod` `async`

update `abstractmethod` `async`

delete `abstractmethod` `async`