Skip to content

Authentication sessions

reauth.authentication_session

AuthenticationSession dataclass 

AuthenticationSession(
    id: Any | None,
    token_hash: TokenHash,
    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_hash instance-attribute 

token_hash: TokenHash

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(
    *,
    hash_secret: str,
    factors: set[FactorBase[Any]],
    token_prefix: str = "reauth_as_",
    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.

hash_secret instance-attribute 

hash_secret = hash_secret

factors instance-attribute 

factors = factors

token_prefix instance-attribute 

token_prefix = token_prefix

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).

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(
    authentication_session: AuthenticationSession,
    identity_id: Any,
    factor: FactorBase[Any],
) -> AuthenticationSession

Advance an authentication session by marking a factor as completed.

Parameters:

Name Type Description Default
authentication_session AuthenticationSession

The AuthenticationSession instance to advance.

 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
UnavailableFactorException

If the factor is not available for the session.

complete async 

complete(
    authentication_session: AuthenticationSession,
) -> tuple[typing.Any, list[AuthenticationMethodReference]]

Complete an authentication session and return identity info.

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

Parameters:

Name Type Description Default
authentication_session AuthenticationSession

The session to complete.

 required

Returns:

Type Description
tuple[Any, list[AuthenticationMethodReference]]

A tuple of (identity_id, amr) for creating a user session.

Raises:

Type Description
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.

Implementers should implement this method.

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.

get_by_token_hash abstractmethod async 

get_by_token_hash(
    token_hash: str,
) -> AuthenticationSession | None

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

Implementers should implement this method.

Parameters:

Name Type Description Default
token_hash str

The hash of the token to look up.

 required

Returns:

Type Description
AuthenticationSession | None

The corresponding AuthenticationSession instance, or None if not found.

update abstractmethod async 

update(
    authentication_session: AuthenticationSession,
) -> None

Update an authentication session in the persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
authentication_session AuthenticationSession

The AuthenticationSession instance to update.

 required

delete abstractmethod async 

delete(
    authentication_session: AuthenticationSession,
) -> None

Delete an authentication session from the persistent store.

Implementers should implement this method.

Parameters:

Name Type Description Default
authentication_session AuthenticationSession

The AuthenticationSession instance to delete.

 required