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: |
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 |
__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
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dict mapping field names to their current values. Nested |
dict[str, Any]
|
dataclasses are recursively converted, respecting |
dict[str, Any]
|
metadata at every level. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the subclass was not decorated with
|
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 |
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 |
TypeError
|
If the subclass was not decorated with
|
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: |
None
|
**kwargs
|
Any
|
Additional keyword arguments forwarded to
:func: |
{}
|
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: |
{}
|
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 |