Web service security

The DINGO-Stack implements OAuth2 functions to protect its BACnet web services. The DINGO-Stack has an internal authorization server for generating access tokens and functions to validate the access tokens.

OAuth2 is an authorization framework that enables applications (clients), like for example the DINGO-Manager, to obtain limited access to HTTP services, like the BACnet web services in the DINGO-Stack.

In short, the DINGO-Stack will generate a access token in exchange for a valid username and password, and this access token should then present in all requests to the BACnet web-service. See examples below.

Security setup

What follows is a quick guide to set up the security regarding the BACnet web-services. The security is set up under the Security tab in DINGO-Manager.

  1. First generate a new UUID (RFC 4122). The access token generated by the internal or external authorization server is specific for the UUID of the device. This means that an access token generated for one device can not be used for another. More on UUID can be found here.
  2. Then save the UUID.
  3. Then make sure that the internal authorization server is enabled.
  4. Specify a lifetime in seconds for generated access tokens (RFC 6750 and RFC 7519).
  5. Then save the changes.
  6. Choose a username and password, that will be used to obtain a access token (Resource Owner Password Credentials).
  7. Save the changes.
  8. Generate a private key, that will be used to sign the generated access tokens. This prevents tokens from being modified or used on other devices.

  9. Then make sure that HTTPS is enabled (Network tab in DINGO-Manager). When the security setup has proven itself to work as expected, the unsecure HTTP can be disabled.

  10. And finally restart the DINGO-Stack service, so that the security changes can be activated (General tab in DINGO-Manager).

Note: The internal authorization server on the DINGO device can currently only store one username and password pair.

Example

The request to get a token via the BACnet web services is issued with the POST method, which can NOT be issued from the address bar of a browser (because browsers use the GET method for browsing sites). Instead Fiddler can be used for testing POST, PUT and DELETE requests.

In the following example, please use the IP or OpenPort information of your DINGOs device. And use the username and password, that you have assigned to the DINGO device, by following the previous security setup.

Note: When requesting tokens and subsequently using them in secure requests, then always use the encrypted HTTPS protocol. Usernames, passwords and tokens can otherwise be intercepted by attackers.

Request token

The URL should be: https://192.168.1.32/bacnetws/.auth/int/token?alt=json

And the body of the request should be: grant_type=password&username=MyUsername&password=MyPassword&scope=auth config bacnet

Response

If authentication is successful, the response will contain a JSON object containing the access-token. The JSON object also specifies in seconds, when the token expires, according to the security setup.

{"access_token":"eyJ0eXA...ZGY4M2E=","token_type":"Bearer","expires_in": 86400}

Make secure BACnet web-service request

When we have a valid token, then we can make a secure BACnet web-service request. The token will be placed in the header of the request and shall have this format: Authorization: Bearer eyJ0eXA...ZGY4M2E=

Use the <Inspectors> in Fiddler to analyse the response.

Unauthorized request

If we do not use a token or the token is invalid, then the response will be an unauthorized error code.

Use the <Inspectors> in Fiddler to analyse the response.

When a token expires, a new token-request is made for a new token (see examples above). This can of course be done before the previous token expires, to always ensure a valid token. The recommended interval between token-requests is the expiration-time-in-seconds / 2 (the expiration time is defined in the security setup).

Tip: When a token has been provided, then secure requests can be made in a browser by using ModHeader plugins.

More on BACnet web-service security

This section contains some more advanced aspects of BACnet web-service security.

Client Credentials Grant

The previous sections have explained the token exchange by using the so called Resource Owner Password Credentials Grant, where the token is exchange for a username and password.

Another grant is also implemented in the BACnet web-services, called Client Credentials Grant. To use this, start be defining a Client ID and Secret in the security setup. The DINGO-Stack can currently only store one Client ID and Secret pair.

The request for a token is similar to the Resource Owner Password Credentials Grant, except that the grant_type is different and the Client ID and Secret are provided as Base64 encoded in a Basic authorization header.

Certificates

When the DINGO device boots, it will acquire an IP-address. The boot sequence will automatically create a HTTPS certificate, based on the IP. This HTTPS certificate is then used to secure the BACnet web-services. The HTTPS certificate is also signed by a CA certificate. If any certificate validation problems are encountered when using the secure BACnet web-services, then it is probably because the CA certificate is missing in the browser trusted certificate repositories or not loaded in the application environment, that is being used.

The same CA certificate is being used across all DINGO devices. The CA certificate can be downloaded from here: http://apps.control2net.com/apt/cloud/DinGoCA.pem

Once the CA certificate is downloaded, then it can be used or installed into the browser trusted certificate repositories. The following image shows how this is done in Google Chrome. When the certificate is installed, the browser needs to be restarted.

If the owner of the DINGO device has its own CA certificate, that he wants to use, then visit this advanced page.

Links

Here are links to more information on BACnet web-service security: