OAuth Proxy

How to Use OAuth Proxies with Cloud Elements

Before using an OAuth proxy with Cloud Elements, you must have the necessary information for your application, including the API key and API secret. You can access that information from the application provider's site.

Creating an OAuth proxy via the UI

  1. Navigate to https://my-staging.cloudelements.io/welcome. Log in to your Cloud Elements account, and click the Account Profile button.
  2. Click VIEW MY ORGANIZATION SECRET and VIEW MY USER SECRET. Take note of your Organization and User secrets, as they will be used later in this setup process.
  3. Click OAuth Proxy.
  4. At the top of the OAuth Proxies list, click the Add button.
  5. On the Create page, enter the following information:
    • OAuth Proxy Name
    • API Key
    • API Secret
  6. Paste the unique URL generated by Cloud Elements in the Redirect URL field of the application provider's site. For this example, we will use Box.
  7. Execute the cURL GET command:
    curl -X GET \
    	 'https://api.cloud-elements.com/elements/api-v2/elements/<Element name here>/oauth/url?isOauthProxy=true&oauthProxyName=%3CYour%20OAuth%20Proxy%20Name%3E&apiKey=%3CAPI%20Key%3E&apiSecret=%3CAPI%20Secret%3E&callbackUrl=%3CUnique%20UL%20Cloud%20Elements%20generated%3E&state=%3CURL%20you%20want%20the%20proxy%20to%20point%20to%3E&callbackProxy=true' \
    	 -H 'Authorization: User <secret>, Organization <secret>' \
    	 -H 'Cache-Control: no-cache' \
    	 -H 'Content-Type: application/json' 
  8. The above should either give you a code or have you run through the OAuth flow which will render a code to you. Record that code.

  9. Execute the cURL POST command:
    curl -X POST \
    	 https://api.cloud-elements.com/elements/api-v2/instances \
    	 -H 'Authorization: User <Secret>, Organization <sceret>' \
    	 -H 'Cache-Control: no-cache' \
    	 -H 'Content-Type: application/json' \
    	 -d '{
    	 "element": {
    	 "key": "<Name of Element>"
    	 },
    	 "providerData": {
    	 "code": "<Code from the GET flow>"
    	 },
    	 "configuration": {
    	 "authentication.type": "oauth2",
    	 "oauth.api.key": "<Your API Key>",
    	 "oauth.api.secret": "<Your API Secret>",
    	 "oauth.callback.url": "<The OAuth Proxy URL Cloud Elements generated>"
    	 },
    	 "name": "<Your name for the instance>"
    	}'
  10. After executing the cURL GET command, you should either receive a code or be run through the OAuth flow, generating the code. Take note of the code.
  11. Execute the following API call:
    curl -X POST \
    	 https://api.cloud-elements.com/elements/api-v2/instances \
    	 -H 'Authorization: User <Secret>, Organization <sceret>' \
    	 -H 'Cache-Control: no-cache' \
    	 -H 'Content-Type: application/json' \
    	 -d '{
    	 "element": {
    	 "key": "<Name of Element>"
    	 },
    	 "providerData": {
    	 "code": "<Code from the GET flow>"
    	 },
    	 "configuration": {
    	 "authentication.type": "oauth2",
    	 "oauth.api.key": "<Your API Key>",
    	 "oauth.api.secret": "<Your API Secret>",
    	 "oauth.callback.url": "<The OAuth Proxy URL Cloud Elements generated>"
    	 },
    	 "name": "<Your name for the instance>"
    	}'

You should receive a 200 response code and a brand new instance of your element.

The "configuration" JSON object may have to be slightly modified depending on the element you are using. Refer to the authentication tab for the given element here: https://my-staging.cloudelements.io/elements.

Creating an OAuth proxy via API

Execute the following API call:

curl -X POST \
	  https://api.cloud-elements.com/elements/api-v2/elements/oauthProxies \
	  -H 'Authorization: User <<user_token>>, Organization <<organization_token>>' \
	  -H 'Content-Type: application/json' \
	  -d '{
	  "name":"Your OAuth Proxy Name",
	  "apiKey":"<<yourApiKey>>",
	  "apiSecret":"<<yourApiSecret>>",
	   "configuration":"{ \"config\": \"additional\" }"
	}'

