Skip to main content

Identity-Aware Kernel

Identity is the platform's most distinctive structural decision. Gate is the Identity-Aware Kernel — the hardened ingress layer every request passes through, binding tokens to cryptographically verified identity state and forensic audit attribution at the kernel itself. Identity is not a plugin sitting alongside the four pillars; it is the perimeter every pillar sits behind. This page is the conceptual framing; the API surface covers the call-shapes.

1. Identity model​

A single human has one User identity globally. Organisation and project memberships layer on top:

  • User — the global identity. One human, one row, persists across orgs.
  • Organisation — a billing and administration container. A User may belong to many.
  • Project — the data-isolation unit, scoped within an org. A User's relationship to a project is mediated by a Membership row carrying a role.
  • End-user — for projects whose Gate-issued identities authenticate their own application's customers, a separate identity class (eu_<base62>) carries the project's application-level users. Operator identities (usr_<base62>) and end-user identities never collide.

A User can authenticate through one or many identity providers. Local email/password authentication and federated authentication coexist on the same User row — User.identityProviderId records the primary provider; secondary providers attach as IdentityProviderLink rows.

Project context is established per request, not per session. A signed-in User holds a session that's user-scoped; the active project for any given API call is communicated via the X-K9o-Project header.

2. Two token kinds​

Gate issues two distinct token kinds:

Token kindShapeUseLifetime
Bearer JWTStateless, signed with per-project keys, verifiable from the project's JWKS endpoint without a gateway round-tripSDK + API access1 hour access TTL by default; 30-day refresh TTL for user sessions
Opaque session IDServer-validated on every request; revocable immediatelyConsole cookies onlyIdle 30 minutes / absolute 8 hours by default

The two kinds are not interchangeable. A JWT cannot establish a Console session; an opaque session ID cannot authenticate an SDK call. Bridges between them exist (gate.exchangeSessionForJwt for a Console-launched CLI invocation), but the bridge is explicit.

JWTs default to EdDSA (Ed25519) signatures; RS256 is supported as a per-project alternative for environments whose JWT-validation libraries lack EdDSA support. Refresh tokens are single-use mandatory: replay invalidates the entire refresh chain and forces a fresh sign-in, matching OAuth 2.0 BCP-200 §4.13.2.

3. Sign-in surface​

Sign-in is method-discriminated through a single endpoint:

MethodFlow
EMAIL_PASSWORDLocal password authentication. Argon2id hashing only; no bcrypt fallback.
MAGIC_LINK_REDEEMEmail-delivered single-use link; 15-minute TTL
OTP_REDEEMEmail-delivered 6-digit code; 5-minute TTL
OIDC_CALLBACKOpenID Connect authorization-code flow with PKCE; discovery cached 24h
SAML_CALLBACKSP-initiated and IdP-initiated SSO with XML-Sig assertion validation
OAUTH2_CALLBACKOAuth2 authorization-code flow with PKCE
AD_BINDNative Active Directory / LDAP bind

Native Active Directory and LDAP bridging is supported — the platform binds to the configured directory as the user with the submitted password as the bind credential, surfacing group memberships into the issued JWT's roles claim.

4. Identity providers​

Federated identity providers are first-class platform resources. Each project may carry multiple providers, each typed and configured:

TypeWhat it federates
OIDCOpenID Connect — any provider supporting OIDC discovery
SAMLEnterprise SSO via SAML 2.0
OAUTH2OAuth2 authorization-code flow (social and enterprise)
ACTIVE_DIRECTORYNative AD bind
LDAPNative LDAP bind (OpenLDAP / FreeIPA conventions)

A pre-persistence test-connection probe validates configuration before creating a provider row — useful for migrations from existing identity stacks where misconfigurations are expensive to debug in production. The probe runs the actual TLS handshake, bind credential check, and group fetch for AD/LDAP; the OIDC discovery document fetch + credential validation for OIDC/OAuth2; the assertion-signing certificate validation for SAML.

Group synchronisation runs in one of three modes: on-demand (fetched at sign-in time; live freshness; ~10–50 ms latency cost), scheduled (background poll every 60 minutes; sign-in latency unaffected), or both (live materialisation + scheduled cache warmup).

5. Gate's two consumption paths​

Gate supports two distinct adoption patterns:

