OpenFrame Documentation
Deployment guides, the CLI reference, architecture and admin guides for OpenFrame
Flamingo Raises $4.5M Seed Round · Led by Vertex Ventures, bringing total funding to $6.7M to build the open, AI-native layer for IT and security.
Deployment guides, the CLI reference, architecture and admin guides for OpenFrame
Registration And Authentication is the device-facing boundary of the OpenFrame Client service. It accepts an initial registration key and device metadata, supports authenticated reinstall and uninstall operations, issues OAuth-style client tokens, and schedules the tenant's current client feature flags for a newly registered machine.
The module is implemented by the com.openframe.oss:openframe-client-core library at version 7.0.11 and runs in this repository's OpenFrame Client service. It is a focused part of the verified OpenFrame Client Core Java documentation.
/api/agents for registration, reinstall, and uninstall./oauth/token for client-secret and refresh-token grant handling.The OpenFrame Client service hosts the HTTP controllers from this module. The device-side OpenFrame client first calls the registration API, then uses the returned client identity and credentials to obtain and renew tokens. After registration, the feature-flag service can seed the device's delivery stream with the current tenant configuration.
flowchart LR
Agent["OpenFrame Device Agent"] -->|"register, reinstall, uninstall"| AgentController["Agent Controller"]
Agent -->|"token request"| AuthController["Agent Auth Controller"]
AgentController --> RegistrationService["Agent Registration Service"]
AgentController --> UninstallService["Agent Uninstall Service"]
RegistrationService --> FlagsService["Registration Feature Flags Service"]
AuthController --> AuthService["Agent Auth Service"]
AuthService --> AccessTokens["Access Token Generator"]
AuthService --> RefreshTokens["Refresh Token Generator"]
AccessTokens --> JwtService["JWT Service"]
RefreshTokens --> JwtService
FlagsService --> ConfigurationService["Client Configuration Service"]
FlagsService --> DeliveryRouter["Delivery Router"]
DeliveryRouter --> Agent
AgentController is mapped to /api/agents and defines three POST operations.
| Operation | Required headers | Body | Result | Delegate |
|---|---|---|---|---|
/register |
X-Initial-Key |
Validated AgentRegistrationRequest |
AgentRegistrationResponse |
AgentRegistrationService.register |
/reinstall |
X-Initial-Key, X-Machine-Id, X-Client-Secret |
Validated AgentRegistrationRequest |
AgentRegistrationResponse |
AgentRegistrationService.reinstall |
/uninstall |
X-Machine-Id, X-Client-Secret |
None | HTTP 204 | AgentUninstallService.uninstall |
The controller is deliberately thin: it extracts the identity material from headers, applies Jakarta validation to the registration payload, and passes the request to the respective service. Authentication and registration validation policy therefore belongs to those delegates rather than to the controller.
The agent lifecycle endpoints are defined in AgentController.java.
AgentAuthController is mapped to /oauth and provides POST /oauth/token, producing JSON. It accepts these request parameters:
| Parameter | Required | Purpose |
|---|---|---|
grant_type |
Yes | Selects the token grant handled by the authentication service. |
refresh_token |
No | Refresh-token credential for a renewal flow. |
client_id |
No | Client identifier for a client-secret flow. |
client_secret |
No | Client secret for a client-secret flow. |
The controller logs the requested client identifier at debug level and delegates issuance to AgentAuthService.issueClientToken. An IllegalArgumentException becomes HTTP 401 with a message field. Unexpected errors are logged server-side and become HTTP 400 with server_error and a generic description; internal exception details are not returned.
The endpoint is defined in AgentAuthController.java.
Registration starts with an initial key and a validated agent payload. The controller delegates the domain work to AgentRegistrationService. The provided module components establish that feature flags are a post-registration concern: AgentRegistrationClientFeatureFlagsService.process builds a machine-targeted delivery seed from the tenant configuration and routes it when this delivery type is enabled.
sequenceDiagram
participant Agent as Device Agent
participant Controller as Agent Controller
participant Registration as Registration Service
participant Flags as Feature Flags Service
participant Config as Client Configuration Service
participant Router as Delivery Router
Agent->>Controller: POST register with initial key and request
Controller->>Registration: register initial key and request
Registration-->>Controller: registration response
Controller-->>Agent: registration response
Registration->>Flags: process machine identifier
Flags->>Config: read tenant client configuration
Config-->>Flags: feature flags
Flags->>Router: dispatch machine feature flag seed
Router-->>Agent: feature flag delivery
Feature-flag dispatch is best effort. The service exits immediately when CLIENT_FEATURE_FLAGS delivery is disabled. If configuration lookup or dispatch throws a runtime exception, it logs the error and preserves the successful registration result. This ensures a machine can register even when delivery infrastructure is temporarily unavailable; a later feature-flag release can reach it.
The implementation is in AgentRegistrationClientFeatureFlagsService.java.
The authentication service receives the requested grant type and the supplied credential type. The controller does not decide which optional parameters are valid together; that decision is delegated to AgentAuthService. The resulting token response is returned unchanged on success.
AccessTokenGenerator creates a Bearer JWT from an OAuth client record. Its claims include:
https://auth.openframe.com;security.oauth2.token.access.expiration-seconds;machine_id, grant_type, and roles claims.RefreshTokenGenerator produces a separate JWT with the client identifier as its subject, a refresh_count claim initialized to zero, and an expiry set by security.oauth2.token.refresh.expiration-seconds. Its next-token operation increments the count. The configured security.oauth2.token.refresh.max-refresh-count is exposed by the generator for the authentication flow to enforce.
flowchart TD
TokenRequest["Token Request"] --> GrantCheck{"Supported grant and credentials?"}
GrantCheck -->|"no"| Unauthorized["HTTP 401 Message"]
GrantCheck -->|"yes"| AuthService["Agent Auth Service"]
AuthService --> AccessGenerator["Access Token Generator"]
AuthService --> RefreshGenerator["Refresh Token Generator"]
AccessGenerator --> JwtSigner["JWT Service"]
RefreshGenerator --> JwtSigner
JwtSigner --> TokenResponse["Agent Token Response"]
TokenResponse --> Agent["Device Agent"]
The access and refresh generators are implemented in AccessTokenGenerator.java and RefreshTokenGenerator.java.
A reinstall supplies the initial key plus the existing machine identifier and client secret. This enables the registration service to distinguish the lifecycle operation from first-time registration. Uninstall does not accept a request body: the machine identifier and client secret are enough for AgentUninstallService to process the request, after which the controller returns HTTP 204.
flowchart LR
ExistingAgent["Existing Device Agent"] -->|"initial key, machine ID, client secret"| Reinstall["Reinstall Endpoint"]
Reinstall --> RegistrationService["Agent Registration Service"]
ExistingAgent -->|"machine ID and client secret"| Uninstall["Uninstall Endpoint"]
Uninstall --> UninstallService["Agent Uninstall Service"]
UninstallService --> NoContent["HTTP 204"]
X-Initial-Key, X-Client-Secret, refresh tokens, and generated JWTs as secrets. Do not include their values in logs or telemetry.client_id; no token, initial key, or client secret is logged by the provided controller code.| Component | Role |
|---|---|
AgentController |
HTTP API for agent registration, reinstall, and uninstall. |
AgentAuthController |
HTTP token endpoint and error mapping for agent authentication. |
AgentRegistrationService |
Registration and reinstall delegate invoked by the lifecycle controller. |
AgentUninstallService |
Uninstall delegate invoked by the lifecycle controller. |
AgentRegistrationClientFeatureFlagsService |
Best-effort seed dispatcher for the tenant's current feature flags after registration. |
AccessTokenGenerator |
Builds access-token claims and signs the resulting JWT. |
RefreshTokenGenerator |
Builds initial and successor refresh-token claims, including the refresh counter. |
This module's source is supplied by the OpenFrame OSS Library dependency and is assembled into the OpenFrame Client service published by this repository. The platform gateway routes /clients/** traffic to that service, while the service's runtime configuration supplies the client-service address, token lifetimes, signing support, configuration access, and delivery infrastructure.
For surrounding service startup, event delivery, and other client-service concerns, see OpenFrame Client Core Java.