Documentation

Server Side Connect Filtering

Server Side Connect Filtering allows the basestation to perform coarse grained authorization of clients when they try to connect to devices: Either through a simple API-like mechanism with a static key shared among clients. Or through two more powerful token based approaches. The token based approaches are effective ways 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. 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 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

On the device, the token should be generated using nabto_device_create_server_connect_token, but can in principle be any string. The token is passed to the Nabto basestation using nabto_device_add_server_connect_token.

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, JWT authentication support must be enabled through the Nabto Cloud Console: Go to “Apps”, create an app or click “settings” on an existing app, add the app to the product in question, and select JWT as the “authentication type”. 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. When using JWT, the “server key” of the app configured in the previous step must similarly be passed to the basestation using nabto_client_connection_set_server_key.

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.

Server Key Authentication

With this approach, a Server key is added to the product which clients must present to the Nabto basestation when connecting. This is similar to the SCT approach, however, with this approach all clients using the common server key will be allowed connect to all devices in your product. Since all customers of a product share this single key, it cannot be considered secrect - meaning it does not provide protection against DoS attacks on devices.

Server Key Basestation Configuration

Similarly to JWT based authentication, this must be enabled through the Nabto Cloud Console: Go to “Apps”, create an app or click “settings” on an existing app, add the app to the product in question, and select “SERVER_KEY” as the “authentication type”.

Server Key Client Configuration

The Server Key of the “App” created in the previous section must be passed to the basestation using nabto_client_connection_set_server_key when attempting a remote connection to the device.