Device Enrollment and Trust Anchors¶

Enrollment binds a device to an organization and gives it the trust anchors it needs to verify the central policy and the offline license. This page covers the device identity, the enrollment handshake, the three ways to provision a device, the installer artifacts, MDM delivery, and re-enrollment.

For the server side of enrollment, see Policy Server Deployment and Operation. For how the resulting configuration is applied, see Deployment Models.

Device identity¶

The first time a device enrolls, Backend.AI GO creates a stable device identity: an Ed25519 key pair plus a device id. The public half is shared with the management server; the private key never leaves the device. The private key is held in the OS keychain (or an encrypted file on a headless host), and the public record is written to <app_data>/enterprise/identity.json with owner-only permissions. That file carries only the device id, the public key, and a creation timestamp. It never contains the private key.

Each device and each trust anchor has a fingerprint: the SHA-256 of the public key, truncated and rendered as colon-grouped uppercase hex. The Organization settings tab shows the device fingerprint, and the enrollment dialog shows the server's anchor fingerprints so a user can verify them against what the administrator communicated.

Trust anchors¶

A trust anchor is an Ed25519 public key the device trusts to sign policy and licenses. Anchors are distributed in the provisioning profile (trustAnchors) and returned by the enrollment handshake. The central policy and the offline license are both verified against these anchors, so a document signed by the wrong key is rejected.

An anchor may carry an optional notAfter expiry. An expired anchor cannot verify a policy or license, which lets you retire a key on a schedule. Provisioning more than one anchor lets you rotate keys without a flag day: sign with the new key while clients still trust the old one, then retire the old anchor. See key rotation in the Administrator Guide.

The enrollment handshake¶

Enrollment is a one-time handshake against the policy server. The device sends its device id, its public key, and the one-time enrollment token to POST /api/v1/enroll. The server validates the token (single-use), optionally binds the device to an organization, and returns the organization label, the trust anchors, and the poll interval. The device stores the anchors and begins polling for the central policy.

The token is a single-use bearer. It is never persisted on the device and never appears in any response, and it is stripped from the cached provisioning profile after first use. After enrollment, the device authenticates to the server by signing its requests with the device identity, so no further token is needed for policy polls or audit reporting.

The three provisioning entry points¶

All three paths converge on the same backend: device identity plus the one-time enrollment handshake plus profile discovery.

1. Deep link (aigo://enroll)¶

Opening an aigo://enroll link routes the user to the Organization settings tab with the enrollment dialog pre-filled. The link carries the token and the management server URL:

aigo://enroll?token=<one-time-token>&url=<management-server-url>

Either field may be omitted. The URL can come from a dropped provisioning file, and the token can be typed in. The token is treated as a secret: it is never logged in clear. This path suits per-user onboarding, where you mail or message each user a personalized link.

2. Manual enrollment (Organization settings tab)¶

Settings, then Organization, lets a user paste a one-time token and a management server URL. Before the handshake runs, the dialog shows the server URL and any known trust-anchor fingerprints and requires an explicit "trust this server" confirmation. This is the moment of human verification: the user confirms the fingerprints match what the administrator told them.

After enrolling, the tab shows the device identity (device id and public-key fingerprint), the enrollment status (organization, license state, locked-setting count, egress posture, air-gapped indicator), and a manual "refresh policy" action.

3. Installer or MDM provision.json drop¶

For zero-touch deployment, place a provision.json at the OS managed path. Backend.AI GO discovers it on the next launch and enters managed mode:

• Linux: /etc/aigo/provision.json
• Windows: %ProgramData%\aigo\provision.json
• macOS: /Library/Application Support/ai.backend.go/provision.json

The profile uses the same camelCase schema as the central policy (schemaVersion, mode, organization, managementServerUrl, trustAnchors, pollIntervalSecs, and an optional enrollment.token). Any one-time token in the file is consumed at first launch and stripped from the on-disk cache, so it is never durable. The template is packaging/provisioning/provision.example.json:

{
  "schemaVersion": 1,
  "mode": "managed",
  "organization": "Example Organization",
  "managementServerUrl": "https://policy.example.com",
  "trustAnchors": [
    {
      "id": "org-root-2026",
      "publicKey": "REPLACE_WITH_BASE64_ED25519_PUBLIC_KEY"
    }
  ],
  "pollIntervalSecs": 900,
  "enrollment": {
    "token": "REPLACE_WITH_ONE_TIME_ENROLLMENT_TOKEN"
  }
}

Fill in the publicKey from your trust anchor (see Policy Server Deployment and Operation) and, for hands-off enrollment, a one-time token. You can omit the token and let users enroll manually, in which case the file supplies only the URL and trust anchors.

Installer artifacts¶

The installer hooks prepare the managed directory and install a staged provision.json only when one is baked into the package and the managed path does not already carry a file. They never auto-manage a stock install, and they never clobber an existing MDM drop. The hooks ship under packaging/provisioning/.

A stock package ships only the example template and never auto-manages a device. To use installer-based enrollment, repackage with a real provision.json staged where the hook expects it.

MDM delivery¶

Any tool that can write a file to the OS managed path can provision a device. The discovery path is the same regardless of how the file arrives.

• Microsoft Intune: deploy provision.json to %ProgramData%\aigo\ (Windows) with a Win32 app or a remediation script, or to /Library/Application Support/ai.backend.go/ (macOS) with a shell-script policy. Alternatively, push a repackaged installer that stages the file.
• Jamf: deploy provision.json as a file payload to /Library/Application Support/ai.backend.go/, or distribute a .pkg built with the macOS postinstall hook.
• Group Policy (GPO): use a Group Policy preference or a startup script to copy provision.json into %ProgramData%\aigo\ on domain-joined Windows machines.

For per-user enrollment without file deployment, generate a personalized aigo://enroll?token=...&url=... link per device and deliver it through your existing channel (email, chat, or an MDM notification).

Re-enrollment and token rotation¶

A device that is already managed can re-enroll: the Organization tab shows a "re-enroll device" action that runs the same handshake with a new token. New trust anchors returned by the server are merged with the existing ones, so re-enrollment can introduce a rotated key.

Enrollment tokens are single-use. To onboard or re-enroll a device, mint a fresh token on the policy server (a --enrollment-token flag or an entry in the tokens file) and deliver it through any of the three entry points. A token in a cached provisioning profile is consumed once and stripped, so it never lingers on disk. To un-enroll, remove the managed provision.json (and any machine policy) from the OS path; the device returns to un-managed mode on the next launch, with the policy locks and egress firewall lifted only because the install is genuinely no longer managed.

Next steps¶

• Lock down an offline site in Air-Gapped Deployment.
• Require a signed entitlement in Offline Licensing.
• Follow the end-to-end onboarding and rotation procedures in the Administrator Guide.