Securing your Sync App
Sync provides useful, efficient, and professionally-operated primitives to light up your apps in the browser and on mobiles. As with any Twilio product, these conveniences come together with a ready solution for security and access control.
In any Sync application, you have two levers of control that determine which SDK clients have access to what data. The first is the Access Token issued by your backend and secured by your method of choice. The second is the Sync Permissions API, which serves to further identify which tokens give access to which Sync objects. By using these two levers together, your users will be protected while Sync delivers the real-time liveness they expect and require.
The following is a guide to using these levers properly to secure your app before you go to production.
The ACLEnabled Flag, a Boolean value configured on your Sync Service Instance, determines whether token identities are used for access control. When ACLEnabled is unset, token identities are essentially ignored. In this case, the actor behind every Sync action is still visible in webhooks, for example, but it has no functional impact on your application.
Operating with ACLs disabled is ideal for experimentation and prototyping. Among other things, it's possible to operate entirely without backend server support in this mode. We encourage you to consider this "development mode" for any Sync-based project.
Twilio Access Tokens are your application's primary defense against unwelcome users. When getting started, it's convenient to issue tokens to all comers (as our Quickstart guides recommend) — and for some use-cases this can be your modus operandi indefinitely. In particular, if you're providing Sync-driven features to a public, anonymous audience, issuing tokens to unknown actors is common and reasonable.
If, on the other hand, your users are known, then you should be sure to authenticate them before issuing a token that authorizes access to your Sync app. When doing so, make sure to provision your token with a corresponding identity string. Keep in mind that Twilio strongly recommends not to put personally identifiable information (names, phone numbers, etc.) in this field; we advise a UUID or a hash.
The token identity you provide here will be useful later when you secure your application with the help of the REST API.
Once you move past the stage of prototyping or validation, it's time to think about securing your app. When the ACLEnabled flag is set, your backend will have to have explicitly allowed SDK-based clients read, write, and/or management access to shared objects. This means you'll have to consider:
1. How much do you trust your clients, specifically those on browsers or mobiles? Consider the risk of software bugs as well as nefarious users.
2. To what does each client need access? Do they need shared write access, or is shared read sufficient?
As a rule, shared-write privileges among SDK-driven endpoints create a significant risk for your application. Your token-issuing authority is your first line of defense against rogue SDK endpoints, but this will not always help defend against stolen credentials. Furthermore, the risk of buggy implementations is ever-present.
By contrast, one-to-many synchronization via your REST backend is generally safe. Where SDK-based clients need to communicate their own state, you should consider sharing such objects only with your backend and reflecting those changes towards other SDKs. With this organization, you will have the possibility to detect or intercept misbehaving clients in your backend and react accordingly. If endpoints in your system must be considered untrusted, we recommend something along these lines.
The exceptional case, in which the model of shared-write may be acceptable, is one in which you have high trust in your client endpoints or in which the shared data is sufficiently non-critical. For example, online/offline status among employees in a medium-sized company is not likely as high-risk as the same information shared with public users. In a call center, for example, the assignment of agents to customers is actually rather important, as programming errors may lead to consternation; but the greater risk in this case may be programming errors, not malicious agents.
With ACLs enabled:
- By default, an object created by an SDK endpoint will only be accessible by other endpoints with the same token identity.
- By default, An object created via the REST API will be inaccessible to all SDK endpoints.
- Your backend services, accessing Twilio over REST, always have full access to everything.
- Your backend services can allow (and subsequently disallow) access to objects by arbitrary identities, one-by-one.
Allowing of individual identity-object pairs is possible via the Sync Permissions API, accessible from your backend services. You will need to do this for any object not shared exclusively between an SDK object-creator and your REST backend.
Enabling ACLs is an important step. Where possible, we suggest testing your application with ACLs enabled on a separate Sync Service Instance serving as a development environment.