Secure and Scale Programmable Chat Applications

Twilio Chat consists of two main components: REST APIs (back-end) and Client SDKs (front-end).

The back-end and front-end (client) components of chat applications need to be considered and handled separately from a security point of view. Let's start with discussing the mechanism for securing the back-end.

The back-end application makes requests to Twilio's Chat REST API which uses basic HTTP authentication. As with all of Twilio's REST APIs, the Twilio Account SID and Auth Token can be used as the username and password respectively. However, for Programmable Chat, we recommended using API Keys.

Here is an example back-end chat request using API keys:

1
curl -G https://chat.twilio.com/v2/Services \
2
   -u '[YOUR API KEY]:[YOUR API SECRET]'

API Keys are used both to authenticate to the REST API and to create and revoke the Access Tokens used by Chat clients. API Keys can be provisioned and revoked either via the REST API or the Twilio console. These tools offer fine-grained control over the developer and application access to the Chat REST API.

Note: When handling API keys, ensure you follow these two critical points:

• API keys must be stored and handled with the same care as any other secret (for example, passwords and tokens for other third-party APIs and services).
• API Keys and Twilio's REST APIs should only be used by the back-end application. API Keys & REST API Tokens should never be sent to or embedded in the client application. Additionally, you should never embed your API key directly in your source code or push it to a repo. If an API Key is available to a client, it could be obtained by an end user who will then have API-level access to your Twilio account.

The Chat Client SDKs authenticate using Twilio Access Tokens. Unlike API Keys, Access Tokens are short-lived tokens granted by your application to give a client access to a Chat Service Instance for a defined amount of time.

The maximum lifetime of an Access Token can be up to 24 hours, but best practice is to limit them to the shortest amount of time feasible for your specific Chat application.

Your back-end application is responsible for authenticating the end user to ensure that they should have access to the Chat Service Instance. Your application can then make a REST API request to Twilio to grant an Access Token for the client.

The Access Token contains two pieces of information:

• User's Identity
• Chat Grant that specifies the Service Instance SID this user can connect to

The application then passes the Access Token back to the client (for example, via Ajax). The Chat client SDK will then provide this Access Token on requests to Twilio.

Expand image

As a result of this process, Twilio keys do not need to be stored in the client application. Also, your client authenticates using the generated access token, as follows:

const chatClient = new Twilio.Chat.Client('the token string from server');

These tokens are based on the JSON Web Token standard (JWT). For troubleshooting purposes, you can paste a token into https://jwt.io/, and it will decode the token for you. This helps confirm that the values encoded in the token are correct.

Finally, if the Client needs uninterrupted access to the Chat Service, Access Tokens need to be renewed before they expire. This can be done using the client's updateToken method, but Twilio also has an optional helper, AccessManager, that can manage the renewal process.

Programmable Chat considers a back-end application that uses the REST API and authenticates via API Keys a "trusted" application. On the other hand, the client is considered "untrusted" and so requires extra security precautions such as time-limited Access Tokens for client access to Chat.

Roles and Permissions are also a critical component to "trust." Default service-level and channel-level roles are set up within Twilio Chat and can be assigned to give either Admin-level or User-level rights to each User within the Service Instance.

While permissions defaults work well for out-of-the-box Chat applications (for example, prototype/proof of concept), you need to review the permissions granted to each User within a production Chat application.

You can use the Roles resource to check the permissions and roles for any instance:

1
curl -X GET 'https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles' \
2
-u AC235fc1b3aa3cf4ec101177b6b49d76f0:your_auth_token

For example, should a new User connecting to customer service Chat via the browser be allowed to create new Channels?

You might think that if your client UI doesn't offer a feature to create channels, then Users wouldn't be able to do that. However, a savvy User with developer experience may be able to access the underlying client SDK and perform unwanted operations granted by their User Role.

Therefore, Twilio's recommended best practice for Roles is to create custom Roles for your production application that grants the absolute minimum Permissions required for each User role.

In addition to the concept of minimally-provisioned roles, Twilio recommends that your back-end application orchestrates all channel creation via the REST API (where the use case allows for that) rather than granting channel creation privileges to untrusted client users.

As an example of how someone might exploit channel creation privileges, imagine a scenario where a client user initiates unwanted chats targeting individual agents or groups.

Chat data, particularly Message and Member data associated with Channels, persists forever by default unless the individual Messages or the entire Channel is deleted. This data retention has implications for both the security and performance of your application.

Security - General security best practice is to retain only the data you need and to store that data only where you need it.

Performance - Initializing a Chat client causes it to read Channel and Member data from the Chat Service. If over time that User becomes a Member of more and more Channels with more Message data in each channel, this can significantly impact Client initialization time as well as the general performance of other client SDK methods.

Twilio recommends that when designing the Chat application architecture you consider at what point Chat information should be archived or deleted. This decision is typically tied to the required lifecycle of a Channel.

An example of a Channel lifecycle might be as follows:

1. End-user requests Chat session via a web browser.
2. A user is placed in a newly-created Channel with a customer service Agent.
3. Chat session completes.
4. The application retrieves Message history from the Channel via the REST API and stores it in a CRM system.
5. Application deletes Channel, removing all history from Twilio's platform.

Additionally, you may want to consider your particular use-case and customer base:

• Any PII shared via Chat?
• PHI?
• Are any of your Chat users EU citizens who are protected by GDPR?

Be thoughtful as you consider your application's data retention.

A few steps are required to get push notifications working for Programmable Chat.

1. Push must be explicitly enabled as it is disabled by default on all Chat Service Instances.
2. Specific events for iOS (via APN), for Android, and for browsers (via GCM/FCM) support Programmable Chat push notifications.
3. Use the Chat console to provision Apple Developer credentials for iOS pushes. Use FCM push credentials for provisioning Android and browser push notifications. Before Twilio Chat provisioning can be completed, you need to configure both APN and FCM credentials with Apple and Google respectively.

When architecting your Chat application, make sure you consider what level of management functionality you need to build for system administration.

While individual Channels and Users can be created and deleted by the core application business logic, administrators may need additional insights into usage of a Chat Service Instance. These insights include, for example, a detailed breakdown of Users, Channels and Messages, and the ability to modify or remove Chat objects directly.

Some of these actions can be performed via the Twilio console but administrators often may not, or should not, have access to the console.

An admin interface can be a great solution to this requirement.

When using Twilio Programmable Chat, your Users' communications are being handled and stored by Twilio.

It's best practice, and it's a law in many jurisdictions, to ensure that you have a User's consent for this before making use of a service based on Programmable Chat. Twilio recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you transmit using Twilio.