Skip to content

Authentication Model

Authentication is handled by an external OAuth2-compliant authorization server, which authenticates users and clients and issues the access tokens they present to the Keyserver. The Keyserver itself does not manage usernames or passwords.

flowchart TB
    U(["User<br/>a person in a browser"]) --> W["Keyserver UI (BFF)"]
    C(["Client<br/>CI pipeline, headless service,<br/>provisioning station"])

    subgraph IDP["Identity provider"]
        TRIAL["<b>Trial:</b> the bundled Authserver<br/>evaluation only"]
        PROD["<b>Production:</b> your OAuth2/OIDC provider,<br/>with a client registration per caller<br/>(for example, an Entra ID app registration)"]
    end

    W -->|"1. user signs in<br/>Authorization Code"| IDP
    C -->|"1. authenticates<br/>Client Credentials, federated<br/>CI token, or PKCE"| IDP
    IDP -->|"2. issues"| T["Signed JWT access token<br/>held by the UI or the client"]
    T -->|"3. sent with each API call<br/>Authorization: Bearer"| V

    subgraph KS["Keyserver API"]
        V["Validate the token<br/>signature, exp, iss, aud, scope"] --> M["Match a registered subject"]
        M --> R["Check the subject's roles"]
    end

    IDP -.->|"public keys (JWKS)"| V

Diagram: User a person in a browser; Keyserver UI (BFF); Client CI pipeline, headless service, provisioning station; Identity provider; Trial: the bundled Authserver evaluation only; Production: your OAuth2/OIDC provider, with a client registration per caller (for example, an Entra ID app registration); 1. user signs in Authorization Code; 1. authenticates Client Credentials, federated CI token, or PKCE; 2. issues; Signed JWT access token held by the UI or the client; 3. sent with each API call Authorization: Bearer; Keyserver API; Validate the token signature, exp, iss, aud, scope; Match a registered subject; Check the subject's roles; public keys (JWKS)


Trial vs. production

Trial instances use the bundled Authserver instead, so you can evaluate the Keyserver without configuring an identity provider first.

The Authserver is for evaluation only

The Authserver lacks the controls that protect production signing keys:

  • No MFA. A stolen password alone is enough to sign in.
  • No account lifecycle management. Accounts are not tied to your joiner, mover and leaver processes, so access does not end when someone leaves.
  • No enterprise integration. It does not connect to your directory or apply your organization's sign-in policies.

Never use it for real firmware signing, device certificates or production pipelines. Every environment other than a trial, including development CI and manufacturing, must authenticate through an external OAuth2/OIDC provider; see External Authorization Server.

Environment Identity provider
Trial The bundled Authserver
Any other environment (development CI, production, manufacturing) Your own OAuth2/OIDC provider, required

What the trial Authserver's tokens contain is shown in the last column of the Token Validation table.


External Authorization Server

The Keyserver accepts OAuth2/OIDC JSON Web Tokens (JWTs) from the identity providers configured for your deployment. Typical providers include:

  • Microsoft Entra ID (formerly Azure AD)
  • GitLab (OIDC ID tokens issued to CI jobs)
  • Any other compliant OAuth2/OIDC provider

Validated provider integrations

Setup guides validated against a live Keyserver instance exist for Microsoft Entra ID and GitLab; guides for further providers are planned. The Keyserver can accept tokens from any standards-compliant OAuth2/OIDC provider that is configured as an identity provider for your deployment. For a provider without a validated guide, configure the provider side according to its own documentation and the token requirements.

The provider:

  1. Authenticates the user or client
  2. Issues a signed JWT access token
  3. Publishes the public keys required for token validation at a JWKS endpoint

The Keyserver validates each token locally against the provider's public keys, without calling the provider. It fetches those keys from the jwks_uri in the provider's discovery metadata, caches them, and refreshes the cache when the provider rotates keys.


Choosing a flow

Which flow fits depends on who is authenticating and whether the system can protect a secret:

You are Situation Flow Setup guide
Human user Browser login to the Keyserver UI Authorization Code (via the Keyserver BFF) Azure Entra ID Integration
CI pipeline GitLab CI, Azure DevOps Federated job identity, no stored secret GitLab CI · Azure DevOps
Headless service Standalone build server, signing service; can hold a secret securely Client Credentials (service account) Integrate a Headless Build Server
Provisioning station / desktop tool Cannot hold a secret; an operator is present Authorization Code + PKCE (operator logs in) PKCE Client Integration · Integrate Provisioning Tools

Authentication Flows

People use the Authorization Code Flow. Automated systems use Client Credentials or a federated CI identity.

Users: Authorization Code Flow

Interactive users authenticate through a browser using the standard OAuth2 Authorization Code Flow. The Keyserver web application is a Backend-for-Frontend (BFF) (IETF: OAuth 2.0 for Browser-Based Applications), so the browser never holds an OAuth2 token.

sequenceDiagram
    autonumber
    participant B as Browser
    participant W as Keyserver web application (BFF)
    participant IdP as Identity provider
    participant KS as Keyserver API

    B->>W: User opens the Keyserver UI
    W-->>B: Redirect to the identity provider
    B->>IdP: User signs in (MFA if configured)
    IdP-->>B: Redirect to the web application with an authorization code
    B->>W: Authorization code
    W->>IdP: Exchange the code for ID and access tokens
    IdP-->>W: Tokens, kept server-side with the user's session
    W-->>B: Session cookie only (JSESSIONID, Secure, HttpOnly)
    B->>W: UI calls carry the cookie
    W->>KS: API call with the user's access token

