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.
TRANSACTION_COOKIE = '__Host-login-tx'
module-attribute
¶
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 |
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 |
()
|
**kwargs
|
Any
|
Forwarded as |
{}
|
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 |
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 |
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
|
required |
Returns:
| Type | Description |
|---|---|
CompletedLogin
|
The verified identity and the transaction's |
Raises:
| Type | Description |
|---|---|
LoginFailed
|
The transaction is missing, expired, already consumed or belongs to another provider, or the provider rejected the response. |
transaction_cookie_value(headers)
¶
Return the single transaction cookie value from raw Cookie headers.
Raises:
| Type | Description |
|---|---|
LoginFailed
|
More than one transaction cookie is present. |