Skip to content

Identity (authn & authz)

Identity splits into authentication (who is calling — ctx.authn.*) and authorization (what they may do — ctx.authz.*), each a family of small ports. The concepts are in Identity & access and the shipped stack in the authn / OIDC integrations; this page is the port catalog — what each port promises, the dep key it binds under, and how to replace one port without the rest.

Every port is routed by its spec's name: ctx.authn.token_lifecycle(spec) resolves TokenLifecycleDepKey under the route spec.name. A provider is a factory (ctx, spec) -> port. A write accessor hands back a port that refuses any use inside a read-only (QUERY) operation.

Authentication

AuthnSpec declares which credential families a route accepts:

Field Type Default Meaning
name str \| StrEnum required route name — every authn port resolves under it
enabled_methods frozenset[AuthnMethod] {"token"} credential families: password / token / api_key; an empty set is a configuration error, and AuthnPort refuses a family the route does not enable

Ports and dep keys

Accessor ctx.authn.<x>(spec) Port Dep key Write
authn AuthnPort AuthnDepKey
eligibility PrincipalEligibilityPort PrincipalEligibilityDepKey
token_lifecycle TokenLifecyclePort TokenLifecycleDepKey yes
password_lifecycle PasswordLifecyclePort PasswordLifecycleDepKey yes
password_reset PasswordResetPort PasswordResetDepKey yes
api_key_lifecycle ApiKeyLifecyclePort ApiKeyLifecycleDepKey yes
password_account_provisioning PasswordAccountProvisioningPort PasswordAccountProvisioningDepKey yes
principal_deactivation PrincipalDeactivationPort PrincipalDeactivationDepKey yes
event_sink AuthnEventSink AuthnEventSinkDepKey

Six more keys have no accessor. The orchestrator behind AuthnDepKey resolves the first four for its own route, and session issue and revocation resolve the last two:

Port Dep key Resolved by
PasswordVerifierPort · TokenVerifierPort · ApiKeyVerifierPort PasswordVerifierDepKey · TokenVerifierDepKey · ApiKeyVerifierDepKey the orchestrator, one per enabled family, under spec.name
PrincipalResolverPort PrincipalResolverDepKey the orchestrator, under spec.name
RevocationStatesPort RevocationStatesDepKey verification, session issue and revocation, under the route AuthnKernelConfig.revocation_states names (a RevocationStatesSpec)
PrincipalEpochPort PrincipalEpochDepKey session issue and revocation; one store per deployment, unrouted

Verifying a credential

The verify-then-resolve seam. A verifier proves a credential and emits a VerifiedAssertion; the resolver maps it to an AuthnIdentity; the orchestrator runs both and then checks eligibility.

Port Method Notes
AuthnPort authenticate_with_password(credentials) · authenticate_with_token(credentials) · authenticate_with_api_key(credentials) each returns an AuthnResult; a family the route does not enable is refused as authentication
PasswordVerifierPort verify_password(credentials) PasswordCredentials → VerifiedAssertion
TokenVerifierPort verify_token(credentials) AccessTokenCredentials → VerifiedAssertion; the assertion's issuer is what a resolver discriminates on; refresh tokens never reach a verifier
ApiKeyVerifierPort verify_api_key(credentials) ApiKeyCredentials → VerifiedAssertion
PrincipalResolverPort resolve(assertion) VerifiedAssertion → AuthnIdentity — trust the subject as a UUID, derive one from (issuer, subject), or look it up

Credential lifecycle

