Skip to content

Identity

rn_forge.auth.identity

Identity-provider contract and the values it exchanges.

A provider takes the framework's native request and returns an :class:ExternalIdentity; everything on the far side of that result is framework-neutral.

ProviderKind = Literal['oidc', 'oauth2', 'password', 'development'] module-attribute

The protocol family of an :class:IdentityProvider.

ExternalIdentity(provider, issuer, subject, email=None, email_verified=False, name=None, picture=None, groups=frozenset(), attributes=dict[str, Any](), auth_time=None, amr=frozenset(), session_ref=None, id_token=None) dataclass

A verified identity asserted by a login provider.

Attributes:

Name Type Description
provider str

Configured provider ID.

issuer str

The OIDC iss, or "local" for a local login.

subject str

The OIDC sub.

email str | None

The email address, if the provider released one.

email_verified bool

Whether the provider verified email.

name str | None

Display name.

picture str | None

Avatar URL.

groups frozenset[str]

Group names the provider asserted.

attributes Mapping[str, Any]

Other mapped claims.

auth_time datetime | None

When the user authenticated.

amr frozenset[str]

How the user authenticated, such as pwd, mfa or hwk.

session_ref str | None

The OIDC sid, used for logout.

id_token str | None

The raw ID token, set only when the provider has RP-initiated logout enabled.

IdentityProvider

Bases: Protocol

A login method, generic over the framework's native request type.

Attributes:

Name Type Description
id str

The configured provider ID.

kind ProviderKind

The protocol family.

begin(request, *, return_to)

Return the redirect (or form) and the transaction to persist.

complete(request, transaction)

Validate the provider's response against transaction.

logout_redirect(session, *, post_logout_redirect)

Return the provider's logout URL, or None for local logout only.

LoginRequest

Bases: Protocol

The part of a framework request that login providers read.

A binding passes its native request when it has these two members, or a small adapter around it when it does not.

Attributes:

Name Type Description
query Mapping[str, str]

The URL query parameters; the provider's callback arrives here.

form Mapping[str, str]

The decoded form fields of a POST body, empty otherwise.

form property

The decoded form fields.

query property

The URL query parameters.

LoginStart(transaction, redirect_url) dataclass

The result of :meth:IdentityProvider.begin.

Attributes:

Name Type Description
transaction LoginTransaction

The transaction to persist.

redirect_url str | None

Where to send the browser, or None when the provider takes a form instead, as password login does.

LoginTransaction(id, provider, return_to, created_at, state=None, nonce=None, code_verifier=None, extra=dict[str, str]()) dataclass

The state of one login in flight, persisted between begin and complete.

Attributes:

Name Type Description
id str

Opaque handle the transaction cookie carries.

provider str

ID of the provider that began the login.

return_to str

Validated path to send the user to after login.

created_at datetime

When the login began.

state str | None

The OAuth 2.0 state value.

nonce str | None

The OIDC nonce value.

code_verifier str | None

The PKCE code verifier.

extra Mapping[str, str]

Provider-specific values.

SessionInfo(account_id, session_version, provider, issuer, external_subject, created_at, expires_at, auth_time=None, amr=frozenset(), session_ref=None, id_token=None) dataclass

The identity content of a login session; it holds no permissions.

Attributes:

Name Type Description
account_id str

The internal account ID.

session_version int

The account's session version at login.

provider str

ID of the provider that authenticated the session.

issuer str

The external identity's issuer.

external_subject str

The external identity's subject.

auth_time datetime | None

When the user authenticated.

amr frozenset[str]

How the user authenticated.

session_ref str | None

The OIDC sid, used for logout.

id_token str | None

The ID token, kept only when RP-initiated logout is enabled.

created_at datetime

When the session started.

expires_at datetime

When the absolute timeout ends the session.