API Documentation

Security Tokens Guide

This documentation for developers describes the security tokens the Syncplicity application programming interface (API) issues and requires in various integration scenarios. Best practice is using this documentation to maintain confidentiality. Developers can risk exposing Syncplicity security tokens to attackers or make it easier for attackers to obtain them.

Confidentiality guidelines

The following are guidelines to integrate end-user user interface (UI) applications with Syncplicity and ensure confidentiality of user data.

  1. Store the API token in user browser or end-user device when possible.
  2. Avoid storing the refresh token in user browser or device. If you must, encrypt the token with an encryption key stored somewhere else. For example, stored on the application server.
  3. Never expose the application secret to the client device or browser. Run on the application server the second step of the Open Authentication (OAuth) 2.0 code grant, which requires passing this value to Syncplicity.
  4. Store the application secret on the application server.
  5. Never send the storage vault authentication (SVA) token to the application server or other servers outside of the customer network. Retrieve and save the token only in user browser or end-user device. Store it encrypted.
  6. Never send the SVA token to any of the Syncplicity APIs. The SVA token is only needed for authenticating calls to storage APIs implemented by storage connector services in the customer network.
  7. Store API and SVA tokens in UI applications in different storage spaces if possible.

Server-side applications might implement token security differently, generally by running in a trusted environment.

Glossary

Term Definition
OAuth 2.0 Open Authentication (OAuth) 2.0. This protocol is used to authenticate or authorize applications that integrate with Syncplicity and their users. See The OAuth 2.0 Authorization Framework.
Application key Identifier of the third-party application as defined by OAuth 2.0.
Application secret The secret (password) of the third-party application as defined by OAuth 2.0. Used with an application key to authenticate a third-party application.

API token or access token

A session token valid for a specified time (currently 85 minutes). It is obtained as a result of an OAuth 2.0 grant. Syncplicity implements two grant types:

  • A resource owner credentials grant typically is used by administrative tools, like data migration scripts, with a command-line interface that authenticates user by client secret key.
  • An authorization code grant typically is used by an end-user UI applications that authenticates user by user name and password.

Syncplicity does not implement OAuth 2.0 implicit credentials grant that doesn't require an application secret to authenticate a third-party application.

Refresh token A token obtained as a result of an OAuth 2.0 grant with an API token. Typically, it is valid for many days (currently 21 days). The token is used to refresh the API token without going through the same grant again, which means no user interaction.
Storage vault An on-premises installation of the Syncplicity storage connector service on top of storage owned and maintained by the customer. A storage vault may have an additional layer of SVA security that prevents anyone without special credentials from accessing the files in storage.
Storage connector A Syncplicity service installed and maintained by customers in their networks. It implements Syncplicity storage APIs on top of a standard storage solution. A storage connector together with underlying storage typically is usually referred to as a storage vault.
Storage vault authentication (SVA)

An optional authentication workflow enabled in some on-premises storage vaults. It provides an additional layer of security for the data stored in the protected storage vault. The main premise is having a customer-owned authentication flow outside of Syncplicity systems. So, there is no possibility for Syncplicity employees to access SVA user credentials, as the credentials are never sent to the Syncplicity orchestration framework in the cloud.

SVA token or SVA cookie A token or cookie obtained as a result of SVA. By default, these have a long expiration time, and you should protect them. An SVA token is tied to a specific end-user device. An SVA cookie is tied to a web browser.
SSO Single sign-on. Syncplicity supports various third-party SSO providers using Security Assertion Markup Language (SAML) and an identity provider (IdP). SSO can be used in an OAuth 2.0 flow to obtain an API token and in an SVA flow to obtain an SVA token.
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 administration tasks that run in a headless session. If provisioned, an application token is the only information required to log in a user using OAuth 2.0 resource owner credentials grant. You should protect this token.

Authentication flows

Due to how Syncplicity stores and protects data, two separate authentication and authorization flows may be required for users to access their data. All users must authenticate to Syncplicity orchestration (flow 1). The second is required only when the end-user must connect to one or more SVA-enabled storage vaults.

  1. The first workflow authenticates the user to Syncplicity orchestration. The user needs to authenticate and authorize via the Syncplicity API to access their data. The first workflow is implemented using OAuth 2.0. There are two grant types that Syncplicity supports:

    1. Resource owner credentials 
      grant, which also is known as grant-by-token, is used for server application integration. It doesn't require user interaction, which means there is no need to render any UI and prompt the user for user name and password. This grant usually is used for data migrations to Syncplicity storage that also act on behalf of different users. This grant type infers there is an application token, which can be provisioned for Syncplicity users, that can be used to authenticate the user instead of user name and password. Keep this application token safe.
    2. Authorization code grant, which also is known as grant-by-code, is used for end-user UI applications. It is required to display web UI for entering user name and password, either Syncplicity's form or SSO provider's form. This grant is useful for applications that interact with users and want to use Syncplicity storage in their workflows.
  2. The second workflow is SVA and required when the customer has enabled SVA in one or more storage vaults. The Syncplicity storage connector service implements it. When SVA is enabled, users go through this authentication flow before downloading or uploading files to the storage vault.

