You must explicitly authorize any Device identified by a set of Identity attributes before it can authenticate with the Mender server.
This section describes 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.
The Device Authentication service, a part of the Mender server, implements Device authentication.
This service exposes APIs for:
Mender identifies a Device 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 client signs the request with the 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 forms an authentication set, or 'auth set' in short.
The concept takes into consideration 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, where each Device might create multiple Authentication sets. Note that maximum one Authentication set can be accepted for a specific Device at any given time.
Mender provides two possible authorization flows. Both involve a user's explicit consent to authorize a Device via the UI or Device Authentication API, but they differ in the order of events and intended use cases. Below is a detailed breakdown of each.
For details of API calls please consult the API documentation.
The simplest flow, which usually suits quick prototyping and testing best, is manual authorization. The Mender server records every auth request for future inspection. You can accept it via the Device Authentication API (or the UI) whenever you see fit. When the Device sends another auth request it will result in a successful authorization.
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 with many Devices; we recommended it 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:
Preauthorization is the idea of authorizing a Device before it connects to the server for the first time. This is an intuitive model analogous to creating an account before logging in to an online service.
It allows you to authorize a particular Device before it leaves the production line by providing a pre-assigned Authentication set to the Device Authentication. When a Device with the corresponding Identity attributes and public key requests authorization, the Mender server will authorize it immediately without further user intervention.
This flow is typically better suited for a production use case, where you plan a release of a potentially large batch of Devices:
The sequence diagram below describes the API interactions between the user and the Device Authentication within this flow:
After the Mender server authorizes a Device, a subsequent authentication request
to the Device Authentication service returns an authentication token. The
Mender client will record the token and attach it to every API call under the HTTP
The token does have an expiry date (one week period by default), but the Mender client will obtain a fresh token from the Mender server automatically.
For details on the token format please see the relevant documentation on submitting an authentication request.