Skip to content

Principal

rn_forge.auth.principal

The verified caller, the access requirement it is checked against, and the default token-claims mapping.

Principal(subject, issuer=None, external_subject=None, scopes=frozenset(), permissions=frozenset(), roles=frozenset(), tenant=None, attributes=dict[str, Any](), claims=dict[str, Any](), mechanism='bearer', auth_time=None, amr=frozenset()) dataclass

Bases: DataclassMixin

The verified caller.

subject is the only required field.

Attributes:

Name Type Description
subject str

The internal account or service-account ID.

issuer str | None

The issuer of the external identity that authenticated, from the session metadata or the verified token.

external_subject str | None

The external identity's subject, from the same source.

scopes frozenset[str]

Delegated scopes from the verified token; empty for a session.

permissions frozenset[str]

Effective permissions: the authorization context's, limited by scopes for a bearer caller (see :func:effective_permissions).

roles frozenset[str]

Role names from the authorization context.

tenant str | None

The tenant, from the authorization context.

attributes Mapping[str, Any]

Inputs to attribute-based rules, from the authorization context.

claims Mapping[str, Any]

Verified token claims, retained for the application's own use; empty for a session.

mechanism Mechanism

How the caller authenticated, set by the authenticator.

auth_time datetime | None

When the caller authenticated, from the session metadata or the verified token.

amr frozenset[str]

Authentication methods used, from the same source.

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

Requirement(any_scope=frozenset(), all_scopes=frozenset(), any_permission=frozenset(), all_permissions=frozenset()) dataclass

A declarative access requirement.

All four sets are ANDed together; within any_* the members are ORed. Permission clauses are checked against :attr:Principal.permissions and scope clauses against :attr:Principal.scopes; scope clauses can only narrow access further. An empty requirement is satisfied by any principal: it means "authenticated", not "denied".

is_satisfied_by(principal)

Return whether principal meets every clause of this requirement.

principal_from_claims(claims, *, mechanism='bearer')

The default mapping from verified token claims to a :class:Principal.

Claims are read as follows:

Principal Claim
subject sub (required)
issuer iss
scopes scope (RFC 8693 §4.2, space-delimited) or scp (string or list)
roles roles (a list)
tenant tid

Any other claim is left in :attr:Principal.claims, which retains every verified claim.

Parameters:

Name Type Description Default
claims Mapping[str, Any]

Claims already verified by the caller.

required
mechanism Mechanism

Recorded on the principal.

'bearer'

Raises:

Type Description
AuthenticationFailed

There is no sub. The detail stays generic.