Skip to content

Accounts and authorization

See the Auth guide.

Accounts

rn_forge.django.auth.accounts

The default :class:~rn_forge.auth.AccountResolver on Django's user model.

DjangoAccountResolver(policies, *, sync=None)

Links, provisions or rejects external identities as Django users.

An identity already linked on (issuer, subject) resolves to its user. Otherwise a verified email in one of the provider's :attr:~ProviderPolicy.authoritative_domains links to the user with that address (case-insensitively, and only when exactly one matches). Otherwise the provider's jit policy provisions a user, and existing rejects. An unverified email never links and is never stored on a provisioned user. A provider with no policy is rejected.

Parameters:

Name Type Description Default
policies Mapping[str, ProviderPolicy]

The policy of each provider, by provider ID.

required
sync Callable[[AbstractUser, ExternalIdentity], None] | None

Called with the user and the identity at every successful login, inside the transaction, to copy attributes onto the user. It must save what it changes.

None

Link issuer and subject to user, such as a service account.

Raises:

Type Description
IntegrityError

The pair is already linked.

lookup(issuer, subject)

Return the account ID linked to issuer and subject, if any.

resolve(identity)

Return the account ID of identity.

Raises:

Type Description
AccountRejected

The provider has no policy, or the policy refuses the identity.

DjangoAccountStateWriter

The :class:~rn_forge.auth.AccountStateWriter for Django users.

bump_session_version(account_id)

Increase the user's session version and return the new one.

set_active(account_id, active)

Store whether the user may authenticate.

ProviderPolicy(provisioning='existing', email_domains=frozenset(), authoritative_domains=frozenset()) dataclass

How logins from one provider are linked and provisioned.

Attributes:

Name Type Description
provisioning Literal['existing', 'jit']

existing rejects a user with no account; jit creates the account on first login.

email_domains frozenset[str]

With jit, the email domains that may be provisioned. Empty allows any. A non-empty allowlist also requires a verified email.

authoritative_domains frozenset[str]

Email domains for which this provider is authoritative: a verified email in one links to the existing user with that address.

account_session_version(user)

The session version of user; 0 before the first bump.

Models

rn_forge.django.auth.models

Models behind the default account resolver.

AccountState

Bases: Model

The session version of a user; an absent row means 0.

ExternalAccount

Bases: Model

The link from an external (issuer, subject) to a user.

A service account is a link to the user that stands for the client.

Authorization

rn_forge.django.auth.authorization

Authorization for Django accounts: context provider and invalidation signals.

BYPASS_ROLES = ('superuser', 'staff') module-attribute

Roles that grant every permission: superuser for is_superuser and staff for is_staff.

DjangoAuthorizationContextProvider(*, catalog=(), session_version=account_session_version)

An :class:~rn_forge.auth.AuthorizationContextProvider over Django's auth models.

The account ID is the user's primary key as a string. An unknown user, or one with is_active false, resolves to an inactive context with no permissions. Roles are the names of the user's groups. Permissions are the keys (see :func:permission_keys) of the user's own permissions and those of their groups.

A staff or superuser account additionally has the matching role from :data:BYPASS_ROLES, and holds the keys of every Django permission and of catalog, so the bypass shows in the context as a role and a full permission set.

Parameters:

Name Type Description Default
catalog Iterable[str]

Permission keys that exist outside Django's permission table, such as a viewset's orders.read, which the bypass also grants.

()
session_version Callable[[AbstractUser], int]

Returns a user's session version. Defaults to the one :class:~rn_forge.django.auth.accounts.DjangoAccountStateWriter bumps.

account_session_version

resolve(account_id)

Return the current context of the user with primary key account_id.

connect_authorization_signals(cache)

Invalidate cache when the Django models behind a context change.

A change to a user, or to the groups or permissions assigned directly to them, invalidates that account. A change to a group or permission, or to which permissions a group holds, invalidates every account. These are the signals the User, Group and Permission viewsets raise.

Returns:

Type Description
Callable[[], None]

A function that disconnects the receivers.

permission_keys(permission)

The dotted permission keys that a Django permission grants.

Django's default model permissions map to <app_label>.<model>.<action>, lowercase: add to create, change to update, delete to delete and view to both read and list. So inventory.change_stock is inventory.stock.update. Any other permission, such as a custom inventory.adjust_stock, keeps its <app_label>.<codename> as the key.