Port Method Notes
TokenLifecyclePort issue_tokens(identity, *, tenant_id=None) returns IssuedTokens; refuses a delegated identity (delegate_denied). Issue and refresh check eligibility with a locking read, so run them in a transaction
refresh_tokens(refresh_token) rotates the pair; a reused token must revoke its family, then raise RefreshTokenReuseError, whose raise rolls that revocation back inside your transaction: catch it after the transaction ends and call revoke_chain_of_tokens(error.principal_id, error.family_id) in a fresh one, as AuthnRefreshTokens does; within a configured reuse grace a just-rotated token is refused as refresh_superseded and nothing is revoked
revoke_tokens(identity) logout
revoke_tokens_by_refresh_token(refresh_token) logout holding only a refresh token; an unknown, revoked, rotated or expired one revokes nothing and raises nothing
revoke_chain_of_tokens(principal_id, family_id) revoke every live session of one rotation family
PasswordLifecyclePort change_password(identity, current_password, new_password) re-authenticates with the current password first
PasswordResetPort request_reset(login) returns an IssuedPasswordReset carrying the raw token, or None for an unknown or ineligible login; a new reset invalidates the previous one. Keeping the caller's response uniform is the handler's job
reset_password(token, new_password) an invalid, expired or used token is one uniform authentication error; success marks the token used and revokes the principal's sessions (the shipped adapter keeps them only with revoke_sessions_on_reset=False)
ApiKeyLifecyclePort issue_api_key(identity, *, actor_principal_id=None, label=None) · refresh_api_key(credentials) return an IssuedApiKey
list_api_keys(identity) the caller's keys as ApiKeyInfo descriptors, never secrets
revoke_api_key(identity, key_id) · revoke_many_api_keys(identity, key_ids) the caller's own keys
list_principal_api_keys(principal_id) · revoke_principal_api_key(key_id) administrator calls: no identity check, so who may make them is the calling operation's authorization to settle; global lookup, since API-key accounts are not tenant-scoped; revoking an unknown key is not_found
PasswordAccountProvisioningPort register_with_password(principal_id, credentials) create the password account of a known principal id
provision_password_account(operator, principal_id, credentials) the same, on an operator's behalf
issue_password_invite(operator, principal_id) · accept_invite_with_password(invite_token, principal_id, credentials) invite flow; the first returns an IssuedInvite

Principal state and events

Port Method Notes
PrincipalEligibilityPort require_authentication_allowed(principal_id, *, for_update=False) raises when the principal is missing or inactive; for_update takes a row lock held until the caller's transaction ends. Session issue passes it, so on Postgres a concurrent deactivation either waits for the new session and revokes it, or commits first and the issue is refused
PrincipalDeactivationPort deactivate(principal_id) idempotent; cascades logout and closes the password and API-key accounts of every store the application wires; with revocation states wired it must run inside a transaction (authn_revocation_requires_transaction otherwise)
AuthnEventSink record(event) receives an AuthnEvent (AuthnEventKind, principal, login_digest — never the raw login). Optional and best-effort: flows emit through resolve_authn_event_emitter, which treats a missing registration as emission off and a raising sink as a logged warning. ctx.authn.event_sink(spec) raises when none is registered

Revocation fast path

Postgres stays the truth; these cache what a session or API-key lookup read there, so a verification can skip the row. A missing or unreadable state means "read Postgres", never "admitted". Wiring is in Check sessions and API keys from Redis.

Port Method Notes
RevocationStatesPort read(principal_id, key) the principal's epoch and one family (f:<id>) or session (s:<id>) state, with the store's clock, in one read
fill(principal_id, states, *, expire_at_ms) set absent keys only; a write landing at or after expire_at_ms leaves nothing
revoke(principal_id, keys, *, ttl) overwrite with revoked — a revocation always wins
now_ms(principal_id) · raise_epoch(principal_id, epoch, *, expire_at_ms, state=None) the store's clock; keep the larger cached epoch
ApiKeyStatesPort read_api_key(digest) · fill_api_key(digest, state, *, expire_at_ms) · revoke_api_keys(digests, *, ttl) opt-in extension of the same store for API keys; the build refuses a states store that lacks it when API keys verify from cached states
PrincipalEpochPort current(principal_id) unlocked read; a principal with no row has epoch 0
hold(principal_id) · advance(principal_id) issue creates the row if absent and holds the epoch under a share lock; a revocation raises it by one. Both refuse to run outside a transaction. The epoch only rises, and its row is never deleted while a token might carry it

Authorization

AuthzSpec:

Field Type Default Meaning
name str \| StrEnum required route name
tenancy_mode "global" \| "require_invocation_tenant" "global" whether grant resolution is partitioned by the invocation tenant — set require_invocation_tenant in a multi-tenant deployment; it refuses a call with no tenant bound as tenant_required (401), which asks the client to select a tenant, not to refresh its token
enforce_principal_active bool True refuse a decision for a deactivated principal
enforce_delegation_grant bool False a delegated identity (actor set) also needs a recorded delegation grant; enabling it with no delegation port wired is a configuration error

Ports and dep keys

