Identified clients
When a client is authenticated and connected to PUBQ, it is considered to be an authenticated client. While an authenticated client has a means to authenticate with PUBQ, they do not necessarily have an identity.
When a client is assigned a trusted identity, that is, a clientId, then they are considered to be an identified client. For all operations that client performs with the PUBQ service, their clientId field will be automatically populated and can be trusted by other clients.
For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a clientId that they are not assigned in their PUBQ-compatible token. They are unable to masquerade as another clientId.
Assign a clientId
There are three different ways a client can be identified with using a clientId:
- A client claims a
clientIdwhen authenticating with an API key. - A client is authenticating with a token issued for a specific
clientId. - A client claims a
clientIdwhen authenticating with a token that is issued for a wildcardclientId.
Identifying a client varies depending on whether they are authenticating with basic authentication or token authentication. Token authentication is recommended in most instances so that clients authenticate using short-lived tokens and do not have access to API keys.
Since you then control the clientId that may be used by any clients, all other clients can rely on the validity of the clientId in published messages and of members present in presence channels.
Basic auth
You can use basic authentication to allow a client to claim any clientId when they authenticate with PUBQ. As the assignation of the clientId is not handled by a server, it cannot be trusted to represent the genuine identity of the client.
Token auth
You can use token authentication to set an explicit clientId when creating or issuing a token. Clients using that token are restricted to operations for only that clientId, and all operations will implicitly contain that clientId.
For example, when publishing a message, the clientId attribute of the message will be pre-populated with that clientId. Entering presence will also implicitly use that clientId.
The following example demonstrates how to issue a PUBQ Token with an explicit clientId:
const rest = new Pubq.REST({ key: "q4D9G2.rGQK1W:9pWbndVJg50MaOPAapAx7LQ_zKw6YvXl2B" });
const response = rest.generateToken({ clientId: "John" });Unidentified clients
If no clientId is provided when using token authentication then clients are not permitted to assume an identity and will be considered an unidentified client in all operations. Messages published will contain no clientId and those clients will not be permitted to enter the presence set.
