Identity

The identity layer provides three things: a way to issue and verify cryptographic identities (PKI), a way to store and distribute secrets safely (secrets management), and a way to authenticate humans and services using federated identity (authentication). These are distinct problems, and keeping them separate makes each easier to secure.

Identity is layer 4 in the stack: it depends on compute, networking and storage, and everything above it depends on identity. Certificate issuance needs a running certificate authority, secrets management needs a running secrets manager, and federated login needs a running identity provider. The identity layer must therefore be highly available and well backed up; if it is down, services that need it at startup cannot start.

Status: the open standards are chosen (X.509, ACME, OIDC / OAuth 2.0, SAML 2.0, SCIM, SPIFFE). The software that implements each function is under evaluation; this page sets out the requirements each candidate must meet, and each choice will be documented with its reasoning.

Identity is not authentication PKI establishes that a certificate was issued by a trusted CA. Secrets management stores credentials. Authentication (OIDC, OAuth2) verifies who is making a request. These work together, but they are separate systems with separate failure modes.

PKI & Certificates

Overview

Public Key Infrastructure (PKI) is the system by which cryptographic identities are established and verified. A Certificate Authority (CA) issues signed certificates that assert "this public key belongs to this entity." Anyone who trusts the CA can verify a certificate's authenticity without contacting the CA directly — the signature is mathematically verifiable from the CA's public key alone.

In an infrastructure context, TLS certificates are the primary use case: a service presents a certificate proving its identity when a client connects, and the client verifies it against a trusted CA. With mTLS, the client also presents a certificate that the service verifies. The CA's trustworthiness is therefore the root of all TLS security in the system.

⚠  PKI concepts deep dive and certificate lifecycle management documentation in progress.

Architecture

A production PKI uses at minimum a two-tier hierarchy: an offline root CA and an online intermediate CA. The root CA's private key is kept offline (air-gapped, HSM-stored) and only used to sign intermediate CA certificates. The intermediate CA is the one services interact with day-to-day for certificate issuance.

If the intermediate CA is compromised, it can be revoked with the root CA and replaced — without needing to replace every certificate in the system immediately. If the root CA were online and compromised, every certificate in the system would need to be replaced and every client would need to update its trust store. The offline root CA is essential, not optional.

The intended direction is short-lived certificates wherever possible. A certificate valid for hours or a few days, renewed automatically via ACME (RFC 8555), limits how long a stolen key is useful and reduces reliance on revocation lists (CRL) and OCSP. ACME is the same protocol public certificate authorities use for automated issuance.

⚠  Root CA offline ceremony, intermediate CA design, certificate lifetimes, and SSH certificate documentation in progress.

Requirements & standards

Internal certificate authority

The internal CA software is under evaluation. Candidates are assessed against these requirements:

  • Issues X.509 certificates from an intermediate CA chained to an offline root.
  • Speaks ACME (RFC 8555), so any ACME-capable client or proxy can enrol and renew against an internal endpoint instead of a public CA.
  • Supports short certificate lifetimes and automated renewal at scale.
  • Offers a bootstrap path for workloads that cannot use ACME challenges, such as OIDC-based or token-based enrolment.
  • Can act as an SSH certificate authority, issuing short-lived SSH certificates in place of distributed authorized_keys files.
  • Can issue workload identities compatible with SPIFFE / SVID for mTLS between services, including in Kubernetes.
  • Keeps the CA key in an HSM or equivalent protected key store, with audit logging of every issuance.
⚠  Internal CA evaluation, ACME enrolment, and SSH certificate guide in progress.

Secrets Management

Overview

Secrets — passwords, API keys, database credentials, private keys — need to be available to services that legitimately need them, invisible to services and people that don't, and auditable so you know who accessed what and when. Secrets placed in environment variables, config files committed to git, or .env files meet at most one of these three requirements.

A secrets manager solves these problems: secrets are stored encrypted at rest, access is controlled by policy tied to authenticated identity, and every read is logged. Services authenticate to the secrets manager using their TLS certificate (or another credential) and receive only the secrets their policy allows.

⚠  Secrets classification guide and access policy design documentation in progress.

Architecture

Dynamic secrets take the secrets management model further: rather than storing a static database password and handing it to a service, the secrets manager generates a temporary credential on demand — a database user with a short TTL, valid for one hour. When the TTL expires, the secrets manager revokes the credential at the database. The service never sees a long-lived credential that could be stolen and replayed indefinitely.

Leasing and revocation: every secret issued has a lease with a configurable TTL. Secrets can be renewed before expiry or explicitly revoked. If a service is compromised, its access to secrets can be revoked immediately without changing the underlying credentials (which would require updating every legitimate consumer).

⚠  Dynamic secrets configuration, lease management, and secret rotation strategies in progress.

Requirements & candidates

Secrets manager

The secrets manager is under evaluation. Candidates are assessed against these requirements:

  • Encryption at rest, with the master key protected by an HSM, a KMS or a documented manual unseal procedure.
  • Policy-based access tied to authenticated identity: X.509 / mTLS client certificates, OIDC tokens and Kubernetes service accounts.
  • A complete audit log of every read and write, exportable to the observability stack.
  • Leasing, renewal and revocation, plus dynamic short-lived credentials for databases and other back ends.
  • Automated rotation of static secrets.
  • High availability and a tested backup and restore path.
  • Integration with Kubernetes (e.g. via CSI or a sync mechanism), so workloads avoid long-lived secrets in manifests.
  • A licence, governance model and operating cost the project can accept long term, with the reasoning documented.
⚠  Secrets manager evaluation, key protection, and audit logging documentation in progress.

Authentication

Overview

Authentication (AuthN) answers "who are you?" Authentication is distinct from authorization (AuthZ, "what are you allowed to do?") and from identity (the cryptographic assertion that you are who you say you are). In practice, these three concepts are implemented by different systems that work together.

Federation lets users authenticate once with an identity provider (IdP) and use that authentication across multiple services. Rather than each service maintaining its own user database and authentication logic, services trust the IdP's assertions. The IdP handles login, MFA, session management, and password complexity — the service only needs to verify a token.

⚠  Identity federation design and IdP selection documentation in progress.

Architecture

OpenID Connect (OIDC) is the standard protocol for federated identity in web and API contexts. A user authenticates with an IdP; the IdP issues a JWT (ID token) asserting the user's identity and attributes. Services validate the JWT's signature using the IdP's public keys (fetched via OIDC discovery) and trust the claims it contains.

Service-to-service authentication uses the same protocol via client credentials flow: a service obtains a token from the IdP using its client ID and secret, and presents that token when calling other services. The receiving service validates the token, checks the audience claim (is this token intended for me?), and proceeds if the claims satisfy its authorization policy.

⚠  OIDC flow diagrams, token validation, claims mapping, and scope design documentation in progress.

Technologies

OIDC Federation

OIDC federation can chain identity providers: a user authenticates with an upstream IdP (a corporate directory, a managed identity provider, or any OIDC provider) and the local IdP issues its own token with the claims local services need. Local authorization then stays independent of upstream specifics, with fine-grained control over which claims pass through.

The identity provider software is under evaluation. Requirements: OIDC / OAuth 2.0 as the primary protocol, SAML 2.0 for applications that need it, SCIM for user and group provisioning, MFA (including phishing-resistant methods such as WebAuthn), upstream federation, high availability, and audit logging.

⚠  Identity provider evaluation, federation design, and service integration guides in progress.