The answer for the above call should be:

200 OK:

	{
	    "apiKey": "<<yourApiKey>>",
	    "configuration": "{ \"config\": \"additional\" }",
	    "proxyUrl": "https://XXXXXXXX-YourOAuthProxyName.ceproxy.co.uk/production",
	    "name": "Your OAuth Proxy Name",
	    "apiSecret": "<<yourApiSecret>>",
	    "id": <<oauthProxyUrlId>>
	}

Enter the OAuth Proxy URL in the Redirect URL section of your application provider's site.

Callback URLs for OAuth Proxies

 The OAuth Proxy feature provided by Cloud Elements offers the possibility to connect multiple environments using only one callback URL (the one provided by Cloud Elements). In some cases, the application can support only one callback URL, thus limiting the developer’s possibilities. 

This feature can enable multiple domain connections possibilities. As each application domain can differ, and to ensure a successful connection through the provided callback URL, the application field should contain only valid regex regular expressions. 

Regex regular expressions represents a sequence of characters that define a search pattern. They are a way to describe patterns in a string data and they form a small separate language (it is part of JavaScript but also from many other programming language). When used in JavaScript these regular expressions are also objects. They can provide compilation of the regular expression when the script is loaded. For example, if a company owns the domain named《 *justATest.com 》, this one has to be adjusted to the regex regular expressions into this way: 《 .*\.justATest\.com 》.

If the chosen application URL does not fulfill the regex regular expression rules no connection can be established to the desired application. The error can be displayed in two different ways, depending the connection method:

  1. If you are connected in your application UI and want to see from a user’s perspective how the connection is performed, instead of being redirected to the application connection page where you can type in your credentials, a blank page will be displayed in your browser with the message “This site can’t be reached… ERR_TIMED_OUT”;

  1. If you’re trying to connect via Postman or any other tool that supports every stage of the API Lifecycle, the following error message will be displayed “Failed to retrieve OAuth authorize url”.


Here is an example of an invalid regular expression case: 

  1. Create an OAuth Proxy and add an invalid regular expression: 

                                               


  1. Check the application connection through Postman:

               


  1. The above error appears due to an invalid regex expression used in the callback URL provided within the OAuth Proxy Application URL: 


                         


  1. The previous error from steps 2 and 3 can be avoided if the domain URL is adjusted to the regex regular expressions using this 《 .*\.justATest\.com 》instead of this 《 *justATest.com 》.


               



OAuth Proxy Documentation

The OAuth Proxy feature gives you the capability to have multiple environments, such as development, QA, etc, with one endpoint application. For example some vendors only allow one callback URL per application. The proxy will allow for the same callback URL to be used with multiple application endpoints. You would then use the proxy address as the Callback URL instead of your own Callback URL. This permits multiple endpoint applications to one callback URL.

We offer two forms of the proxy. Standard OAuth Proxy Configuration: requires an API key and secret to be passed as URL parameters or in the JSON payload needed to create an instance. OAuth Proxy with API Key and Secret Management: option to input your API key and secret during the proxy creation and we will take care of the rest during instance creation.

Currently, an OAuth Proxy can only be created from Cloud Elements. The OAuth Proxy is an OPTIONAL feature. This feature is NOT required to use Cloud Elements Service. Instructions on how to set up the Proxy are below.

How to use the OAuth Proxy:

Via a web browser go to https://my-staging.cloudelements.io/login and log in to your Cloud Elements account.

Select “OAUTH Proxy”

Click “Add Proxy” Cloud Elements OAuth Proxy 1

Name the Application

Click “Add” Cloud Elements OAuth Proxy 2

A proxy URL will be created. Please copy this URL as it will be used as your Callback URL to the endpoint Application. Cloud Elements OAuth Proxy 3

Navigate to your connected apps and input the proxy URL into the redirect URI or URL field. Box will be used for this demonstration Cloud Elements OAuth Proxy 4

Enter your callback URLs of your applications.

Click “Add URL” Cloud Elements OAuth Proxy 5

Cloud Elements OAuth Proxy functionality supports domain regular expressions. For example, if you have a number of different URLs to your apps, you may use a domain regular expression to minimize the number of URLs. Example URLs: https://www.myapp.com https://www.myapp.denver.ds https://www.myapp.austin.ds https://www.prodapp.com https://www.prodapp.alpha.ds https://www.prodapp.beta.ds