Diagram: Browser; Keyserver web application (BFF); Identity provider; Keyserver API; User opens the Keyserver UI; Redirect to the identity provider; User signs in (MFA if configured); Redirect to the web application with an authorization code; Authorization code; Exchange the code for ID and access tokens; Tokens, kept server-side with the user's session; Session cookie only (JSESSIONID, Secure, HttpOnly); UI calls carry the cookie; API call with the user's access token

This flow is used because:

  • No token is exposed to JavaScript, the browser URL, or history. Page scripts cannot read an HttpOnly cookie, so a cross-site scripting bug cannot exfiltrate a bearer token.
  • MFA is enforced by the enterprise identity provider, not the Keyserver
  • Session timeouts and reauthentication are handled centrally

What follows from the BFF model:

  • CSRF: the browser authenticates with a cookie, not an Authorization header, so state-changing UI requests need CSRF protection. The web application provides it.
  • Logout: ending the Keyserver session invalidates the server-side tokens, but not the identity provider's session, which may sign the same user straight back in. To switch identity, for example to approve as a different person, use a private window or a separate browser profile.
  • CORS: the UI is same-origin with its backend, so CORS configuration only matters for a browser-based application calling keyserver.<UNIQUE-ID>... directly with its own token.

PKCE

PKCE (Proof Key for Code Exchange, RFC 7636) protects the Authorization Code Flow for your own clients that cannot hold a client secret: provisioning stations, desktop tools, and browser-only applications. The Keyserver UI does not need it, because its BFF backend holds the client secret.

The client generates a random code_verifier, sends a hash of it (code_challenge) with the authorization request, and presents the original code_verifier at the token exchange. An attacker who intercepts the authorization code cannot exchange it for a token without the code_verifier. Setup: PKCE Client Integration.


Clients: Client Credentials Flow

Automated systems such as CI/CD pipelines, build servers, and provisioning tools authenticate using OAuth2 Client Credentials.

  1. The client presents its client_id and client_secret to the authorization server.
  2. The authorization server returns a signed JWT access token.
  3. The client includes the token in the Authorization: Bearer header for all Keyserver API calls.

The client_secret is sensitive credential material. In CI or build environments, we recommend storing it with the platform's secret or protected-variable mechanism and never embedding it in source code.

Headless service identities

A standalone build server, signing service, or factory tool that can protect a secret authenticates with Client Credentials, for example as an Entra ID app registration. See Integrate a Headless Build Server.

Federated CI identities (no stored secret)

CI platforms that issue short-lived job identity tokens need no long-lived secret.

  • On Azure DevOps, the pipeline's service connection is federated with an Entra ID app registration (Workload Identity Federation). The pipeline exchanges its federated identity for an Entra access token, and that app registration is registered as the Keyserver subject. See Integrate the Keyserver with Azure DevOps.
  • On GitLab CI, the job's OIDC ID token is presented directly to the Keyserver, with no Entra exchange. The Keyserver trusts your GitLab instance as an issuer and validates the token against GitLab's published keys (JWKS). The id_tokens configuration is in GitLab CI.

We recommend federation for production pipelines.


Token Validation

All access tokens must be:

  • JWT format with a digital signature
  • Signed by a configured authorization server
  • Verifiable against the provider's JWKS endpoint

The Keyserver validates the claims below. The last column shows what the trial Authserver's tokens contain, which helps when you debug with the About page's token viewers or adapt examples written for another provider.

Claim What the Keyserver checks In a trial Authserver token
Signature Verified against the provider's published public keys Signed by the Authserver
exp Token must not be expired Present, with the standard nbf, iat and jti claims
iss Must match a configured issuer https://authserver.<UNIQUE-ID>.cryptera-security.io
aud When audiences are configured for the provider, must include one of them Client: the client_id itself. User: keyserver-client, the UI's own OAuth2 client
scp / scope When present and the provider is configured with a scope, must contain that scope Client: absent (Scopes)
roles When the provider is configured with a role, a token holding it is a client (service account) token Client: ["ApiCaller"]. User: absent
sub / oid / azp / preferred_username Mapped to a registered subject (Token-to-subject mapping) sub: an MD5 hash of the client ID or username, matched against Subject ID. preferred_username: the client ID or username

Scopes

A client-credentials token from the trial Authserver carries no scope, scp, or ver claim, so Entra ID examples that inspect those claims find nothing.

In production, client-credentials tokens generally carry no scope claim either, including Entra ID's. See Integrate a Headless Build Server. For those tokens, the audience restriction configured for the provider does the work: requesting api://<KEYSERVER_APP_ID>/.default is what sets aud to the Keyserver. Configure the keyserver scope as Azure Entra ID Integration describes.

Delegated (user) tokens do carry scp; the PKCE guide checks it.


From token to subject

A valid token is necessary but not sufficient: its identity must match a registered subject, or the request is rejected with 401 ("The user/client is not valid"). The matching rules are in Token-to-subject mapping.


Authentication vs. authorization

Authentication ("who are you?") and authorization ("what are you allowed to do?") are handled separately:

  • Authentication is performed by the external OAuth2 provider
  • Authorization is evaluated by the Keyserver using the subject's assigned roles

A valid token from a known subject with no matching permissions still results in a 403. Roles are managed inside the Keyserver, not the identity provider.