ThingWorx Flow > Administrator Tasks > Configuring Connector OAuth Settings
  
Configuring Connector OAuth Settings
Many connectors are included in ThingWorx Flow. To use these connectors, obtain the client id and client secret tokens for each connector through a registration process with each third-party system. Then, load the client id and client secret tokens into ThingWorx Flow so that the connectors can use them.
This section describes additional actions required to enable authentication for connectors that use OAuth.
The following out-of-the-box connectors require OAuth:
Azure
Bitly
Box
Dropbox
Github
Google Drive
Gmail
Google Sheet
Google Form
Google Tasks
Google Translator
Youtube
Office 365
Onedrive
Excel Online
Salesforce
Servicemax
Slack
Trello
Zendesk
Dynamics365
OData
Windchill
Swagger
The following video demonstrates the steps required to enable the out of the box connectors OAuth configuration such as the Box connector.
You can enable all or selected connectors from the list. The high-level process is as follows:
1. Create a JSON file, and then copy the following code snippet to the file. This file is used to record the client id and client secret for all the connectors.
{
"azure":{
"Azure": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"bitly": {
"Bitly": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"box": {
"Box": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"dropbox": {
"Dropbox": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"github": {
"Github": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"google_drive": {
"Google Drive": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"google_gmail": {
"Gmail": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"google_sheet": {
"Google Sheet": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"google_form": {
"Google Form": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"google_task": {
"Google Tasks": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"google_translator": {
"Google Translator": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"youtube": {
"Youtube": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"microsoft_365": {
"Office 365": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"onedrive": {
"OneDrive": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"excel": {
"Excel Online": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"salesforce": {
"Salesforce": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"servicemax": {
"Servicemax": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"slack": {
"Slack": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"trello": {
"Trello": {
"CONSUMER_KEY": "<client id here>",
"CONSUMER_SECRET": "<client secret here>"
}
},
"zendesk": {
"Zendesk": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"dynamics365": {
"Dynamics365": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>"
}
},
"odata": {
"OData": {
"oauth2_validate_method": "GET",
"oauth2_validate_headers": [
"<header here>"
],
"oauth2_params_scope": ["<params scope here>"],
"oauth2_validate_url": "/introspect.oauth2",
"oauth2_refresh_data": [
"{\"client_secret\":\"<clinet secret here>\"}",
"{\"grant_type\":\"refresh_token\"}",
"{\"client_id\":\"<client id here>\"}",
"{\"refresh_token\":\"{refresh_token}\"}"
],
"oauth2_refresh_url": "/token.oauth2",
"oauth2_token_data": [
"{\"redirect_uri\":\"<redirect uri here>\"}",
"{\"client_id\":\"<client id here>\"}",
"{\"client_secret\":\"<client secret here>\"}",
"{\"grant_type\":\"authorization_code\"}"
],
"oauth2_token_url": "/token.oauth2",
"oauth2_auth_query": [
"{\"client_id\":\"<client id here>\"}",
"{\"response_type\":\"code\"}",
"{\"redirect_uri\":\"<redirect uri here>\"}",
"{\"scope\":\"{scope}\"}"
],
"oauth2_auth_url": "/authorization.oauth2",
"oauth2_no_state": false,
"base_url": "<base url here>",
"oauth_type": "OAuth2",
"published": true
}
},
"windchill": {
"Windchill": {
"CLIENT_ID": "<client id here>",
"CLIENT_SECRET": "<client secret here>",
"base_url":"<base url here>"
}
}
{
"name": "swagger",
"created_at": "2019-03-04T09:26:46.890Z",
"updated_at": "2019-03-04T09:26:46.890Z",
"uid": "<uid here>",
"icon": "swagger"
}
}
* 
Make sure that the file is a valid JSON file. You can choose to enable a few connectors from the above list or additional connectors, as required. To remove the connector, you need to remove its entire JSON object. For example, to remove the Youtube connector, remove the following code block from the JSON file:
"youtube": {
"Youtube": {
"CLIENT_ID":"<client id here>
"CLIENT_SECRET:"<client secret here>"
}
}
If the OAuth for connector needs to be enabled later, then add the JSON code snippet for Youtube from the sample file, and then provide the values for its client id and client secret properties.
2. Create accounts on the selected connectors, and then login to the connector using a developer portal. For example, for Box, create an account on the Box portal— https://developer.box.com/
3. Follow the steps listed in this section and the document available on the connector’s Website to create an App. After the App is created, retrieve the client ID and client secret and add them to the file created in Step 1. To get the client id and client secret for each connector, refer to the section Configuring OAuths for Out of the Box Connectors.
4. Load the client id and client secret into ThingWorx Flow using the flow-deploy tool. Execute the flow-deploy tool as often as required. The flow-deploy tool updates or adds the client id and client secrets. The tool does not delete any previously added client id or client secrets.
To deploy the OAuths using the flow-deploy tool, execute the following command:
flow-deploy oauths load -f <path-to-the-file-you-created> -t <thingworxurl> -u <username> -p <password>
* 
Make sure that you login as a ThingWorx Administrator.
You can authenticate by providing the user name and password pair such as -u and -p options for the user or by providing the ThingWorx Application Key for the user using the -a option.
where
--version Show version number [boolean]
--help Show help [boolean]
--file, -f Path to a OAuth data file [string]
--username, -u Thingworx Administrator username [string]
--password, -p Thingworx Administrator password [string]
--app-key, -a Thingworx App Key [string]
--twx-url, -t Thingworx Base URL [string]
--log, -l Set the log level [string] [default: "info"]
Obtaining Client Id and Secrets for Out-of-the-Box Connectors
To obtain OAuths client id and client secrets for the out-of-the-box connectors, follow the steps given for each connector in each section that follows:
For all the connectors, the redirect URI has the following format:
https://<hostname>:<port>/Thingworx/Oauths/oauth/return
For example, a sample redirect URI is as follows: https://earth:443/Thingworx/Oauths/oauth/return
Azure
To add an OAuth connection, follow these steps:
1. Register a new application using the Azure portal or search App Registrations, and then click New application registration.
* 
If you are not an owner of any application in the given directory, click View all applications.
2. Provide a name, and then select Application type as Web app/ API.
3. Enter the sign-on Url as https://flow.local.rnd.ptc.com/Thingworx/Composer/apps/flow/ and then click Create.
4. Go to the registered app. The Application ID is the client ID.
5. Go to Settings. Create a new password in the Keys tab. This is the client secret.
* 
Save the secret as soon as it is generated. It might not be visible later.
6. Go to Reply Urls in settings and add the URL https://flow.local.rnd.ptc.com/Thingworx/Oauths/oauth/return
7. Go to Required Permissions in settings and then select Windows Azure Service Management API. Select all permissions, if prompted.
8. After putting client ID, secret in the OAuth file and running ‘gulp-load oauths’, when you finally add a connection you will be required to provide tenant ID and subscription ID.
Bitly
To create an API key, do the following:
1. Create an account on the Bitly portal.
2. Enter your credentials.
3. Set up your application as follows:
a. Click the settings link on the home page.
b. Click the profile name > Registered OAuth Applications > Register New App > Get Registration Code.
An email is sent with an application registration link.
c. Click the link in the email. It redirects to the Bitly page to fill the following application information:
Box
To create a developer account, do the following:
1. Create a developer account on the Box portal.
2. Enter your credentials, and then click Submit.
3. Create your new enterprise application as follows:
a. Click Console, and then click Create New App.
b. Select Enterprise Integration, and then click Next.
c. Select the user authentication method, and then click Next.
d. Enter a unique name for the application, and then click Create App.
To access API Keys, do following:
1. Go to the following link https://app.box.com/developers and then select an application.
2. Select configuration on the left sidebar to get the client id and client secret.
* 
Make sure that you select all the scopes.
Dropbox
To create a developers account, do following:
1. Create an account on the Dropbox portal.
2. Enter your credentials, and then click Create an account.
3. Set up your application as follows:
a. Click on the right bottom corner, and then select Developers.
b. Click Create your app or go to My apps, and then click Create app.
c. On the Create a new app on the DBX Platform window, enter the following details:
For an API, select Dropbox API.
For type of access, select Full Dropbox.
Provide a name for the application.
d. Click Create app.
Click Enable additional users for others to access your application. You can add up to 500 users before applying for production.
Read the reference guide to apply for production.
Dynamic 365
To set up your application, do the following:
1. Create an account on the following portal: https://portal.azure.com.
2. From left navigation menu, select Azure Active Directory.
3. From the Create menu, select App Registration.
4. To register the application, enter following details:
Name—Application name. Make sure that the name contains a minimum of four characters.
Application type—Select one of the following options:
Web app/ API
—Represents the Web application, Web API, or both.
Native—Application that can be installed on your device.
Sign-on URL—Sign in and use your application
5. Open the App details.
6. Select, and then add Reply URLs.
To get the client id and client secret, do the following:
1. Enter App ID as client id.
2. Select the required keys and add a new Password.
3. Copy the password value. It represents the client secret.
Github
To set up your application, do the following:
1. Create an account on the Github portal.
2. Go to settings page, and then click Developer settings.
3. Click the new OAuth Apps, then enter the application information.
4. After clicking the Register application, the client id and client secret appears.
Google Services
1. Access the Google API console, and then enter your credentials.
2. Select the project, and then click the credentials from the menu on the left side.
3. Click the Web Client name under OAuth 2.0 client Ids. The client id and client secret appear as shown in the figure that follows:
4. Click ENABLE APIS AND SERVICES to enable the required services.
5. Click Enable, and then you can use the same client credentials for these connectors that were created with your Google account.
* 
Some APIs or services require you to add the billing account. For example, Google Translator.
Office365/Onedrive/Excel Online
To create an API Key, do following:
Create a developer account on the Microsoft application registration portal.
To set up a new application, do the following:
1. Go to the Microsoft application registration portal link.
2. Sign in to your account or create a new account.
3. Click Add an app.
4. Enter the application name to register the application, and then click Create.
You are redirected to the application properties page.
5. Copy the Application Id, and then click Generate New Password to get the client secret.
6. Click Edit Application Manifest to add the redirect URIs as provided in the figure that follows:
Salesforce
Create an account on the Salesforce portal, and then enter the required details:
To create the consumer key and consumer secret, do the following:
1. Register a New App:
a. Click to log in to your Salesforce account.
b. Navigate to Platform Tools > Apps, and then under the App Manager section, click New Connected App.
2. To complete the New Connected App form, do following:
a. Enter the Connected App Name, API Name, and Contact Email.
b. Select the Enable OAuth Settings check box.
c. Enter a ThingWorx related Callback URL such as https://user-domain:user-port/Thingworx/Oauths/oauth/return
d. Add Access your basic information to the Selected OAuth Scopes, and then click Save.
e. Add the following OAuth scopes:
After your app is registered, your Consumer Key and Consumer Secret appear on the page.
ServiceMax
Create an account on the Servicemax portal, and then enter the details as shown in the figure that follows:
To create the consumer key and consumer secret, do the following
1. Navigate to Custom Apps > Connected Apps.
2. To complete the New Connected App form, do following:
a. Enter Connected App Name, API Name, and Contact Email.
b. Select the Enable OAuth Settings check box under API (Enable OAuth Settings).
c. Enter a ThingWorx related Callback URL such as https://user-domain:user-port/Thingworx/Oauths/oauth/return
d. Add the required Selected OAuth Scopes, and then click Save.
After your App is registered, your Consumer Key and Consumer Secret appear on the page.
Slack
To create an API key, do following:
1. Create an account on the Slack portal.
2. Open the link, and then click the Your Apps link on the top right corner.
3. Click Create an App, and then enter the application name and Workspace in which to develop this app and click Create App.
4. Click OAuth & Permission under the Features menu, and then enter the redirect URLs.
5. Select Admin under the Scopes section.
6. Select Manage distribution from the menu on the left side, to distribute the app for users in other workspaces.
7. Select the check box, and then click Activate Public Distribution.
8. Copy the client id and client secret in the corresponding OAuth data file.
Trello
Create a developer account on the Trello portal.
Create a Trello account on the portal.
To access the API Key and Secret:
Navigate to the app-key section.
USgeoCoder
To create the API Key, create an account on the USgeoCoder portal.
On successful creation of an account, an authentication key is provided.
* 
Free sign up is valid for 30 days only. For paid account with USgeoCoder, contact the USgeoCoder support team.
Twilio
Create an account on the Twilio portal, and then enter the details as shown in the figure that follows:
To get the ACCOUNT SID and AUTH TOKEN navigate to Settings > General Settings > API Credentials.
Zendesk
1. Create an account on the Zendesk portal.
2. Enter the Subdomain.
3. To create OAuth clients, do following:
a. Click the admin icon and then select the API option that appears on the left menu.
b. Select the OAuth Clients tab.
c. Enter the client id.
d. Provide the redirect uri, and then click Save to get the client secret.
OData
1. Provide the header information in the "oauth2_validate_headers" array. The sample array is as follows:
"oauth2_validate_headers": [
"{\"Authorization\":\"Bearer {access_token}\"}",
"{\"Content-Type\":\"application/json\"}"
]
2. Provide the scope information in the "oauth2_params_scope" array. The sample array is as follows:
"oauth2_params_scope": [
"{\"READ\":\"READ_PRIVILEGES\"}"
]
3. Provide the client id information “<client id here>” wherever applicable in the JSON file.
4. Provide the client secret information “<client secret here>” wherever applicable in the JSON file.
5. Provide the redirect uri information “<redirect uri here>” wherever applicable in the JSON file.
6. Provide the base url information “<base url here>” wherever applicable in the JSON file.
Windchill
Provide the client id, client secret, and base url information wherever applicable in the JSON file. For information on adding a new OAuth connection, refer to the Windchill connector topic.
Swagger
Provide the configuration details wherever applicable in the JSON file.