Self Registration

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. Trivially, it is possible to explicitly create a user with a corresponding password and set this password manually on the client in question. This process is both cumbersome and contains security risks, because pre-shared credentials need to be carried around. In the best case, credentials would be exchanged automatically in the background without any administrator interaction.

Implicit Flow

Implicit self-registration will work with any MQTT client. It assumes that the client tries to connect with a non existing user, which will reject the connection request. However, if the self-registration endpoint is open, these connection requests will shown in the client registry section and may be granted through the Admin Web App. This will automatically create a user with the name and password received through the connection request. Note however, that this user will have no initial permissions.

The benefit is, that no manual password handling is required; the client can easily generate a random password on its own.

Explicit Flow

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

Client            Auth Server           Admin
   │                    │                 │
   │ 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 auth server 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 Auth Server 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 auth server deletes all temporary information.

For security reasons, the register endpoint on the auth server is closed by default and must explicitly be opened 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).

Granting access

This assumes a self-registering agent is running and requesting access

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

../_images/sidebar_1.png
  1. Go to the Client Registry menu.

../_images/client_registry_menu.png
  1. Press the lock icon in the toolbar to unlock the Connectware self registration.

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

../_images/registry_agent_request.png
  1. Click on the table entry to inspect the agent and grant access

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

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

../_images/registry_agent_added.png

API Definition

For the API Definition see User Management