Livepatch Server Authentication
This document provides a technical reference for all authentication and authorization mechanisms used by the on-premises Livepatch Server. It covers the authentication flows for each API surface and the cryptographic technologies involved.
Admin APIs
These APIs are consumed by administrators through the Livepatch Admin Tool.
The following authentication flows are supported:
- Basic Auth → Macaroon: Login using Basic Auth to obtain a macaroon, then use the macaroon to authenticate subsequent requests. Macaroons expire after 240 hours.
All admin activity is logged as a structured security event with the authz_admin event code.
Client APIs
These APIs are consumed by Livepatch Client instances.
- Auth Token: A UUIDv4 token used to authenticate and register a machine. After successful registration, a machine token is issued for subsequent requests. This is a legacy token format that is no longer used for new clients.
- Resource Token: A macaroon verified against the Ubuntu Pro backend to authenticate requests. This token is provided to the Livepatch Client by the Ubuntu Pro client when enabling Pro.
After authentication, client requests are authorized based on tier and affordances (architecture and kernel compatibility).
Server APIs
These APIs are used for patch synchronization between on-premises servers and their upstream patch source (Canonical’s hosted Livepatch service or another on-premises server).
- - Contract Resource Token: A resource token obtained from the Ubuntu Pro contracts service, used to authenticate the on-premises server with Canonical’s hosted Livepatch service. For charm deployments, obtained via the
get-resource-tokenJuju action (juju run canonical-livepatch-server-k8s/<leader> get-resource-token contract-token=<TOKEN>). For snap deployments, obtained implicitly by setting the contract token (sudo snap set canonical-livepatch-server token=<CONTRACT_TOKEN>); the snap’s configure hook exchanges it for a resource token and setspatch-sync.tokenautomatically. The process exchanges a contract token for a machine token and then retrieves the resource token with appropriate affordances. - Sync Token: A UUIDv4 generated through the Admin APIs of the upstream server (
livepatch-admin sync-tokens add <tier> <token-name>). Used in both direct (hosted) and federated (on-premises to on-premises) synchronization. Like client tokens, sync tokens specify which tier patches will be retrieved from. Configured viapatch-sync.token. Stored in PostgreSQL with verification by direct comparison.
Technologies
Basic Auth
HTTP Basic Authentication using a username and Base64-encoded password. The authentication process extracts credentials from the HTTP Authorization header, decodes them, and compares the provided password against a stored bcrypt hash using constant-time comparison.
Go packages used:
Macaroons
Macaroons are decentralized authentication tokens that use HMAC for cryptographic signatures and symmetric encryption to encode the scope (caveats) of entitlements.
Operations are performed using HMAC-SHA256 and XSalsa20-Poly1305. Go packages used by the macaroon package:
The higher-level Macaroon Bakery package adds public key cryptography for macaroon operations.
Operations are performed using Ed25519 and XSalsa20-Poly1305. Go packages used:
Macaroon root keys are stored in PostgreSQL with a 24-hour expiry policy. Macaroons themselves expire after 240 hours.
UUID
UUIDv4 is a 128-bit identifier generated using random number generation, represented as 32 hexadecimal digits in 8-4-4-4-12 format. Used for auth tokens, machine tokens, sync tokens, and request trace IDs.
Go packages used: