API Documentation

Authentication & Authorization via OAuth 2.0

Here's the definition of OAuth 2.0 from the OAuth 2.0 IETF specification itself:

"The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf."

The main thing you need to know is that OAuth 2.0 provides a way for apps to gain limited access to a user's protected resources (think of bank account or any other sensitive information a user might wish to access from an app) without the need for the user to divulge her login credentials to the app. There are many books, blogs, and sites devoted to OAuth 2.0. We highly recommend that you begin by reviewing the IETF OAuth 2.0 specification.

 

The OAuth 2.0 Flow

Here is the general flow for the OAuth 2.0 security framework. We'll discuss this flow in more detail in this topic, starting with a diagram, which illustrates a lot about how OAuth 2.0 works. If you're unfamiliar with the terms used in this diagram, read this section for a quick introduction.

Terms you should know:

  • Client (App): It can be an app running on a mobile device or a traditional web app or a command line tool. The app makes requests to the resource server for protected assets on behalf of the resource owner. The resource owner must give the app permission to access the protected resources.
  • Resource owner (end user): This is generally the person (or another entity) who is capable of granting access to a protected resource. For example, if an app needs to use data from one of your social media sites, then you are the resource owner and the only person who can grant the app access to your data.
  • Resource server (Syncplicity service): The resource server needs some kind of authorization before it will serve up protected resources to the app. Syncplicity API Gateway also acts as a resource server whenever OAuth token validation is required to process API requests.
  • Authorization server (API Gateway): The authorization server is implemented in compliance with the OAuth 2.0 specification, and it is responsible for validating authorization grants and issuing the access tokens that give the app access to the user's data on the resource server. You can configure "token endpoints" on API gateway, in which case gateway takes on the role of authorization server.
  • Authorization grant: Gives the app permission to retrieve an access token on behalf of the end user. OAuth 2.0 defines four specific "grant types". See OAuth grant types supported by Syncplicity APIs below.
  • Access token: A long string of characters that serves as a credential used to access protected resources. Access tokens (also called bearer tokens) are passed in Authorization HTTP header, like this:
    • Authorization: Bearer $access_token
  • Protected resource: Anything sensitive owned by the resource owner. For example, the users & groups data, policies, files and folders, etc.

 

Supported Grant Types

Think of grant types as different paths or interactions an app can take to gain an access token. Each grant type addresses one or more use cases, and you'll need to select which grant type(s) to use based on your own needs. In general, each grant type has advantages and disadvantages, and you'll need to weigh the tradeoffs based on your business use cases.

Syncplicity API Gateway supports "client credentials" OAuth 2.0 grant type only. This grant type is best suited for client apps that are expected to act on its own behalf without requiring end user interaction. For e.g. an administrative tool that runs as a service and provisions users & groups to the Syncplicity company direction. In this case, the client is also the resource owner. With this grant type, an app can receive an access token by presenting its client ID (App Key) and client secret (App Secret) keys to the authorization server located at https://api.syncplicity.com/oauth/token.

 

Implementing the "client credentials" OAuth flow

With the client credentials grant type, an app sends its own credentials (the App Key and App Secret) to a /oauth/token endpoint on Syncplicity API Gateway. If the credentials are valid, the gateway returns an OAuth access token to the client app.

 

Step 1. Obtain Syncplicity Application Token from sandbox account

Before you call the OAuth you need to have the Syncplicity Application Token handy for a given administrator user account that will be used for accessing the protected resources via API. In order to the Application Token, follow the steps below:

  1. Login to your sandbox account. In case you have more than one user accounts created in your sandbox, make sure you are logging in as the user who has either "support administrator" or "global administrator" role. For more information on these roles, please read about administrator roles.
  2. Go to Account page and if you haven't already, create an Application Token within the profile section. See the screenshot below for more clarity.
  3. Copy the Application Token string so that you can use it in the next step. For e.g. Application Token: tjDminDmoxesw2zJ/tOtfXO2VOKhGp+dtiANDhcs+kSjJmb6H3G5DmNokgwup8TH.

 

Step 2. Client requests an access token

To receive an access token, the client app must POST an API call to Syncplicity API Gateway with the following fields:

  • HTTP Headers
    • Sync-App-Token: The value of this header is the Syncplicity Application Token obtained from the user's account profile as described in Step 1.
    • Authorization: The value of this header is 'Basic base64Encode(AppKey:AppSecret)'
    • Content-Type: application/x-www-form-urlencoded'
  • Parameter
    • grant_type=client_credentials

As you may recall, the App Key and App Secret keys are automatically generated by the Developer Portal when you register your app in the portal. In order to generate the base64 encoded string from App Key and App Secret keys, you can use free tools such as https://www.base64encode.org to encode the App Key and App Secret keys together with colon separating then.