Implementing API keys and SVA tokens and two corresponding authentication flows keeps parts of the data key separate. Syncplicity maintains one part. The customer maintains the other. Ideally, both parts should meet only briefly in the storage vault for retrieving the file. They should not be kept together in a back-end system otherwise.

Types of apps that integrate via API

Typically, there are two types of applications that integrate with Syncplicity via its API.

  • Server-side, mostly command-line, tools that do some user data manipulations on behalf of users. For example, upload files or migration.
  • End-user UI applications, web and non-web, that let users interact with their Syncplicity storage.

Server-side applications usually are used by company administrators and run in a trusted environment. It may be acceptable to store both security tokens in one place, as this is assumed to be a secure environment. However, if the company network is not considered secure, do not use store credentials and tokens for any application.

UI applications that interact with users via public networks are more exposed to attacks. So, the remainder of this topic has guidelines for end-user UI applications.

UI applications can interact differently with Syncplicity API.

  • Web client-side, single page application (SPA). These applications have little or no interaction with back-end servers. They don't delegate calling Syncplicity API to these servers. Instead they call Syncplicity API directly from a user browser or application running on a user's device. This is the preferred approach for storing tokens safely. 
  • Server-side, classic web application. These applications must call Syncplicity API from their back-end servers. For example, for asynchronous processing, But they must have UI and allow users to log in to Syncplicity from the browsers or built-in web view.
  • Hybrid application, which combines both approaches. Some calls to Syncplicity API are issued from application back-end servers and others directly from the UI.

Hybrid applications

The following graphic illustrates the hybrid application case, when the UI application developer wants to store the API token in both the user browser or end-user device and on the application server. However, you must ensure the SVA token never leaves the user browser or end-user device.


Graphic descriptions

The following describes the authentication and authorization workflow illustrated in the preceding graphic. Cross-reference the labels in the graphic with those in the descriptions.

  1. For user login:
    1. Use OAuth 2.0 to authenticate and authorize specific user via Syncplicity API. For native application this requires building a web view in the application and navigating to specific URL. See OAuth 2.0 RFC for details.
    2. Save the received API token in the web application domain cache or secure device cache. Refresh this token with refresh token grant as necessary (1.e) using the refresh token stored on application server. You also can save the refresh token with the API token in the web application domain cache or device cache, but avoid this if possible, as the refresh token is valid longer than the API token (21 days vs 85 minutes).
    3. Save the API token on the application server.
    4. Save the refresh token on the application server.
  2. For Syncplicity API calls:
    1. Call Syncplicity API from the user browser or end-user device to do operations such as listing folder contents.
    2. If the API token is saved on the application server, the server also can issue Syncplicity API requests.
  3. SVA and retrieving SVA token (applies only to SVA-enabled storage vaults):
    1. Lets user log in to SVA-enabled storage connector and obtain SVA token. Client application must navigate to a URL on the storage connector and let user log in. This process is secure, as the interaction happens between the user browser or end-user device and storage connector and identity provider hosted in user company network.
    2. Save obtained SVA token in web application domain cache or other secure local cache in case of non-web client application. As interaction with storage connector happens in a browser in different domain, the browser does not allow application domain to access any information returned. There are two ways to overcome this browser security measure:
      1. For native client applications: host the web browser view in the application and read the SVA token from the final server response. In general, there is no problem with browser security, as native client applications usually request SVA token, which is returned as part of the redirect URL.
      2. For web applications that use SVA cookie, use window.parent.postMessage to retrieve SVA token in a parent window. Parent window is usually a window within application in its own domain. This mechanism is implemented in the storage connector, but only works with parent domains whitelisted by the customer. Whitelisting here works in conjunction with cross-origin resource sharing (CORS) rules the customer assigns to the storage API. That is, the domains whitelisted for this interaction usually  are the same domains whitelisted in CORS rules.
  4. For all storage connector calls (file upload and download, authorizing shared links):
    1. Use the saved API token to call the storage connector from the user browser or end-user device. If SVA is enabled, calls additionally require SVA token or cookie obtained in step 3.

Note on 3 and 4: SVA token is only transferred from the storage connector to the user browser or end-user device, and vice versa. This does not allow server-side file downloads or uploads from or to SVA-enabled storage. This is by design, as customers want to restrict back-end threats and ensure only authenticated users can access their data.