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).

API Definition

POST /client-registry/register

Endpoint for self-registration of clients

Parameters

Name

Position

Description

Type

body

body

Responses

201 - Granted. The registration request has been confirmed, proceed to login

202 - Pending. The registration request has been accepted but needs to be confirmed. Try again later.

400 - Invalid Request.

409 - Conflict. Might indicate that a conflicting registration is pending or a conflicting user is already existing.

423 - Locked. The registration endpoint is currently not open. Try again later.

GET /client-registry

Receive a list of all pending registration requests

Responses

200 - OK

401 - Unauthorized

GET /client-registry/status

Return the current lock status of the registration endpoint

Responses

200 - OK

POST /client-registry/open

Open the registration endpoint temporarily

Parameters

Name

Position

Description

Type

body

body

Responses

204 - OK

401 - Unauthorized

POST /client-registry/lock

Lock the registration endpoint now. This will flush the internal request cache.

Responses

204 - OK

401 - Unauthorized

POST /client-registry/confirm

Confirm a single authentication request

Parameters

Name

Position

Description

Type

body

body

Responses

204 - OK

401 - Unauthorized

404 - Corresponding username not found

Granting access

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

  1. Navigate to user section.

  2. Go to the Client Registry tab and unlock the Connectware.

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

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

../_images/registry_agent_allow.png
  1. The newly added agent should appear in the Users tab.

../_images/registry_agent_added.png