Example Regular Expressions: https\:\/\/www\.(myapp|prodapp)\.com https\:\/\/www\.(myapp|prodapp)(\.[a-zA-Z0-9]*\.ds) Cloud Elements OAuth Proxy 6

API Calls

Performing a GET

While calling the GET /elements/{keyOrId}/oauth/url to get the provider URL, please make sure the fields below are included in your parameters: isOauthProxy – Should be set to true oauthProxyName – Name of the proxy e.g. “TestApp” state – should be the application callback URL which was provided during the creation of the Proxy

From here the OAuth Provisioning Process would follow the same instructions as shown in our Provisioning Instructions below.

The Callback URL retrieved by the initial GET /elements/{keyOrId}/oauth/url will be the OAuth Proxy URL that we created via the steps outlined above.

Create Instance

Box is a Documents Platform. When you provision an instance, your app will have access to the different functionality offered by the Box platform.

Step 1. Get Elements OAuth Information

HTTP Header: None HTTP Verb: GET Request URL: /elements/{keyOrId}/oauth/url Request Body: None Query Parameters:

  • key - box
  • apiKey - Client ID
  • apiSecret – Client Secret
  • callbackUrl – OAuth Proxy URL
  • isOauthProxy - true
  • oauthProxyName - Name of the proxy e.g. "TestApp"

Description: The result of this API invocation is an OAuth redirect URL from the endpoint. Your application should now redirect to this URL, which in turn will present the OAuth authentication and authorization page to the user. When the provided callback URL is executed, a code value will be returned, which is required for the Create Instance API.

Example cURL Command:

curl -X GET
-H 'Content-Type: application/json'
'https://api.cloud-elements.com/elements/api-v2/elements/box/oauth/url?isOauthProxy=true&oauthProxyName=TestApp&apiKey=fake_box_client_id&apiSecret=fake_box_client_secret&callbackUrl=insert_oauth_proxy_url&state=https://www.your_call_back_url&callbackProxy=true'

Response:

{
  "oauthUrl": "https://www.box.com/api/oauth2/authorize?response_type=code&client_id=INSERT_BOX_CLIENT_ID&redirect_uri=https%3A%2F%2Finsert_oauth_proxy_url&state=cloud_elements_random_key",
  "element": "box"
}

Handle Callback from the Endpoint: Upon successful authentication and authorization by the user, the endpoint will redirect to the callback URL you provided when you setup your application with the endpoint, in our example, https://www.mycoolapp.com/auth. The endpoint will also provide two query string parameters: “state” and “code”. The value for the “state” parameter will be the name of the endpoint, e.g., “box” in our example, and the value for the “code” parameter is the code required by Cloud Elements to retrieve the OAuth access and refresh tokens from the endpoint. If the user denies authentication and/or authorization, there will be a query string parameter called “error” instead of the “code” parameter. In this case, your application can handle the error gracefully.

Step 2. Create an Instance

To provision your Box Element, use the /instances API.

Below is an example of the provisioning API call.

  • HTTP Headers: Authorization- User , Organization
  • HTTP Verb: POST
  • Request URL: /instances
  • Request Body: Required – see below
  • Query Parameters: none

Description: An Element token is returned upon successful execution of this API. This token needs to be retained by the application for all subsequent requests involving this element instance.

A sample request illustrating the /instances API is shown below.

HTTP Headers:

Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>

This instance.json file must be included with your instance request. Please fill your information to provision. The “key” into Cloud Elements Box is “box”. This will need to be entered in the “key” field below depending on which Element you wish to instantiate.

{
  "element": {
    "key": "box"
  },
  "providerData": {
    "code": "Code on Return the URL"
  },
  "configuration": {
    "oauth.api.key": "<INSERT_BOX_CLIENT_ID>",
    "oauth.api.secret": "<INSERT_BOX_CLIENT_SECRET>",
    "oauth.callback.url": "<INSERT_OAUTH_PROXY_URL>"
  },
  "tags": [
    "<INSERT_TAGS>"
  ],
  "name": "<INSERT_INSTANCE_NAME>"
}

Here is an example cURL command to create an instance using /instances API.

Example Request:

