timApp.auth.session package#

Submodules#

timApp.auth.session.model module#

Database models for session management.

class timApp.auth.session.model.UserSession(**kwargs)[source]#

Bases: sqlalchemy.ext.declarative.api.Model

User session. A session is given to the user when they log in.

The session is used to track the user’s login status and login history:

Note

At the moment, the model is only used for logging when timApp.defaultconfig.SESSIONS_ENABLE is set.

expire() → None[source]#: Expires the current user session.

expired#: Whether the user session is expired.

expired_at: datetime.datetime | None#: The time when the session was expired.

logged_in_at#: The time when the user logged in and the session was created.

origin#: Information about the origin of the session. May include user agent and any other information about login state.

session_id#: Unique session ID.

user#: User that owns the session. Relationship to user_id.

user_id#: User ID of the user who owns the session.

timApp.auth.session.routes module#

Routes for managing user sessions.

class timApp.auth.session.routes.ExportFormatOptions(value)[source]#

Bases: enum.Enum

Options for session export format.

CSV = 'csv'#: Export sessions as CSV.

JSON = 'json'#: Export sessions as JSON.

class timApp.auth.session.routes.SessionStateFilterOptions(value)[source]#

Bases: enum.Enum

Options for filtering the sessions by state.

ACTIVE = 'active'#: Only allow active sessions.

ALL = 'all'#: Allow any session state.

EXPIRED = 'expired'#: Only allow expired sessions.

timApp.auth.session.routes.get_all_sessions(state: timApp.auth.session.routes.SessionStateFilterOptions = Field(name='state', type=<enum 'SessionStateFilterOptions'>, default=<SessionStateFilterOptions.ALL: 'all'>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=mappingproxy({'by_value': True}), kw_only=False, _field_type=_FIELD), user: str | None = None, export_format: timApp.auth.session.routes.ExportFormatOptions = Field(name='export_format', type=<enum 'ExportFormatOptions'>, default=<ExportFormatOptions.CSV: 'csv'>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=mappingproxy({'by_value': True, 'data_key': 'format'}), kw_only=False, _field_type=_FIELD)) → flask.wrappers.Response[source]#

Get all sessions information.

Note

This endpoint is only accessible to administrators.

Parameters

state – Session state to filter by.
user – Username to filter by.
export_format – Export format to use.

Returns

User sessions information in the specified format.

timApp.auth.session.routes.get_current_session() → flask.wrappers.Response[source]#

Get the information about the current session.

Returns: A JSON response with the session ID and validity.

timApp.auth.session.routes.invalidate_all() → flask.wrappers.Response[source]#: Invalidate all sessions.

timApp.auth.session.routes.invalidate_remote_session(username: str, session_id: str | None = None, secret: str | None = None) → flask.wrappers.Response[source]#

Invalidate a session.

A validated session will be unexpired while all other sessions will be expired.

Parameters

username – Username to invalidate.
session_id – Session ID to invalidate. If not specified, all sessions will be invalidated.
secret – Right distribution secret (timApp.defaulconfig.DIST_RIGHTS_RECEIVE_SECRET). If not specified, the caller must be an administrator.

Returns

OK response if session was invalidated.

timApp.auth.session.routes.invalidate_session(user: str, session_id: str | None = None) → flask.wrappers.Response[source]#

Invalidate a session.

Note

This endpoint is only accessible to administrators.

Parameters

user – Username to invalidate.
session_id – Session ID to invalidate. If not specified, all sessions will be invalidated.

Returns

OK response.

timApp.auth.session.routes.validate_all() → flask.wrappers.Response[source]#: Validate all latest sessions.

timApp.auth.session.routes.validate_remote_session(username: str, session_id: str | None = None, secret: str | None = None) → flask.wrappers.Response[source]#

Validate a session.

A validated session will be unexpired while all other sessions will be expired.

Parameters

username – Username to validate.
session_id – Session ID to validate. If not specified, the latest session will be validated.
secret – Right distribution secret (timApp.defaulconfig.DIST_RIGHTS_RECEIVE_SECRET). If not specified, the caller must be an administrator.

Returns

OK response if session was validated.

