Core Concepts: Authentication Model¶

The Keyserver does not manage usernames or passwords internally (only for trial setups).
Instead, it relies entirely on an external OAuth2-compliant authorization server to authenticate subjects and issue access tokens.

This section explains how authentication works for both users and clients, how tokens are validated, and why the design strengthens security.

External Authorization Server¶

The Keyserver integrates with any identity provider that can issue OAuth2/OIDC JSON Web Tokens (JWTs).
Typical providers include:

• Microsoft Entra ID (formerly Azure AD)
• GitLab (via Workload Identity Federation or JWT tokens)

The chosen provider:

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

The Keyserver verifies tokens using the provider’s published public keys and accepts or rejects requests accordingly.

Authentication Flows¶

Two OAuth2 flows are used depending on whether the subject is a human (approver / admin) or a system (CICD).

Users: Authorization Code Flow (with optional PKCE)¶

Interactive users authenticate through a browser, using the standard OAuth2 Authorization Code Flow.

How it works¶

1. The user accesses keyservers user interface URL.
2. The user is redirected to the identity provider where the user logs in.
3. The provider redirects back to the Keyserver user interface with an authorization code.
4. The Keyserver’s frontend exchanges the code for a signed JWT access token.
5. The JWT is stored in keyservers frontend and is used for all subsequent API calls.

Why this flow is used¶

• Strong authentication, including MFA
• Tokens never pass through insecure clients (web browser)
• Simplifies integration with enterprise SSO
• Supports session timeouts and reauthentication
• Standard flow used in modern web based systems.

PKCE for public clients¶

If the user interface runs in an environment where secrets cannot be stored securely (e.g., a native app or browser-based provisioning tool running off-site), PKCE is required.

PKCE adds: - A one-time code verifier generated by the client
- A code challenge sent to the identity provider - Client secret only exists in memory

This prevents attackers from hijacking client secret/authorization codes during the flow.

Clients: Client Credentials Flow¶

Automated systems (CI/CD pipelines, build servers, integration scripts) authenticate using OAuth2 Client Credentials.

How it works¶

1. The client presents its Client ID and Client Secret (which it must store securely in CI/CD runner or build server!) to the authorization server
2. It receives a signed JWT access token.
3. The token is included in the Authorization: Bearer header for all Keyserver API requests.

Why this flow is used¶

• Non-interactive, suitable for automation
• Simple
• No browser interaction required
• Integrates cleanly with GitLab, and other CI platforms

Workload Identity Federation (WIF)¶

Some providers (e.g., Azure DevOps, GitHub, GitLab) can issue tokens without storing secrets, using trust relationships between:

• The CI runner
• The Identity Provider
• The Keyserver app registration

This eliminates long-lived credentials and is recommended for production pipelines.

GitLab CI tokens (OIDC)¶

For GitLab CI, the runner issues an OIDC ID token (e.g., CI_JOB_JWT_V2). The Keyserver validates that token locally by:

• Verifying the signature against GitLab's JWKS (https://gitlab.com/-/jwks or https://<your-gitlab>/-/jwks for self-managed)
• Checking issuer (iss), audience (aud configured for the Keyserver), expiration, and subject claims

No PATs or long-lived secrets are required; trust is derived solely from the signed GitLab-issued token.

Token Requirements¶

All access tokens must be:

• JWT format
• Digitally signed by the authorization server
• Verifiable through the provider’s JWKS (JSON Web Key Set)
• Issued for the Keyserver’s audience value

The Keyserver validates:

• Signature integrity
• Token expiration
• Audience (aud)
• Issuer (iss)
• Scope (where applicable)
• Subject identity (preferred_username, oid or sub claims)

The Keyserver never communicates with the identity provider during request processing; all validation is local and cryptographically verifiable.

Each authenticated identity corresponds to a subject inside the Keyserver.

A subject must exist with:

• An identity matching the identity provider’s token claims
• One or more roles granting permissions
• A subject type: User or Client

Authorization vs Authentication¶

Authentication (who are you?) is only the first step.
Once the Keyserver confirms the identity from the token by matching a subject, it evaluates the subject’s permissions by inspecting associated roles.

• A valid token identifying a subject without the correct permissions for the requested action still results in denial (we know who you are but you are not allowed to do "this").
• Roles are stored and managed inside the Keyserver, not the identity provider.
• Token identity must match a configured subject.
• For initial login, matching is performed on JWT preferred_username claim (email) against subjects subjectname. Immutable JWT oid/sub is saved in subject as subjectid.
• For following logins, matching is performed on JWT oid/sub against subjectid

Summary¶

• The Keyserver uses standard external OAuth2 providers for all authentication.
• Users authenticate using Authorization Code Flow (with optional PKCE).
• Clients authenticate using Client Credentials Flow or Workload Identity Federation.
• Access tokens are validated locally using the provider’s public keys.
• Identity proves who the subject is; subject's association with roles define what they are allowed to do.

This model provides strong authentication, integrates with enterprise IAM systems, and simplifies secure automation workflows.

Trial vs. Production Authentication¶

The Keyserver supports two authentication configurations:

1. Internal Authserver (Trial / Development Only)¶

The Keyserver includes a lightweight OAuth2 authentication service intended for:

• Local testing
• Trial and demo environments
• Air-gapped evaluation systems
• CI/CD sandboxing

This internal Authserver runs alongside the Keyserver and allows administrators to create local client credentials for rapid testing.

It is not intended for production use and should not be used for:

• Real firmware signing
• Production CI/CD pipelines
• Device certificate issuance
• Multi-user environments

2. External Identity Providers (Required in Production)¶

Production deployments must use an external identity provider, such as:

• Azure Entra ID
• GitLab OIDC
• Compliant OAuth2/OIDC providers

External identity providers provide:

• Strong MFA policies
• Centralized credential management
• Account lifecycle enforcement
• Short-lived access tokens
• Hardware-backed identity support
• Compliance auditability

The Keyserver integrates with these providers through standard OAuth2/OIDC flows: - Authorization Code (UI users) - Client Credentials (CI/CD clients) - PKCE (public clients / provisioning tools) - Federated OIDC tokens (GitLab CI, Azure DevOps WIF)

Using an external identity provider ensures that authentication, password policies, MFA, account ownership, and token issuance are handled by the organization’s existing identity infrastructure.

Summary¶

Summary¶

Authentication is externalized and standards-based.
Use the internal Authserver only for testing, and always use an external identity provider in development and production for MFA, traceability, and security compliance.