Authentication to Ably

We will use Ably JWT as an authentication mechanism for Ably. Out of all possible scenarios explained here, we’ve came to the conclusion that the following is most suitable for our use case(s) and requirements: 2.3 Ably JWT is created by your servers and passed to clients:

Notes

• Client uses the Ably JWT for all standard communication with Ably

• There is no communication between neither the Client nor the IAM Service with Ably in regards to getting or generating the Ably JWT

• The token can be used only for requests to Ably, this requires a somewhat granular token management on the Client

Creating the Ably JWT

The JWT that should be created must be a JWS with the following requirements, in order to make it an Ably JWT:

• JOSE header must have:

  • kid parameter which has Key Name as the value - if the key is e.g. xVLyHw.4ry6xg:RFay_icM-GVwUzBJ-ir-eLu4MBWJlR14NiVz8Fzi9tI , then the corresponding value that should be set is xVLyHw.4ry6xg

• JWT Claim set must have:

  • iat field which represents time of issue in seconds

  • exp field which represents expiry time in seconds

  • x-ably-capability field that is the JSON text encoding of the capability:

    {
      "customer:CUSTOMER_ID": ["subscribe", "push-subscribe", "history"],
      "account:ACCOUNT_ID": ["subscribe", "push-subscribe", "history"],
      "broadcast": ["subscribe", "push-subscribe", "history"],
      "support:CUSTOMER_ID": ["subscribe", "push-subscribe", "history"]
    }

    where CUSTOMER_ID and ACCOUNT_ID should be replaced with the actual values:

    • CUSTOMER_ID will be part of the incoming request (set by the FE and verified by the IAM layer on the BE side, refer to this doc)

    • ACCOUNT_ID: customer can have multiple accounts and they can be listed by account-manager@/v2/account/by-customer-id/{ownerId}. All the id fields in the returned objects should be added to the above JSON as:
      "account:ACCOUNT_ID": ["subscribe", "push-subscribe", "history"],
      by replacing ACCOUNT_ID with id.

  • x-ably-clientId field that contains CUSTOMER_ID

An example of how this is done in JS can be found here.

Refreshing the Ably JWT

When the Ably JWT expires, the responsibility of refreshing the token lies on the Client. Specifically, the SDK uses the configured authCallback in order to get a new token.

More info on how the SDK can be configured can be found here and an example on how to refresh the token can be found here under “Token Authentication”. NB! - this specific code example demonstrates creating a new TokenRequest which is not the approach that we’ve opted for, instead the Ably JWT should be the result of this callback.

How clients get the Ably JWT

The IAM service should expose an endpoint with which the Client can receive their Ably JWT. This endpoint must be protected and it should be known who the specific user is.

The endpoint should be defined as /notifications/token and accept headers defined as in this document.