Devices, identified by a set of identity attributes, must be explicitly authorized by the user before they can authenticate with the Mender server.
This section describes in detail the components and workflows relevant to device authentication, and provides practical tips on navigating our APIs to successfully authorize devices, monitor authorization status, and troubleshoot related issues.
Device authentication is implemented by a single service:
The service exposes APIs for:
Device authorization can be performed in either of two modes, or workflows, which will be described in full in the following section:
It is important to clear up some terminology used throughout this documentation and various APIs.
A device represents, intuitively, a particular piece of hardware. It is uniquely identified by a set of identity attributes (MAC addresses, user-defined UIDs, etc.); think of it as an extension of a unique identifier into a multi-attribute structure (see Identity).
To obtain an auth token, the device sends an authentication request containing the identity attributes and its current public key. The request is signed with the respective private key (kept secret on the device), and the server uses the public key to verify the signature.
The combination of identity attributes and public key is termed an authentication set, or 'auth set' in short. The concept was introduced when considering device key rotation - a single device may over time present different keys, and it's important to track those, and allow the user to accept(i.e. authorize) or reject a particular identity/key combination.
Mender keeps tracks both of a device, as a single real-world entity, and its multiple authentication sets (one-to-many relation).
There are two possible authorization flows - both involve a user's explicit consent to authorize a device via the Device Authentication API, but they differ in the order of events and intended use cases. Below is a detailed breakdown of each of them.
Preauthorization is the idea of authorizing a device before it ever connects to the server for the first time. This is the intuitive model analogous to creating an account before logging in to an online service.
Preauthorization can be performed before a particular device is even released - or in fact, assembled - just yet. It is enough for the user to submit a pre-assigned authentication set to Device Authentication. At some point in the future, a device with corresponding identity attributes and public key will request authentication and be granted it immediately, without further user intervention.
This flow is therefore best suited to a typical production use case, where a release of a potentially large batch of devices is planned:
The sequence diagram below describes the API interactions between the user and Device Authentication within this flow:
For details of API calls please consult the API documentation.
For open source:
And for Enterprise:
An alternate flow, suitable mostly for quick prototyping and testing, is the accept-on-request flow.
It is not required for the user to preauthorize a device - instead, when the device first submits an auth request, it will be recorded for future inspection by the user. The auth set can then be accepted via the Device Authentication API whenever the user sees fit; a subsequent auth request from the device will be successful and a valid auth token will be returned.
The authorize-on-request flow therefore requires the user to accept authentication sets one-by-one, as devices connect to the server. As such it is not ideal for scenarios where a large number of devices is being managed; it is recommended for smaller or non-production installations instead.
The sequence diagram below describes the API interactions between the user, Device, and Device Authentication within this flow:
For details of API calls please consult the API documentation:
For open source:
And for Enterprise:
After a device is authorized, its next authentication request to Device Authentication results
in obtaining an authentication token. The Mender client will record it and attach it to every API call under
The token does have an expiry date (one week period), but the Mender client will obtain a fresh token automatically; the process is transparent to the user. The only prerequisite is that the device's authentication set has not been explicitly rejected in the meantime via the Device Authentication API.
For details on the token format please see the relevant documentation on submitting an authentication request for Open Source or Enterprise.
To view available devices and their authentication sets, use the
GET /api/management/v2/authentication/devices endpoint of the Device Authentication Management API for Open Source or Enterprise.
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to submit changes.
© 2021 Northern.tech AS