curl -X POST
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type: application/json'
-d @instance.json
'https://api.cloud-elements.com/elements/api-v2/instances'

If the user does not specify a required config entry, an error will result notifying her of which entries she is missing.

Below is a successful JSON response:

{
  "id": 123,
  "name": "Test",
  "token": "5MOr3Sl/E4kww6mTjmjBYV/hAUAzz1g=",
  "element": {
      "id": 22,
      "name": "Box",
      "key": "box",
      "description": "Add a Box Instance to connect your existing Box account to the Documents Hub, allowing you to manage files and folders. You will need your Box account information to add an instance.",
      "image": "elements/provider_box.png",
      "active": true,
      "deleted": false,
      "typeOauth": true,
      "trialAccount": false,
      "existingAccountDescription": "Give your application access to your existing
   Box accountEnter your credentials and details for your Box Account",
      "configDescription": "If you do not have an Box.net account, you can create one at Box.Net Signup",
      "transformationsEnabled": false,
      "authentication": {
        "type": "oauth2"
      },
      "hub": "documents"
    },
    "provisionInteractions": [],
    "valid": true,
    "disabled": false,
    "maxCacheSize": 0,
    "cacheTimeToLive": 0,
    "eventsEnabled": false,
    "cachingEnabled": false
  }

Note: Make sure you have straight quotes in your JSON files and cURL commands. Please use plain text formatting in your code. Make sure you do not have spaces after the in the cURL command.

OAuth Proxy with API Key and Secret Management

Implementing OAuth Proxy with API Key and Secret Management works the same as the process described above. An API Key and Secret are required when the proxy is set up. This feature is NOT required to use Cloud Elements Service. NOTE: A sub-account user (user under your Organization) will not be able to access the API Key/ API Secret that has been added for OAuth proxy by the super-account user (The Organizational level account). Instructions on how to set up the Proxy are below.

How to use the OAuth Proxy with API Key and Secret Managment:

Via a web browser go to: https://console.cloud-elements.com/elements/jsp/login.jsp and log in to your Cloud Elements account.

Select “OAUTH Proxy”

Click “Add Proxy” Cloud Elements OAuth Proxy 7

Name the Application, input your API Key and API secret

NOTE: You have option to add any additional parameters in the Configuration box. This is only needed if the cloud service requires more than the API Key and Secret during authentication. For example, HubSpot requires a “PortalID” during authentication. These additional parameters need to be inputed as a JSON string.

Click “Add” Cloud Elements OAuth Proxy 8

A proxy URL will be created. Please copy this URL as it will be used as your Callback URL to the endpoint Application. Cloud Elements OAuth Proxy 9

Navigate to your connected apps and input the proxy URL into the redirect URI or URL field. Box will be used for this demonstration. Cloud Elements OAuth Proxy 10

Enter your callback URLs of your applications.

Click “Add URL” Cloud Elements OAuth Proxy 11

Cloud Elements OAuth Proxy functionality supports domain regular expressions. For example, if you have a number of different URLs to your apps, you may use a domain regular expression to minimize the number of URLs. Example URLs: https://www.myapp.com https://www.myapp.denver.ds https://www.myapp.austin.ds https://www.prodapp.com https://www.prodapp.alpha.ds https://www.prodapp.beta.ds

Example Regular Expressions: https\:\/\/www\.(myapp|prodapp)\.com https\:\/\/www\.(myapp|prodapp)(\.[a-zA-Z0-9]*\.ds) Cloud Elements OAuth Proxy 12

API Calls

Performing a GET

While calling the GET /elements/{keyOrId}/oauth/url to get the provider URL, please make sure the fields below are included in your parameters: isOauthProxy – Should be set to true oauthProxyName – Name of the proxy e.g. “TestApp” state – Your application callback URL

From here the OAuth Provisioning Process would follow the same instructions as shown in our Provisioning Instructions below.

The Callback URL retrieved by the initial GET /elements/{keyOrId}/oauth/url will be the OAuth Proxy URL that we created via the steps outlined above.

Create Instance

Box is a Documents Platform. When you provision an instance, your app will have access to the different functionality offered by the Box platform.

Step 1. Get Elements OAuth Information

HTTP Header: None HTTP Verb: GET Request URL: /elements/{keyOrId}/oauth/url Request Body: None Query Parameters:

  • key - box
  • oauthProxyName - Name of the proxy e.g. "TestApp"
  • isOauthProxy - true
  • state - your application callback URL

