Skip to main content

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​

OperationAuthenticationResult
POST /api/gcs/licenses/activateSuite OIDC bearer tokenBinds the licence and device public key; returns activation id and signed activation token
POST /api/gcs/licenses/checkCurrent activation token plus a fresh device-signed challengeConfirms server state and rotates the activation token
POST /api/gcs/licenses/deactivateCurrent activation token plus a fresh device-signed challengeRevokes the device activation
GET /api/gcs/licenses/keysPublicPublishes 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.