PathWhen to chooseWhat you get
StandaloneYou're replacing your current identity vendor without adopting the rest of the platformSovereign Ingress + cryptographically verified tokens + forensic audit attribution + unlimited end-users on paid tiers + full identity-vendor parity
NativeYou're adopting Gate as part of the full Sovereign StackAll of Standalone PLUS automatic data-layer scoping — identity becomes the binding identity for every data query, enforced at the database layer
Standalonereplaces your identity vendorGateExisting data layerstays where it isNativeadopted with the full StackGateidentity scopes every queryKilimanjaro data planeenforced at the database layer
Standalone leaves the data layer where it is; Native binds identity to every data query at the database layer, so scoping comes from infrastructure rather than code discipline.

The Standalone path is a one-API-replacement migration; your existing data layer stays where it is, and Gate handles the auth + JWT issuance + identity verification. The Native path unlocks the structural property that distinguishes Gate from a hosted identity vendor: scoping happens by infrastructure rather than by code discipline, so a developer who forgets to apply a WHERE user_id = ... clause in a query never leaks data — the gateway already enforced it.

Existing customers can start Standalone and move to Native later. The SDK shape is identical; the unlock happens when the project's data plane lives on Kilimanjaro. For the migration mechanics, see the Migration Guide.

6. Multi-factor authentication​

MFA covers two methods:

MethodWhat it covers
TOTPRFC 6238 time-based one-time passwords; SHA-256 default; compatible with standard authenticator apps
WebAuthn / FIDO2Platform authenticators (Touch ID / Windows Hello / Android biometric) and cross-platform security keys

SMS is not supported — NIST SP 800-63B-4 deprecates SMS as a restricted authenticator and SIM-swap risk is material to the threat model Gate is built against. Customers migrating from a vendor with SMS-dominant MFA enrollment should plan a parallel TOTP / WebAuthn enrollment window during the transition.

Recovery codes are mandatory at MFA enrollment — 10 single-use codes that the user records before enrollment completes. A recovery code substitutes for a TOTP / WebAuthn challenge response.

The MFA claim is carried in the JWT (mfa: "verified" | "required" | "not_required") so policy decisions can check it without a gateway round-trip. The IRREVERSIBLE_ACTION_GATE policy family — used for project deletion, custody-mode downgrade, member-role escalation, and similar high-stakes operations — checks mfa: "verified" as a gating condition.

7. Where authentication ends and authorisation begins​

Gate answers "who". The platform's RBAC and JSON-policy layers answer "what they can do". The handoff:

  1. Gate verifies the token, checks MFA, and propagates the caller's identity claims (subject.id, subject.role, subject.orgId, subject.projectId, subject.mfa).
  2. RBAC enforcement (Security pillar) checks the caller's role taxonomy against the endpoint's minimum-role floor — closed enumeration; one of ORG_OWNER / ORG_ADMIN / ORG_BILLING_ADMIN / ORG_MEMBER at the org scope; PROJECT_ADMIN / PROJECT_EDITOR / PROJECT_MEMBER / PROJECT_VIEWER / PROJECT_AUDITOR plus the separate-dimension cuts PROJECT_AUTHOR / PROJECT_ANALYST / PROJECT_END_USER at the project scope.
  3. JSON-policy evaluation (Policy pillar) checks the project's policy graph against the request shape, the caller's claims, and the target resource. A caller with PROJECT_ADMIN is still subject to project policies unless the policy explicitly grants elevated access.
AUTHENTICATIONAUTHORISATION, TWO LAYERSGateanswers whoRBAC enforcementSecurity pillarJSON-policy evaluationPolicy pillarverifies token, checks MFA,propagates identity claimscaller's role taxonomy vsendpoint minimum-role floorpolicy graph vs request shape,caller's claims, target resourceboth layers must permit the call
Gate answers who; RBAC and then JSON-policy answer what the caller can do, and a PROJECT_ADMIN is still subject to project policies.

Authentication is single-layer. Authorisation is two-layer: RBAC first (closed enumeration check), then JSON-policy (project-authored expressions). Both must permit the call.

8. Transactional email — the triple-trigger pattern​

Every transactional-email event ships three first-class triggering paths:

  • gate.send<Event>Email — uses platform-provided email infrastructure (when the project's transactionalEmailProvider is set to 'platform').
  • gate.generate<Event>Link — returns the link / token for the developer's own email infrastructure. Always available regardless of provider setting.
  • auth.<event> webhook — fires for event-driven flows. Always emitted.

The default is 'byo'. Platform-provided email is opt-in. This matches the sovereignty / enterprise posture: the developer controls when, how, and through whose infrastructure their customer's email experience flows.

9. See also​