OAuth in Component.json

This technical reference describes the changes required in component.json in order for the component to handle the OAuth authentication protocol

OAuth1

Specifies OAuth 1.0 specific details of the API used by the component. For more details about Authenticating with OAuth 1.0 refer to the OAuth 1.0 specification standard.

Property Name Type Required Description
consumer_key string Yes The Consumer Key
consumer_secret string Yes The Consumer Secret
request_token_uri string Yes URI to get a Request Token
auth_uri string Yes URI to get User Authorization
access_token_uri string Yes URI to get an Access Token

Here is an example implementation of OAuth1 in the Credentials Object:

{
  "credentials" : {
    "fields": {
      "oauth": {
        "viewClass":"OAuthFieldView",
        "label":"Twitter Account",
        "required" : true
      }
    },
    "oauth1":{
      "consumer_key":"",
      "consumer_secret":"",
      "request_token_uri":"https://api.twitter.com/oauth/request_token",
      "auth_uri":"https://api.twitter.com/oauth/authorize",
      "access_token_uri":"https://api.twitter.com/oauth/access_token"
    }
  }
}

In case of OAuth1 Authentication we must use fields and oauth1 objects together. The fields object defines the input field type and the oauth1 object provides the configuration. Please note that the viewClass property of the field must be set to OAuthFieldView.

OAuth2

Specifies OAuth 2.0 specific details of the API used by the component. For more details about Authenticating with OAuth 2.0 please read the OAuth 2.0 specification.

To use an OAuth2 based Component in the platform it is required to register a client at the authorization server. After registration the authorization server issues the registered client an identifier (client ID) and a secret. These client credentials are used to create a client using the corresponding API calls. Auth clients can be created on any level: tenant, contract or workspace which incapsulate each other (in order), i.e client created on tenant level is available to use for creating secrets in any workspace of the tenant. You can find all information about the required API endpoints in the API documentation.

Property Name Type Required Description
client_id string Yes The Consumer Key
client_secret string Yes The Consumer Secret
auth_uri string Yes URI to get User Authorization
token_uri string Yes URI to get a Access Token
scopes array of strings No Scopes of the access request

Here is an example of OAuth2 implementation in Google Spreadsheets component:

{
  "oauth2":{
    "client_id":"",
    "client_secret":"",
    "auth_uri":"https://accounts.google.com/o/oauth2/v2/auth",
    "token_uri":"https://www.googleapis.com/oauth2/v4/token",
    "scopes": [
      "https://spreadsheets.google.com/feeds"
    ],
    "access_type": "offline",
    "prompt": "consent"
  }
}

Please note that the properties access_type and prompt above are specific to Google. They are not defined in the OAuth2 specification.

Sometimes you will need to access values in the oauth2 properties you gathered from the user using fields, as for example is done in the Salesforce component. The following example demonstrates how to do that.

{
  "credentials" : {
    "fields":{
      "prodEnv" : {
        "label":"Environment",
        "viewClass":"SelectView",
        "required":true,
        "model":{
          "test":"Sandbox",
          "login":"Production"
        },
        "prompt":"Select environment"
      },
      "oauth":{
        "label":"Authentication",
        "viewClass":"OAuthFieldView",
        "required": true
      }
    },
    "oauth2":{
      "client_id":"SALESFORCE_KEY",
      "client_secret":"SALESFORCE_SECRET",
      "auth_uri":"https://prodEnv.salesforce.com/services/oauth2/authorize",
      "token_uri":"https://prodEnv.salesforce.com/services/oauth2/token"
   }
 }
}

In the example above the value of the prodEnv field is used to define the auth_uri and token_uri properties.

The auth_url property can take additional query parameters as shown below:

{
  "oauth2": {
    "auth_uri": "https://login.windows.net/common/oauth2/authorize?resource=RESOURCSE",
    "token_uri": "https://login.windows.net/common/oauth2/token"
  }
}