Accessor ctx.authz.<x>(spec) Port Dep key Write
decision AuthzDecisionPort AuthzDecisionDepKey
scope AuthzScopePort AuthzScopeDepKey
grant_query GrantQueryPort GrantQueryDepKey
role_assignment RoleAssignmentPort RoleAssignmentDepKey yes
principal_registry PrincipalRegistryPort PrincipalRegistryDepKey yes
delegation DelegationPort DelegationDepKey
delegation_grant DelegationGrantPort DelegationGrantDepKey yes

A subject below is any of PrincipalRef \| UUID \| AuthnIdentity \| AuthzSubject, and scope is an optional AuthzScope policy partition.

Port Method Notes
AuthzDecisionPort authorize(request) AuthzRequest → AuthzDecision: may this principal run this operation?
AuthzScopePort scope_document(request) AuthzDocumentScopeRequest → AuthzDocumentScope, a query-DSL constraint for list, search and read paths. Scopes the request's subject alone; AuthzDocumentScopeWrap walks a delegation chain and conjoins the answers
authorize_sensitive_resource(request) AuthzSensitiveAccessRequest → bool; a delegated subject passes only when every principal in its chain does
GrantQueryPort resolve_effective_grants(subject, *, scope=None) the subject's EffectiveGrants
RoleAssignmentPort assign_role(subject, role_key, *, scope=None) · revoke_role(…) role_key names a catalog role
list_roles(subject, *, scope=None) frozenset[RoleRef]
PrincipalRegistryPort ensure_principal(principal_id, kind, *, is_active=True) idempotent create-or-return; kind is "user" or "service"
create_principal(kind) · get_principal(principal_id) a new PrincipalRef; a known one, or None
deactivate_principal(principal_id) mark inactive for policy
DelegationPort may_act(actor_id, subject_id, *, scope=None) the pairwise grant check, consulted only when enforce_delegation_grant is set
DelegationGrantPort grant_delegation(actor, subject, *, scope=None) · revoke_delegation(…) grant is idempotent
list_delegators(actor, *, scope=None) the principal ids actor may act for

Replacing one port

Register your factory under the port's key and the route, and leave that route out of the module field that would register the shipped one. Two registrations of one key on one route are refused when the deps merge (Conflicting routed dependencies for '<key>': <route>), so the shipped default and yours never race:

from forze.application.contracts.authn import PasswordLifecycleDepKey
from forze.application.contracts.deps import Deps
from forze.application.execution import DepsRegistry
from forze_identity.authn import AuthnDepsModule

deps = DepsRegistry(
    modules=(
        AuthnDepsModule(
            kernel=kernel,
            authn={"main": frozenset({"password", "token"})},
            token_lifecycle=["main"],  # password_lifecycle unset: that slot is yours
        ),
    ),
    deps=(Deps.routed({PasswordLifecycleDepKey: {"main": build_password_lifecycle}}),),
)

Which field registers each shipped port, and the exceptions to the rule:

Dep key Registered by To replace it
AuthnDepKey AuthnDepsModule.authn register your own orchestrator for a route you leave out of authn
TokenVerifierDepKey · PasswordVerifierDepKey · ApiKeyVerifierDepKey AuthnDepsModule.authn, per enabled family pass token_verifiers / password_verifiers / api_key_verifiers for the route; a token-verifier override also needs a resolvers override
PrincipalResolverDepKey AuthnDepsModule.authn pass resolvers for the route
TokenLifecycleDepKey · PasswordLifecycleDepKey · PasswordResetDepKey · ApiKeyLifecycleDepKey · PasswordAccountProvisioningDepKey · PrincipalDeactivationDepKey the AuthnDepsModule field of the same name leave the route out of that field
PrincipalEligibilityDepKey AuthnDepsModule, for every route it wires on those routes, choose eligibility="policy_principal" or "allow_all"; a second registration conflicts
AuthnEventSinkDepKey AuthnDepsModule.events, for every route it wires leave events unset and register a sink per route, or one unrouted sink for all
RevocationStatesDepKey · PrincipalEpochDepKey RedisDepsModule(revocation_states=…) · PostgresDepsModule(principal_epochs=…) register another store in their place
AuthzDecisionDepKey · AuthzScopeDepKey · GrantQueryDepKey · RoleAssignmentDepKey · PrincipalRegistryDepKey · DelegationDepKey · DelegationGrantDepKey the AuthzDepsModule field named for the accessor (decision, scope, …) leave the route out of that field

Keep the contract obligations above when you replace a port — in particular the refresh reuse signal, the uniform reset error, and the locking eligibility read — since the shipped flows and kits rely on them. forze_mock implements every port on this page for tests.