ConnectSoft Identity Platform Contracts¶

This page defines the stable integration contracts future implementations must follow. The contracts are intentionally platform-level. Template-specific documentation may add local details, but must not contradict these rules.

Token Claim Contract¶

Claim	Required	Meaning
`iss`	Yes	Authorization Server issuer URI.
`aud`	Yes	Intended API audience, Gateway audience, or service audience.
`sub`	Yes	Stable internal user id or service subject.
`scope`	For access tokens	Space-delimited OAuth scopes.
`role`	When role-based access is used	Internal platform role names.
`tenant_id` / `tid`	For tenant-scoped products	Internal tenant identifier. `tid` is the compact JWT form.
`amr`	When known	Authentication methods, such as `pwd`, `otp`, `fido2`, `external`, `mfa`.
`acr`	When assurance levels are used	Authentication assurance level, such as `loa1`, `loa2`, or platform URNs.
`email`	When profile/email scope allows	Normalized user email.
`name`	When profile scope allows	Display name.
`client_id`	For client/service tokens	OAuth client id.
`jti`	Recommended	Token identifier for audit, replay analysis, and revocation correlation.

Token Usage Rules¶

APIs accept access_token values only.
Frontends use id_token for identity/session context only.
External provider tokens are not valid internal API credentials.
Refresh tokens are never forwarded to APIs.
Service-to-service calls use service access tokens issued by the Authorization Server.
Token claims must be normalized before being used by Gateway or backend services.

API Gateway Policy Contract¶

Gateway route policies are composed from these requirement types:

Requirement	Purpose
Authenticated	Requires a valid platform access token.
Anonymous allowlist	Allows explicitly public routes such as health, register, callback, or password reset initiation.
Scope	Requires one or more OAuth scopes.
Role	Requires one or more internal roles.
Claim	Requires a specific normalized claim.
Tenant	Requires tenant context and rejects ambiguous or spoofed tenant input.
MFA	Requires `amr` or `acr` to prove a sufficient authentication method or assurance level.
Admin	Combines authenticated, role/scope, tenant where applicable, and often MFA.

Example route policy matrix:

Route family	Policy
`GET /api/orders`	`orders.read`
`POST /api/orders`	`orders.write` and tenant required
`/api/identity/admin/*`	`identity.admin` and MFA for sensitive operations
`/api/auth/admin/*`	`auth.admin` and MFA for sensitive operations
`/api/identity/self-service/*`	Authenticated user
`/api/identity/auth/register`	Anonymous allowlist plus rate limiting

Frontend Contract¶

Blazor Shell initiates login and logout.
Shell owns token acquisition or delegates it to a BFF.
Shell exposes shared auth state to microfrontends.
Microfrontends consume auth state and call APIs through Gateway or BFF.
Microfrontends do not store refresh tokens.
Microfrontends handle 401, 403, and mfa_required using shared Shell auth UX.

Authorization Server to Identity Contract¶

The Authorization Server depends on the Identity Service for identity data. The internal contract must support:

credential validation for local login or password grant where enabled;
user claims retrieval for token and UserInfo projection;
MFA status checks;
MFA challenge verification or challenge state confirmation;
external account link resolution;
JIT provisioning for external identities;
profile, role, claim, and tenant membership lookups.

The canonical internal route prefix is:

/api/internal/identity

Gateway to Backend Contract¶

Gateway forwards requests only after it validates the platform access token and route policy. Forwarded context includes:

Authorization: Bearer <access_token> when downstream APIs validate tokens;
trusted tenant header or metadata after Gateway resolves tenant from validated token/context;
correlation id;
trace context;
optional user context headers only when documented and protected from client spoofing.

Public client-provided tenant headers are never trusted directly. Gateway must ignore, reject, or overwrite them.

Backend Contract¶

Backend services must expose or consume:

current user abstraction based on validated token claims;
tenant context abstraction;
domain authorization checks;
audit context containing user, tenant, client, correlation id, and operation;
transport-specific auth for REST, gRPC, GraphQL, and SignalR.

Backends may validate JWTs directly or rely on a Gateway-trusted deployment mode. Direct validation is preferred unless network isolation and service-to-service controls are strong.

Standard Errors¶

Error	HTTP status	Use
`invalid_token`	401	Token missing, malformed, expired, wrong issuer, wrong audience, or invalid signature.
`insufficient_scope`	403	Token is valid but lacks required scope.
`mfa_required`	403	User must complete step-up MFA.
`consent_required`	403 or authorization redirect	User consent is required before token issuance or API access.
`account_link_required`	409 or interactive redirect	External identity must be linked to an internal account.
`tenant_required`	400 or 403	Tenant context is missing or ambiguous.