Description: The result of this API invocation is an OAuth redirect URL from the endpoint. Your application should now redirect to this URL, which in turn will present the OAuth authentication and authorization page to the user. When the provided callback URL is executed, a code value will be returned, which is required for the Create Instance API.

Example cURL Command:

curl -X GET
-H 'Content-Type: application/json'
'https://api.cloud-elements.com/elements/api-v2/elements/box/oauth/url?isOauthProxy=true&oauthProxyName=TestApp&state=https://www.yourcallbackurl.com'

Response:

{
  "oauthUrl": "https://www.box.com/api/oauth2/authorize?response_type=code&client_id=INSERT_BOX_CLIENT_ID&redirect_uri=https%3A%2F%2Finsert_oauth_proxy_url&state=cloud_elements_random_key",
  "element": "box"
}

Handle Callback from the Endpoint: Upon successful authentication and authorization by the user, the endpoint will redirect to the callback URL you provided when you setup your application with the endpoint, in our example, https://www.mycoolapp.com/auth. The endpoint will also provide two query string parameters: “state” and “code”. The value for the “state” parameter will be the name of the endpoint, e.g., “box” in our example, and the value for the “code” parameter is the code required by Cloud Elements to retrieve the OAuth access and refresh tokens from the endpoint. If the user denies authentication and/or authorization, there will be a query string parameter called “error” instead of the “code” parameter. In this case, your application can handle the error gracefully.

Step 2. Create an Instance

To provision your Box Element, use the /instances API.

Below is an example of the provisioning API call.

  • HTTP Headers: Authorization- User , Organization
  • HTTP Verb: POST
  • Request URL: /instances
  • Request Body: Required – see below
  • Query Parameters: none

Description: An Element token is returned upon successful execution of this API. This token needs to be retained by the application for all subsequent requests involving this element instance.

A sample request illustrating the /instances API is shown below.

HTTP Headers:

Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>

This instance.json file must be included with your instance request. Please fill your information to provision. The “key” into Cloud Elements Box is “box”. This will need to be entered in the “key” field below depending on which Element you wish to instantiate.

{
  "element": {
    "key": "box"
  },
  "providerData": {
    "code": "Code on Return the URL"
  },
  "oauthProxy": {
        "isOauthProxy": true,
        "oauthProxyName": "<INSERT_OAUTH_PROXY_NAME>"
  },
  "tags": [
    "<INSERT_TAGS>"
  ],
  "name": "<INSERT_INSTANCE_NAME>"
}

Here is an example cURL command to create an instance using /instances API.

Example Request:

curl -X POST
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type: application/json'
-d @instance.json
'https://api.cloud-elements.com/elements/api-v2/instances'

If the user does not specify a required config entry, an error will result notifying her of which entries she is missing.

Below is a successful JSON response:

{
  "id": 123,
  "name": "Test",
  "token": "5MOr3Sl/E4kww6mTjmjBYV/hAUAzz1g=",
  "element": {
      "id": 22,
      "name": "Box",
      "key": "box",
      "description": "Add a Box Instance to connect your existing Box account to the Documents Hub, allowing you to manage files and folders. You will need your Box account information to add an instance.",
      "image": "elements/provider_box.png",
      "active": true,
      "deleted": false,
      "typeOauth": true,
      "trialAccount": false,
      "existingAccountDescription": "Give your application access to your existing
   Box accountEnter your credentials and details for your Box Account",
      "configDescription": "If you do not have an Box.net account, you can create one at Box.Net Signup",
      "transformationsEnabled": false,
      "authentication": {
        "type": "oauth2"
      },
      "hub": "documents"
    },
    "provisionInteractions": [],
    "valid": true,
    "disabled": false,
    "maxCacheSize": 0,
    "cacheTimeToLive": 0,
    "eventsEnabled": false,
    "cachingEnabled": false
  }

Note: Make sure you have straight quotes in your JSON files and cURL commands. Please use plain text formatting in your code. Make sure you do not have spaces after the in the cURL command.

If you need any support integrating our APIs, please let us know. You can email or give us a call at +1.866.830.3456. We will do our best to get back to you within 24 hours. Your success is our success.