Base64encodedString = aBase64EncodeFunction(AppKey:AppSecret)

 

For e.g. Let's say the App Key and App Secret keys for our Sample App are "0GgAfBSsubFL4gsyTvBGaCkKWKb5GA32" and "mnPbr82mqQbYFhFf" respectively. Then the resulting base64 encoded string would be like this:

Result = aBase64EncodeFunction(0GgAfBSsubFL4gsyTvBGaCkKWKb5GA32:mnPbr82mqQbYFhFf)

The result of base64 encoding the above string is: MEdnQWZCU3N1YkZMNGdzeVR2QkdhQ2tLV0tiNUdBMzI6bW5QYnI4Mm1xUWJZRmhGZg==

 

Here is a screenshot from https://www.base64encode.org showing the same operation for reference:

 

Here is a sample access token request using cURL:

$ curl -X POST https://api.syncplicity.com/oauth/token -H 'Authorization: Basic MEdnQWZCU3N1YkZMNGdzeVR2QkdhQ2tLV0tiNUdBMzI6bW5QYnI4Mm1xUWJZRmhGZg==' -H 'Sync-App-Token: tjDminDmoxesw2zJ/tOtfXO2VOKhGp+dtiANDhcs+kSjJmb6H3G5DmNokgwup8TH' -d 'grant_type=client_credentials'

 

Step 3. API Gateway validates the credentials and returns a response

Note that the API call is sent to the /oauth/token endpoint. This endpoint has a policy that compares the submitted keys with the ones that Developer Portal created when the app was registered. If the credentials are okay, gateway returns an access token to the client. If not, an error is returned.

Here is a sample response for the token request using cURL (shown above):

{  
   "issued_at":"1430376762922",
   "client_id":"0GgAfBSsubFL4gsyTvBGaCkKWKb5GA32",
   "token_type":"BearerToken",
   "access_token":"T6CDmMP69dSoWI6EAtqLjVLIJvWj",
   "expires_in":"1499",
   "scope":"readwrite read",
   "application_id":"53bf8383-6b3b-4980-806d-2e3e62717ecd",
   "user_company_id":"45b024b0-152a-4686-a714-13542937defc",
   "user_email":"",
   "organization_id":"0",
   "organization_name":"MyCorp"
}

 

Here is a description of the fields shown in the sample response above:

Field Description
issued_at Time since epoch when the access token was issued.
client_id App Key for the app used for requesting access token.
token_type OAuth token type. We currently only support "bearer" token type and do not support "mac" token type.
access_token This is OAuth access token that you will need to use in the subsequent call to access protected APIs.
expires_in Time in seconds for the access token is valid. Typically, you would refresh your access token before it expires.
scope List of one or more scopes associated with the access token issued. application_id GUID of the app registered in the Developer Portal.
user_company_id GUID of the Syncplicity Enterprise Edition account that was authenticated against using the Syncplicity Application Token.
user_email Email of the user who was authenticated. For "client credentials" grant type, this field is not relevant.
organization_id GUID of the Syncplicity Enterprise Edition account.
organization_name Name of the Syncplicity Enterprise Edition account.

 

Step 4. The client app calls the protected API

Now, with a valid access token, the client can make calls to the protected API endpoints. In this scenario, requests are made to the API Gateway, and the API Gateway is validates the access token before passing the API call along to the target protected API endpoints.

For example, say you want to make an API call to GET user information for user@domain.com using the access token "T6CDmMP69dSoWI6EAtqLjVLIJvWj" granted in step 2. Here is how the request and response would look like when using CURL:

Request:

$ curl -X GET https://api.syncplicity.com/provisioning/user.svc/user@domain.com -H 'Authorization: Bearer T6CDmMP69dSoWI6EAtqLjVLIJvWj' -H 'AppKey: 0GgAfBSsubFL4gsyTvBGaCkKWKb5GA32' -H 'Accept: application/json'

Response:

{  
   "Id":"42dc319d-35ae-43a6-8516-6d3c9eb5a40b",
   "EmailAddress":"user@domain.com",
   "FirstName";:"Firstname",
   "LastName":"Lastname",
   "AccountType":7,
   "CreatedDateUtc":"\/Date(1430378231080)\/"
}
    

 

Refreshing client's access token

The Access tokens have an expiration for security reasons. When using the "client credentials" grant type, the client app can refresh the token by executing steps 2 - 3 again. In this case, the API Gateway issues a new access token. The client app is responsible for tracking when the access token is going to expire using the "expires_in" field returned in the Access Token request made in step 2.