timApp.auth.session.routes.validate_session(user: str, session_id: str | None = None) → flask.wrappers.Response[source]#

Validate a session.

A validated session will be unexpired while all other sessions will be expired.

Note

This endpoint is only accessible to administrators.

Parameters

user – Username to validate.
session_id – Session ID to validate. If not specified, the latest session will be validated.

Returns

OK response.

timApp.auth.session.util module#

Helper functions for managing user sessions.

exception timApp.auth.session.util.SessionExpired[source]#

Bases: Exception

Raised when current user’s session is expired.

timApp.auth.session.util.add_user_session(user: timApp.user.user.User, session_id: str, origin: str) → None[source]#

Add a new session for the given user.

Parameters

user – User to add the session for.
session_id – Session ID to add.
origin – Origin of the session. Origin may contain any information to identify the origin of the session (user agent, endpoint, etc).

timApp.auth.session.util.current_session_id() → str | None[source]#

Get the current session ID of the current user.

Note

The function must be called from within a request context.

Returns: Session ID or None if not logged in or the user is missing session info.

timApp.auth.session.util.distribute_session_verification(action: str, username: str, session_id: str | None, targets: list[str]) → list[str][source]#

Distribute a session verification operation to the specified targets.

Note

The function requires right distribution to be enabled. Session verfication is distributed and verified with timApp.defaultconfig.DIST_RIGHTS_SEND_SECRET and timApp.defaultconfig.DIST_RIGHTS_RECEIVE_SECRET configuration options.

Parameters

action – Action to perform. Usually either “verify” or “invalidate”.
username – Username of the user to verify the session for.
session_id – If specified, verify the specific session ID.
targets – List of targets from timApp.defaultconfig.DIST_RIGHTS_HOSTS to distribute the session verification to.

Returns

List of errors that occurred during distribution.

timApp.auth.session.util.expire_user_session(user: timApp.user.user.User, session_id: str | None) → None[source]#

Expire the given session for the given user.

Users with expired sessions cannot access documents without re-verifying their session.

Parameters

user – User to expire the session for.
session_id – Session ID to expire.

timApp.auth.session.util.has_valid_session(user: Optional[timApp.user.user.User] = None) → bool[source]#

Check if the user has a valid session.

A user is considered to have a valid session if:

Session tracking is enabled (timApp.defaultconfig.SESSIONS_ENABLE).
User is an admin.
The user has a session that is not expired (doesn’t have the logout date set).

Parameters: user – User to check for session validity. If None, the current user is used.
Returns: True if the user has a valid session, False otherwise.

timApp.auth.session.util.invalidate_sessions_for(username: str, session_id: Optional[str] = None) → None[source]#

Invalidate the session for the user.

Parameters

username – Username of the user to invalidate the session for.
session_id – If specified, invalidate the specific session ID. If None, invalidate all sessions.

timApp.auth.session.util.is_allowed_document(path: str) → bool[source]#

Check if the given path is allowed to be accessed despite the session block.

Parameters: path – Path to check.
Returns: True if the path is allowed, False otherwise.

timApp.auth.session.util.session_has_access(i: Union[timApp.item.item.ItemBase, timApp.item.block.Block], user: Optional[timApp.user.user.User] = None) → bool[source]#

Checks if the user’s current session has access to the given item.

Parameters

i – Item or block to check access for.
user – User to check access for.

Returns

True if the user has access and valid session, False otherwise.

timApp.auth.session.util.verify_session_for(username: str, session_id: Optional[str] = None) → None[source]#

Verify that the session is valid for the user and expire all other sessions.

Parameters

username – Username of the user to verify the session for.
session_id – If specified, verify the specific session ID. If None, verify the latest added session.

Module contents#

Module for tracking and managing user sessions.

Note

Right now, the module requires timApp.defaultconfig.SESSIONS_ENABLE option to be enabled.

A user can have one or more sessions. A session contains information about user login information and a unique session ID.

Sessions may also be expired, which allows to block the user from accessing documents until they verify the session again.

TIM documentation

timApp.auth.session package

Contents

timApp.auth.session package#

Submodules#

timApp.auth.session.model module#

timApp.auth.session.routes module#

timApp.auth.session.util module#

Module contents#