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)"| VDiagram: 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:
- Authenticates the user or client
- Issues a signed JWT access token
- 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 tokenDiagram: 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
HttpOnlycookie, 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
Authorizationheader, 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.
- The client presents its
client_idandclient_secretto the authorization server. - The authorization server returns a signed JWT access token.
- The client includes the token in the
Authorization: Bearerheader 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_tokensconfiguration 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.