Client Registry

In many situations, external clients must be enabled to connect to Cybus Connectware automatically. The exchange of credentials is a crucial step in the pairing process.

As a first thought, one might tend to explicitly create a user with a corresponding password and set this password manually on the client in question. However, this process is both cumbersome and contains security risks, because pre-shared credentials need to be carried around. It is much better to have credentials exchanged automatically in the background without any administrator interaction.

The solution is to use Connectware’s Client Registry process, which provides a secure and easy way to register new clients and users at the Connectware for subsequent data access.

The client registry process (also referred to as self registration) can be used either in implicit form with any MQTT client, or in explicit form for clients that use the REST API. This process needs to be performed e.g. when setting up the credentials for data sources to send data to the Connectware, or when the credentials for distributed Connectware agents need to be registered at the central Connectware instance.

Implicit Flow

Implicit client registration will work for any MQTT client.

The first step is that the client tries to connect to the Connectware with a username that does not yet exist. The Connectware will reject this connection request as usual. However, if the client registration endpoint has been opened (unlocked) before, these connection requests will be shown in the Client Registry section of the Admin Web App. The administrator can then grant access to this client. This will automatically create a user with the name and password received through the connection request. Note: This newly created user will have no initial permissions, hence the administrator will need to assigns permissions to this user as the next step.

The benefit of this process is that no manual password handling is required. The client can easily generate a random password on its own.

Note: The user name must be at least 3 characters long, and the password at least 5 characters long, otherwise the registration request will be refused.

Explicit Flow

More sophisticated clients can issue requests to the client registration REST API. These requests may contain further information like client context, requested roles, permissions or certificate signing requests.

Client            Connectware        Administrator
   │                    │                 │
   │ Register (creds)   │                 │
   ├────────────────────▶                 │
   │ locked (423)       │                 │
   ◀────────────────────│      open       │
   │                    ◀─────────────────┤
   │                    │                 │
   │ Register (creds)   │                 │
   ├────────────────────▶                 │
   │ pending (202)      │                 │
   ◀────────────────────│                 │
   │                    │                 │
   │                    │                 │
   │ Register (creds)   │                 │
   ├────────────────────▶                 │
   │ pending (202)      │                 │
   ◀────────────────────│                 │
   │                    │                 │
   │                    │     grant       │
   │                    ◀─────────────────┤
   │                    │                 │
   │ Register (creds)   │                 │
   ├────────────────────▶                 │
   │ granted (201)      │                 │
   ◀────────────────────│                 │
   │                    │                 │
   │                    │                 │
   │ Login (creds)      │                 │
   ├────────────────────▶                 │
   │ JWT Token          │                 │
   ◀────────────────────│                 │
   │                    │                 │
   │                    │                 │
   ▼                    ▼                 ▼

The client sends a registration request to the Connectware containing the credentials to register and the permissions to set. The credentials can either be a username/password pair or a username/CSR pair. The Connectware stores this information in memory and responds with a “pending” notification (202). Important: because there is no return channel except the direct HTTP response, the client must repeat the registration request regularly until a positive (“granted”) response is received.

It is the responsibility of the administrator to grant the registration request by an explicit command. Only then the credentials are persisted to the database. In the case of a CSR, the certificate will be signed in this moment. The next register request by the client will carry a positive response (201) which includes the signed certificate if applicable. After this, the client does not need to and should not send requests. The Connectware subsequently deletes all the temporary information.

For security reasons, the register endpoint on the Connectware is closed (locked) by default and must explicitly be opened (unlocked) by the administrator. The endpoint can only be opened temporarily (e.g. for 5 minutes). When the endpoint is closed, all registration requests will receive a locked response (423).

Note: The user name must be at least 3 characters long, and if a password is used it must be at least 5 characters long, otherwise the registration request will be refused.

Granting access

This assumes a self-registering MQTT client is running and requesting access

  1. On the navigation panel click on User Management to expand the menu.

../_images/sidebar_1.png
  1. Click on the Client Registry menu item.

../_images/client_registry_menu.png
  1. Press the lock icon in the toolbar at the top right, to open (unlock) the Connectware self registration. This opens the self registration and keeps it open for the time interval of 5 minutes. The self registration is closed again automatically after 5 minutes, or when the unlocked icon is clicked again.

../_images/registry_landing.png
  1. The requesting client should appear in the table.

../_images/registry_agent_request.png
  1. Click on the table entry to inspect the client request, then click ALLOW to grant access

../_images/registry_agent_allow.png
  1. Go to the Users menu.

../_images/sidebar_2.png
  1. The newly added user should appear in the Users table.

../_images/registry_agent_added.png
  1. As a next step, click on the table row of the user, and assign one or more Roles according to the instructions here: Add role to user

API Definition

For the API Definition see the client-registry section of Auth Server Swagger