Introduction
The goal of this guide is to explain to application developers what security tokens Syncplicity API currently issues and requires in various integration scenarios. As application developers can potentially expose Syncplicity security tokens to attackers (or make it much simpler to obtain them), it is important to follow this guide in order to maintain the principal of confidentiality.
Summary
Developers should follow these guidelines to successfully integrate end-user UI applications with Syncplicity and ensure the confidentiality of user data:
- API and refresh tokens should be stored in user browser or end-user device whenever possible. Storing them (especially refresh token) on application server is discouraged. If it is still required, these tokens should be encrypted with encryption key stored somewhere else.
- Server-side applications may implement token security in a different way (generally by running in a trusted environment).
Definitions
|
Term
|
Definition
|
|---|---|
| API token |
This is a session token that is usually valid for several hours (currently 85 minutes) and is obtained as a result of some OAuth 2.0 grant. Syncplicity currently implements two grant types:
|
| Application Token | Each user can provision a personal Application Token which may be used to authenticate in UI-less scenarios via API. This is especially useful for account admins tasks that run in a ‘headless’ session. If provisioned, Application Token is the only piece of information required to login this particular user and therefore it should always be kept safe. |
| OAuth 2.0 | OAuth 2.0 protocol. Explained in details in corresponding RFC document. Syncplicity API uses this protocol to authenticate/authorize applications that integrate with Syncplicity and their users. |
| Refresh token | This is a token that is also obtained as a result of some OAuth 2.0 grant together with API token. It is usually valid for much longer period of time (currently 21 days) and is used to refresh API token without going through the same grant again which means no user interaction. |
| SSO | Single sign-on. Syncplicity supports various third-party SSO providers using SAML protocol and an Identity Provider (iDP). SSO may be used both in OAuth 2.0 flow to obtain API token as well as in SVA flow to obtain SVA token. |
Authentication Flow
Due to the nature of how Syncplicity stores and protects data, there is an authentication/authorization flow required for users to access their data.
This workflow authenticates the user to Syncplicity Orchestration - user needs to do authentication/authorization via Syncplicity API to access their data. This is implemented using OAuth 2.0 protocol and there are two flavors (grant types) of it that Syncplicity supports:
- Resource owner credentials grant (also known as grant-by-token): used for server application integrations and doesn't require user interaction (i.e. there is no need to render any UI and prompt user for his username and password). This grant is usually used for various data migrations to Syncplicity storage that also act on behalf of different users. Important note: this grant type implies that there is an Application Token (which can be provisioned for Syncplicity users) that can be used to authenticate the user instead if his username and password. Keeping this Application Token safe is paramount.
- Authorization code grant (also known as grant-by-user): used for end-user UI applications and requires to display web UI for entering username and password (either Syncplicity own or SSO provider's form). This grant is useful for applications that interact with user and would like to use Syncplicity storage in their workflows.
Tokens Flow
Most of the applications that integrate with Syncplicity via its API can be divided into two types:
- Server-side (mostly command-line) tools that do some user data manipulations (e.g. files upload or migration) on behalf of users.
- End-user UI applications (web and non-web) that let users interact with their Syncplicity storage.
The first type of applications are usually used by company administrators, running inside a trusted environment, and not all of the principles outlined below are applicable. It may be acceptable to store both security tokens in one place, since this is assumed to be a secure environment. (Of course, if company network is not considered a secure place, then credentials and tokens should not be stored there for any type of application).
On the contrary, end-user UI applications that interact with users via public network are more exposed to various attacks.
UI applications could also have flavors depending on how they interact with Syncplicity API:
- Client-side / single page application (SPA) in case of web. These applications have no or little interaction with any backend servers. In any case they don't delegate calling Syncplicity API to these servers, instead they call Syncplicity API directly from user browser or application running on user's machine.
- Server-side / classic web application in case of web. These applications have a need to call Syncplicity API from their backend server (for example, for asynchronous processing), however, they still have UI and allow users to login to Syncplicity from the browsers (or built-in web view).
- Hybrid application, which combines both approaches, i.e. some calls to Syncplicity API are issued from application backend servers and some others directly from UI.