Documentation

Session Authentication

In addition to the public key authentication used by the pairing mechanisms, the Nabto Edge IAM module also supports authenticating an established session based on Password or OAuth 2.0 tokens.

Password Authentication

If a client performs password authentication after opening a connection, the client will be granted the IAM actions allowed for the user it authenticated as. This is the same mechanism as used with password based pairing, however, authenticating using the open pairing password only allows access to the Password Open Pairing.

Note: Password Invite Pairing is designed for the invite to be sent from the creator to the invited using a temporary password. For this reason, when the invited user completes the pairing process, the password will be removed from the user object. After password pairing, password authentication will not work until a new password has been set. It also removes the password if accepting an invite through the WebRTC demo.

OAuth Authentication

OAuth is a technology that can be used for centralized authentication and authorization in applications. Since OAuth specifics can vary between deployments, in Nabto Edge IAM, OAuth validation is done in an application level CoAP endpoint. After validation, the application authorizes the connection using the IAM API.

This section describes an approach to OAuth where the connection between the client and device is treated as an authenticated session. This means that the client authenticates its connection to the device and all communication occurring on the connection is granted the same permissions. This approach is different from what is often found in HTTP APIs where each request is accompanied by a Bearer token.

STSDeviceClientSTSDeviceClient Connect and validate the fingerprint of the device.Get an access token for the specific device.Authenticate with the access token.

Validating OAuth Tokens

OAuth Tokens are JSON Web Tokens with some claims. The JWT needs to be validated and then the audience in the token needs to be validated. The specifics about how to identify the user is application specific, but a good approach is to use the subject sub and issuer iss to identify the user on which behalf the token is created.

For the audience part, we suggest encoding the product id and device id of the device as nabto://device?productId=...&deviceId=...

The tokens will most likely be signed with a private key which has a corresponding public key. The public key is likely to be available as a JWKS on a https server. The public key needs to be refreshed inside the device often enough such that key rotations are practically possible.

Centralized Authentication with Decentralized Authorization

In many deployments it makes sense for all authorization decisions to be made inside the devices. This moves all the authorization decisions away from the central authentication/authorization systems to the end users device. This approach makes the device more autonomous and makes it easier to make an Authentication system for local connections when there is no Internet access. In such a system each user which needs access to the device have an user account in the device. The user is then linked to a central managed identity through an OAuth subject. This approach makes it possible for a user to control their devices from multiple client applications, such as smartphones, web interfaces or smart-home systems.

Centralized Authentication with Centralized Authorization

Sometimes it can be beneficial to move all authentication and authorization decisions away from the device. In such a system it is the central authentication and authorization services which decides what users has access to which devices and which roles/scopes they have access to on the device. In such a system the device does not need to maintain a user table, but just implement logic to validate OAuth tokens and assign permissions to the connections based on that information.

Local only access with centralized authorization

One drawback with centralized authorization is that it does not work if the client or device does not have Internet access, the client cannot obtain new access tokens, and the device cannot obtain the public key which is needed to validate the access tokens.

To enable access in scenarios without Internet, the centralized authorization system must be accompanied by a decentralized authentication and authorization system (eg. Pairing or Password authorization). However, such a system cannot reflect changes in the central authorization system.

Issuing OAuth tokens

When using OAuth for authentication or authorization it is required that a token used towards one device cannot be used towards another device. This is enforced by setting the audience claim in the token to match the device the token is sent to. This is often not possible with standard OAuth authorization servers as they often only supports a limited amount of audiences for their generated tokens.

A solution for this problem is to use a Security Token Service (STS) as defined in RFC8693. Such a service can take an access token and other parts as input and generate a new access token with a specific audience as output.

The tokens issued by the Security Token Service is used to gain access to the device. This means the Security Token Service must be a trusted party in the security system. The Security Token Service is also heavily dependent on the which OAuth authorization server created the token it uses as input. For these reasons, the Security Token Service is not a part of the Nabto provided cloud services for use in customer solutions.

However, Nabto can provide guidelines and reference material to help you implement and deploy your own Security Token Service. Also, Nabto hosts a demo STS implementation to make it possible to run all the Nabto Edge WebRTC demos without worrying about this.

A Security Token Service as defined in RFC8693 is in it simplest form a service which takes in a token and returns another token.

Example Security Token Service request:

curl -X POST <sts_url> \
  --data-urlencode "client_id=<input_oauth_client_id>" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token=<input_token>" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "resource=nabto://device?productId=<input_product_id>&deviceId=<input_device_id>"

Example Security Token Service response:

{
  "access_token":"JWT encoded access token",
  "issued_token_type":
      "urn:ietf:params:oauth:token-type:access_token",
  "token_type":"Bearer",
  "expires_in":60
}