Authentication and licensing
The Suite owns account authentication and Harlock licence state. These are two separate protocols with different credentials and failure handling.
Interactive sign-in
The Suite is the production OIDC provider and is also an OIDC client of itself.
Harlock and Arcadia use the same public provider. The clients use Authorization Code with
PKCE; discovery starts at /.well-known/openid-configuration and public signing
keys are served from /api/oidc/jwks.
The browser finishes the OIDC exchange at /api/auth/callback and stores an
encrypted sab_session cookie. Harlock keeps its own access and refresh tokens.
An OIDC login proves the user identity; it does not activate a Harlock licence.
GCS clients use their OIDC access token to list visible drones at
/api/gcs/drones and request a short-lived gateway token at
/api/gcs/drones/{droneId}/gateway-token. Authorization still depends on the
Suite account's current role, vehicle visibility and remote-access policy.
Supporting a GCS OIDC client does not give it a Harlock licence activation.
Administrators create users in the Suite and issue a random, single-use temporary password. It expires after 30 minutes and forces a password change before the account can use the rest of the application. This is also the current recovery procedure. There is no self-service email reset.
Harlock licence lifecycle
| Operation | Authentication | Result |
|---|---|---|
POST /api/gcs/licenses/activate | Suite OIDC bearer token | Binds the licence and device public key; returns activation id and signed activation token |
POST /api/gcs/licenses/check | Current activation token plus a fresh device-signed challenge | Confirms server state and rotates the activation token |
POST /api/gcs/licenses/deactivate | Current activation token plus a fresh device-signed challenge | Revokes the device activation |
GET /api/gcs/licenses/keys | Public | Publishes the Ed25519 keys used to verify activation tokens |
Harlock must save the newest activation token returned by activate or
check. It must generate a new nonce for every check or deactivation and sign
the canonical challenge with the private half of the device key. The Suite
stores only the public half.
OIDC tokens and licence tokens are not interchangeable. They use different issuers, audiences, key stores and JWKS endpoints. A cached activation can continue according to Harlock's offline policy when interactive login is unavailable; the next online check remains authoritative for expiry, revocation and device binding.
The versioned wire contract, canonical payloads, response fields and error
codes are maintained in the internal
docs/GCS_LICENSE_INTEGRATION_GUIDE.md. That runbook is for implementers and
contains operational detail that is not copied into this public site.
Operator checks
- Filter Node service logs for the structured authentication events described in Watching the identity provider.
- Confirm OIDC discovery and both JWKS endpoints without copying tokens into tickets or documentation.
- Treat a successful web login and a successful licence check as separate evidence.
- When an account is disabled or given a temporary password, confirm existing browser and refresh sessions are revoked as documented in OIDC provider.