Device authentication

Overview

An API for device authentication handling. Intended for use by devices.

Version information

Version : 1

URI scheme

Host : hosted.mender.io
BasePath : /api/devices/v1/authentication
Schemes : HTTPS

Paths


Submit an authentication request

POST /auth_requests

Description

Issues an authentication token for use in device-facing API calls.

The device presents its unique identity data and public key, and signs the request with its private key. If the request is valid and the device is known to the system, a valid JWT authentication token is issued.

Note that the very first authentication request from a given device ('bootstrap' request) always results in 'HTTP 401 Unauthorized'. At the same time, the identity data is recorded for later inspection by the user, who then explicitly accepts or rejects the device via the web GUI (backed by the Device Admission Service). A subsequent authentication request will reflect this decision.

Note that in case of JWT expiration, the authentication request must be sent again.

Parameters

Type Name Description Schema
Header X-MEN-Signature
required
Request signature.

The request signature depends on the public key submitted in the
AuthRequest. A summary of signature algorithms and format follows:

| Type | Digest | Format | Algorithm |
|------------|---------------------|--------------------------|--------------|
| RSA | SHA256(AuthRequest) | Base64(Signature) | [RFC2313] |
| ECDSA | SHA256(AuthRequest) | Base64(ASN.1(SEQ{R, S})) | [ANSI x9.62] |
| ED25519 | AuthRequest | Base64(Signature) | [RFC8032] |
Remark:
For ECDSA, the signature constitutes two integers (R and S)
in which case the binary signature is taken as the ASN.1 sequence of
the two numbers in the given order.
string
Body AuthRequest
required
Authentication request. AuthRequest

Responses

HTTP Code Description Schema
200 Authentication successful - a new JWT is issued and returned.
The JWT is signed with the API's private key ('RS256' signing algorithm), and contains
the following standard claims:
'iss' - issuer
'exp' - expiry date
'sub' - subject (auto-generated device ID)
'jti' - token's unique identifier (tracked for the purpose of revocation)
No Content
400 Missing or malformed request params or body. See the error message for details. Error
401 The device cannot be granted authentication. There are multiple possible reasons, e.g.:

the device hasn't been accepted yet

the device has been explicitly rejected

* key/signature don't match

See the error message for details.
Error
500 Internal server error. Error

Produces

  • application/jwt
  • application/json

Example HTTP request

Request body
{
  "id_data" : "{"mac":"00:01:02:03:04:05"}",
  "pubkey" : "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH
VJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c
yC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP
okP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty
1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0
iyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG
UwIDAQAB
-----END PUBLIC KEY-----
"
}

Example HTTP response

Response 200
{
  "application/jwt" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.\neyJleHAiOjE0NzYxMTkxMzYsImp0aSI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1h\nMWZiLWYxMTE2MWNlN2E4NCIsImlzcyI6Ik1lbmRlciIsInN1YiI6IjlmNzM2\nYmNiMjhiZmFhOTg5YjVmNWUxNDA5ZGJmMGVhYzdhNjYxMjZiNjMyZDAzYWYwZ\nmUzNGFjMjhiZjRhNzIifQ.\nPArg_WuoQkOiJ4kDoHYbQRjnxykeF1lIlsgJfUryhivnip2AHz5bkxxaxF20X\nTq9mIzSDonTSukfOtkaxJTZXjCMHjgh50iwa6_pUivIYWsIJW2O9t_M9T_SC-\n7Xu7IhE_iKQFb2NXxVfAG4nZKrheUM4MJBt8SxCawT2EOPopiLeIC6MOFBu_s\nPa9RsagKSZCRaLTBWVhmEGbfn19tLOX3Z06DZql61G-VY-YuyOlBjpEsCc4Hi\nA1cXIdncCZKugrONOa44_m4yx0VsgRg4jCd2VO-Is-A96Jw3zkZshoD2cPXVS\nKAhFdhHja447ftuYYRq9kIQghKi3hfsPgyFZQ\n"
}
Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 401
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Definitions

AuthRequest

Name Description Schema
id_data
required
Vendor-specific JSON representation of the device identity data (MACs, serial numbers, etc.). string
pubkey
required
The device's public key (PEM encoding), generated by the device or pre-provisioned by the vendor. Currently supported public algorithms are: RSA, ED25519 and ECDSA. string
tenant_token
optional
Tenant token. string

Error

Error descriptor.

Name Description Schema
error
optional
Description of the error. string
request_id
optional
Request ID (same as in X-MEN-RequestID header). string