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 three possible authorization flows. Two of them 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. The third one, available as an Enterprise feature, leverages a PKI (Public Key Infrastructure) to authorize devices based on client certificates without the need of explicit user's actions. 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:
Mender Enterprise supports setting up a reverse proxy at the edge of the network, which can authenticate devices using TLS client certificates. Each client is equipped with a certificate signed by a CA certificate (Certificate Authority), and the edge proxy authenticates devices by verifying this signature. Authenticated devices are automatically authorized in the Mender backend, and do not need manual approval.
This is in particular useful in a mass production setting because you can sign client certificates when they are manufactured so they automatically get accepted into the Mender server when your customer turns them on, which might happen several months after manufacturing.
The sequence diagram below describes the authentication of a Device through the mutual TLS ambassador:
|mutual TLS flow|
Futher communication between the Device and the Mender Server is intermediated by the mTLS ambassador which verifies the requests are authenticated with a valid client TLS certificate.
Please refer to the client certificates section to find further details on the configuration of this feature.
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.
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.
© 2020 Northern.tech AS