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 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 Connectware with a
username that does not yet exist. 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 assign 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 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. 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 at 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. Connectware subsequently deletes all the temporary information.
For security reasons, the register endpoint on 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).
Notes:
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.
When sending a CSR the CN of the CSR and the username in the payload must not be empty and CN and username should match, otherwise the confirmation request will be rejected.
Granting Access¶
This assumes a self-registering MQTT client is running and requesting access
On the navigation panel, click
User.
In the sidebar, click
Client Registry.
Press the lock icon in the toolbar at the top right, to open (unlock) the Connectware self registration. This self registration is open for 5 minutes. The self registration is closed again automatically after 5 minutes, or when the unlocked icon is clicked again.
The requesting client should appear in the table.
Click on the table entry to inspect the client request, then click
ALLOWto grant access
On the navigation panel, click
User.
The newly added user should appear in the Users table.
As a next step, click on the table row of the user, and assign one or more
Rolesaccording to the instructions here: Roles
API Definition¶
For the API Definition see the client-registry section of Auth Server Swagger