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

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