Token Based Access Control
Token Based Access Control serves two purposes: It allows the basestation to perform coarse grained authorization of clients when they try to connect to devices - only clients with a valid token are allowed to attempt to connect to the target device. This is an effective way to prevent denial of service (DoS) attacks on devices.
Signed tokens may allow a 3rd party to authorize a client to perform operations on the device: For instance, a 3rd party authorization service may grant admin access to a client, expressed as role information (claim) in a signed token. The device can then validate the signed token and allow the client to perform operations in the admin role.
Signed tokens and detailed claims are supported through JWT: The actual 3rd party JWT services are provided by the vendor, Nabto supports integration with these as described below. JWT and Nabto’s JWT integration also support coarse grained central authorization for DoS prevention.
If only coarse grained authorization is needed and if JWT is not already part of the solution design, Nabto provides an alternative with no external dependencies that is simpler to use: Nabto Server Connect Tokens.
SCT: Nabto Server Connect Tokens
This simple approach is part of the core Nabto platform and has no external dependencies. The embedded device application generates a random token and sends it to the Nabto basestation. When a client attempts to connect to the device, it must present a matching token:
It is all self-contained and implemented through simple Nabto Edge API calls in the embedded device and the client. The biggest challenge for the solution developer is passing the SCT from device to client. This can for instance be part of the client/device pairing process.
SCT Basestation Configuration
To use SCT in your solution, you must enable this authentication method on the product in question. In the Nabto Cloud Console, go to “Products”, click “Apps” and click “Edit” on the app in question and select SCT in the dropdown.
Change the app authentication type to SCT:
SCT Client Configuration
On the client side, the application must set the SCT prior to opening a connection. This can be done through the
ServerConnectToken field in the options document passed to
nabto_client_connection_set_options in plain C clients and
Connection.updateOptions on Android.
How to get the SCT to the client in the first place is up to the application developer. The pairing functionality provided by the Nabto SDKs can be used to retrieve the token from the device when the client is initially paired.
SCT Device Configuration
The application developer can either manage tokens manually using this function or use the pairing functions in the IAM module as provided by Nabto.
JWT Support In Nabto Edge
Nabto Edge supports JWT tokens directly and indirectly: The Nabto Client SDK directly supports connecting to the basestation using JWT tokens for client authentication. On the device side, there is no direct support for JWT - instead, the general Nabto Edge CoAP implementation can be used to transfer a JWT token to the embedded application which in turn can validate the token.
The two tokens are issued for two different audiences - the basestation audience and the device audience. This distinction prevents the basestation from impersonating a client and connecting to a device. The purpose of the basestation token is merely coarse grained, central authorization to prevent DoS attacks of the target device. Hence, if JWT is used for access control on the device, the second token must be issued also and provided to the device on the established connection.
The token for the basestation audience is issued and used as seen in the following figure:
And the token for the device audience is issued and used as follows:
In step 1.5 the Nabto Edge Direct connection is established to the device and is in principle ready to use.
On this established connection, a standard application level Nabto Edge CoAP request containing the JWT as the regular custom payload can be made from the client - this happens in step 2.2. The customer application handles the request and validates the token - and the permissions are extracted from the claim and associated with the connection state on the device.
JWT Basestation Configuration
First, enable JWT authentication support through the Nabto Cloud Console: Go to “Products”, click “Apps” and click “Edit” on the app in question and select JWT. Next, all the JWT fields must be filled out:
- JWT Issuer (
iss): Standard JWT claim as per the JWT RFC. It identifies the principal that issued the JWT and is matched against tokens forwarded by clients.
- JWT Audience (
aud): Standard JWT claim as per the JWT RFC. It identifies the recipients that the JWT is intended for and is matched against tokens forwarded by clients.
- JWT JWKs URI: The URI where the basestation can get the JWKs to validate tokens.
- JWT Nabto IDs claim: The name of the claim in a token in which to find the product ID and device ID that the token grants access to. It could e.g. be
custom:nabtoIds. The Nabto Basestation extracts the device and product id from this claim at connect requests and rejects the request if the target device does not match these.
JWT Client Configuration
The JWT token is obtained from an arbitrary JWT authorization service and passed on to the basestation as part of the connect sequence using
nabto_client_connection_set_server_jwt_token or one of the platform specific versions that take a full JSON options document, such as
Connection.updateOptions on Android.
JWT Device Configuration
As mentioned above, there is no direct JWT support in the Nabto Edge Embedded SDK. Instead, register a Nabto Edge CoAP handler as per the general CoAP documentation to validate a JWT token as payload.