Skip to content

Login flow

rn_forge.auth.flow

The login flow over a set of providers and a transaction store.

A framework binding mounts :class:LoginFlow at its login and callback routes: it puts LoginStart.transaction.id in the transaction cookie after :meth:LoginFlow.begin, and reads the cookie back for :meth:LoginFlow.complete.

The cookie that binds a callback to the browser that began the login.

CompletedLogin(identity, return_to) dataclass

A verified login and where to send the user next.

Attributes:

Name Type Description
identity ExternalIdentity

The verified identity.

return_to str

The consumed transaction's return_to, validated when the login began.

LoginFailed(code, reason)

Bases: AppException

A login did not complete.

:attr:reason is for logs: it must not reach the user. :attr:code is what the error route receives.

Parameters:

Name Type Description Default
code CallbackError

The callback error code.

required
reason str

Why the login failed.

required

Attributes:

Name Type Description
code CallbackError

The callback error code.

reason

Why the login failed.

check(value, message, *message_args, **kwargs) classmethod

Raise this exception if value is falsy.

Parameters:

Name Type Description Default
value Any

The value to test.

required
message str

Exception message (supports positional format args).

required
*message_args Any

Forwarded to message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

Example::

AppException.check(path.exists(), "Missing file: {}", path, error_code=404)

LoginFlow(providers, transactions, *, return_to_prefixes, ttl=DEFAULT_TRANSACTION_TTL)

Begins and completes logins for the configured providers.

Parameters:

Name Type Description Default
providers Mapping[str, IdentityProvider[RequestT]]

The identity providers, by provider ID.

required
transactions TransactionStore

Holds each login between its redirect and its callback.

required
return_to_prefixes Sequence[str]

Path prefixes a return_to may lie under.

required
ttl timedelta

How long a login may take between its two legs.

DEFAULT_TRANSACTION_TTL

begin(provider_id, request, *, return_to)

Start a login and save its transaction.

Parameters:

Name Type Description Default
provider_id str

The provider to log in with.

required
request RequestT

The framework's native request.

required
return_to str

Where to send the user after login.

required

Returns:

Type Description
LoginStart

The provider's redirect (or form) and the saved transaction; the

LoginStart

caller carries transaction.id in the transaction cookie.

Raises:

Type Description
LoginFailed

The provider is unknown, return_to is not an allowed path, or the provider could not begin.

complete(provider_id, request, *, transaction_id)

Finish a login.

The transaction is consumed whatever the outcome, so a callback works once.

Parameters:

Name Type Description Default
provider_id str

The provider the callback came to.

required
request RequestT

The framework's native request.

required
transaction_id str | None

The ID from the browser's transaction cookie, or None when it sent none.

required

Returns:

Type Description
CompletedLogin

The verified identity and the transaction's return_to.

Raises:

Type Description
LoginFailed

The transaction is missing, expired, already consumed or belongs to another provider, or the provider rejected the response.

Return the single transaction cookie value from raw Cookie headers.

Raises:

Type Description
LoginFailed

More than one transaction cookie is present.