To implement your own account server, you need to implement a couple of things:
- An access key validation endpoint
- Endpoints to generate and validate application access tokens
1. Access Key validation
To validate access keys, MQTT needs to know what rights the access key provides. Since the access keys are opaque, it consults an endpoint to fetch those rights:
GET /api/v2/applications/{app_id}/rights
Authorization: Key {app_access_key}
If the app id or access key is invalid, it should return 401
.
When successful, the enpoint should return:
200 OK
Content-Type: application/json
[
"messages:up:r",
"messages:down:w"
]
The meaning of rights returned here are:
messages:up:r
: The right to read the uplink messages from devices an applicationmessages:down:w
: The right to send the downlink messages to devices of an application
The presence of these rights tells the MQTT plugin what type of messages allow the client to see or send.
Important Note: due to the limited right management of our MQTT auhtentication implementation, make sure to always return either both rights or none, only returning one will have the same result as returning no rights.
2. JWT access token generation
All management features of the handler require application access tokens. These are JWT tokens that the handler can validate without contacting the account server. To implement these, you need a couple of things:
- A public-private key pair to sign the JWTs
- An endpoint where the handler can fetch the public key.
- JWTs that are signed using the private key, and have claims that adhere to the correct schema.
The handler fetches the public key on startup by performing the HTTP request:
GET /key
which should return:
200 OK
Content-Type: application/json
{
"algorithm": "RS256",
"key": "------- BEGIN PUBLIC KEY ------ ...."
}
The schema of the token claims should be:
{
"iss" : string issuer ID of your account server
"iat" : number seconds since unix epoch from when the token should be considered valid
"exp" : number seconds since unix epoch till when the token will be considered valid
"type" : "user" denotes that the token is for a user
"scope" : [ string ] the list of entities this token is valid for
"apps" : { string: [ string ] } an object that maps app id to the respective rights this token has for that app
}
So for instance, the following token:
{
"iss": "my-account-server",
"iat": 1489678139,
"exp": 1489688139,
"type": "user",
"scope": [ "apps:foo" ],
"apps": {
"foo": [
"settings",
"devices"
]
}
}
gives the token the right to edit settings and manage devices for application
with id foo
. The token is valid from 2017-03-16T15:28:59Z
until 2017-03-16T18:15:39Z
.
To validate it, the handler will consult it’s configuration and look if it knows
an account server with the ID my-account-server
, and validate the token with
the public key it got from its /key
endpoint.
The available rights for an application access token are the following:
settings
: Manage application settings on the handlerdelete
: Unregister/delete the application on the handlerdevices
: View and edit devices of the application on the handler