Configuring and Loading OAuths

ThingWorx Flow > Installation and Configuration > Configuring ThingWorx Flow > Configuring and Loading OAuths

Before you create an OAuth connector for any third-party service or utility, you must load its OAuth provider to the ThingWorx Flow server. The sample OAuth configuration JSON file template is available in the oauthConfigurations parameter of the LoadOAuthConfiguration service of the WorkflowSubsystem in ThingWorx Composer. The following is a high-level overview of the process of loading OAuths:

1. Create an application on the third-party system.

2. Retrieve the client ID-client secret pair from the application, and add it to the sample OAuth configuration JSON file. Add values of any additional parameters that are required for the OAuth configuration.

To remove OAuth settings for any third-party service or utility, you need to remove its entire JSON object. For example, to remove the OAuth settings for Gmail, remove the following JSON object:

"google_gmail": {
"Gmail": {
"CLIENT_ID": "<Client ID>"
"CLIENT_SECRET": "<Secret>"
}
},

If you have removed a JSON object for any third-party service or utility, and want to add its OAuth settings later, add the JSON code snippet from the sample OAuth configuration JSON file template, and provide required values for OAuth configuration.

The sample configuration file contains connector configuration values that represent the third-party service or utility. For example, for Gmail, do not modify google_gmail in the JSON object. To add multiple OAuth providers for Gmail, for example, Gmail-1 and Gmail-2, add the following JSON object to the sample file:

{
"google_gmail": {
"Gmail-1": {
"CLIENT_ID": "<client id for Gmail - 1 account here>",
"CLIENT_SECRET": "<client secret for Gmail - 1 account here>"
},
"Gmail-2": {
"CLIENT_ID": "<client id for Gmail - 2 account here>",
"CLIENT_SECRET": "<client secret for Gmail - 2 account here>"
}
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

ThingWorx Flow supports OAuth for the following services and utilities:

• Azure

• Bitly

• Box

• Dialogflow

• Dropbox

• Dynamics 365 CRM

• Excel Online

• Github

• Gitlab

• Gmail

• Google Drive

• Google Forms

• Google Sheets

• Google Tasks

• Google Translator

• HTTP

• JIRA

• OData

• OSLC

• Office 365

• OneDrive

• SAP OData

• SOAP

• Salesforce

• ServiceMax

• Slack

• Swagger

• ThingWorx

• Trello

• Windchill

• Windchill RV&S

• YouTube

• Zendesk

Configuring and Loading OAuths for Services and Utilities

Azure

Perform the following steps every time you want to add an OAuth provider for an Azure application:

1. Create an Azure application.

While creating the application, set appropriate values of the following parameters:

▪ API Permissions—Azure Service Management.

▪ Redirect URI—Enter ThingWorx Flow return URL in the https://<HostName:Port>/Thingworx/Oauths/oauth/return format.

2. To add an OAuth provider for Azure, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Azure application.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Azure application.

"azure": {
"Azure": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Bitly

Perform the following steps every time you want to add an OAuth provider for a Bitly app:

1. Create a Bitly app.

While creating the app, set the Redirect URI to a ThingWorx Flow return URL in the https://<HostName:Port>/Thingworx/Oauths/oauth/return format.

2. To add an OAuth provider for Bitly, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Bitly app.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Bitly app.

"bitly": {
"Bitly": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Box

Perform the following steps every time you want to add an OAuth provider for a Box app:

1. Create a Box app.

While creating the app, set appropriate values of the following parameters:

▪ Application Scopes—Select all scopes.

▪ Redirect URI—Enter ThingWorx Flow return URL in the https://<HostName:Port>/Thingworx/Oauths/oauth/return format.

The following video demonstrates the steps required to enable OAuth configuration for Box:

2. To add an OAuth provider for Box, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Box app.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Box app.

"box": {
"Box": {
"CLIENT_SECRET": "client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Dialogflow

Perform the following steps every time you want to add an OAuth provider for a Dialogflow app:

1. Configure OAuth for your Dialogflow project.

While creating the app, provide the redirect URI as a ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

To add an OAuth provider for your Dialogflow app, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Google app.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Google app.

"apiai": {
"Dialogflow": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

2. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Dropbox

Perform the following steps every time you want to add an OAuth provider for a Dropbox app:

1. Create a Dropbox app. This link provides information about Dropbox OAuth.

While creating the app, set appropriate values for the following parameters:

▪ API—Select Dropbox API.

▪ Type of access—Full Dropbox.

▪ Redirect URI—Enter ThingWorx Flow return URL in the https://<HostName:Port>/Thingworx/Oauths/oauth/return format.

2. To add an OAuth provider for Dropbox, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Dropbox app.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Dropbox app.

"dropbox": {
"Dropbox": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Dynamics 365 CRM

Perform the following steps every time you want to add an OAuth provider for a Dynamics 365 CRM application:

1. Create an Azure Active Directory application.

While creating the app, set the Redirect URI to a ThingWorx Flow return URL in the https://<HostName:Port>/Thingworx/Oauths/oauth/return format.

2. To add an OAuth provider for Dynamics 365 CRM, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Azure application.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Azure application.

"dynamics365": {
"Dynamics365": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Excel Online, Office 365, OneDrive

Perform the following steps every time you want to add an OAuth provider for an Excel Online, Office 365, or OneDrive application:

1. Create an Azure application.

While creating the application, set appropriate values of the following parameters:

▪ API Permissions—Azure Service Management.

▪ Redirect URI—Enter ThingWorx Flow return URL in the https://<HostName:Port>/Thingworx/Oauths/oauth/return format.

2. To add an OAuth provider for Excel Online, Office 365, or OneDrive, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Azure application.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Azure application.

Excel Online

"excel": {
"Excel Online": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

Office 365

"microsoft_365": {
"Office 365": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

OneDrive

"onedrive": {
"OneDrive": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Github

Perform the following steps every time you want to add an OAuth provider for a GitHub app:

1. Create a Github OAuth app.

While creating the app, set the Authorization callback URL to a ThingWorx Flow return URL in the https://<HostName:Port>/Thingworx/Oauths/oauth/return format.

2. To add an OAuth provider for Github, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Github app.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Github app.

"github": {
"Github": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Gitlab

Perform the following steps every time you want to add an OAuth provider for a Gitlab application:

1. Create a GitLab application.

While creating the application, set appropriate values of the following parameters:

▪ Scopes—api, read_user, read_repository, read_registry.

▪ Redirect URI—Enter ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

2. To add an OAuth provider for Gitlab, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your GitLab application.
CLIENT_SECRET	Client secret value.	Retrieve the value from your GitLab application.

"gitlab": {
"Gitlab": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Gmail, Google Drive, Google Forms, Google Sheets, Google Tasks, Google Translator, YouTube

Perform the following steps every time you want to add an OAuth provider for a Google app:

1. Configure OAuth for your Google app.

While creating the app, provide the redirect URI as a ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

To add an OAuth provider for your Google app, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Google app.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Google app.

Gmail "google_gmail": { "Gmail": { "CLIENT_SECRET": "<client secret here>", "CLIENT_ID": "<client id here>" } }	Google Drive "google_drive": { "Google Drive": { "CLIENT_SECRET": "<client secret here>", "CLIENT_ID": "<client id here>" } }
Google Form "google_form": { "Google Form": { "CLIENT_SECRET": "<client secret here>", "CLIENT_ID": "<client id here>" } }	Google Sheet "google_sheet": { "Google Sheet": { "CLIENT_SECRET": "<client secret here>", "CLIENT_ID": "<client id here>" } }
Google Task "google_task": { "Google Tasks": { "CLIENT_SECRET": "<client secret here>", "CLIENT_ID": "<client id here>" } }	Google Translator "google_translator": { "Google Translator": { "CLIENT_SECRET": "<client secret here>", "CLIENT_ID": "<client id here>" } }
Youtube "youtube": { "Youtube": { "CLIENT_SECRET": "<client secret here>", "CLIENT_ID": "<client id here>" } }

2. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

HTTP

Perform the following steps every time you want to add an OAuth provider for an HTTP server:

1. Configure OAuth on your HTTP server.

2. To add an OAuth provider for your HTTP server, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
AUTH_URL [Required]	Specifies the OAuth endpoint for token requests.	Retrieve the value from your OAuth client. Example: \authorize
TOKEN_URL [Required]	Provides the access token.	Retrieve the value from your OAuth client. Example: \token
VALIDATE_URL [Required]	Specifies the URL used to validate the access token.	Retrieve the value from your OAuth client. • If you do not want to VALIDATE_URL, provide the accessible server URL. Example: https://www.dropbox.com/ • If you want to implement VALIDATE_URL, then use the get method to create API.
REFRESH_URL	Specifies the URL to be used to obtain access tokens.	Retrieve the value from your OAuth client. Example: \token
SCOPE [Required]	Provides a space-separated list of scopes for your application.	<SCOPE 1> <SCOPE 2>
BASE_URL [Required]	Specifies the Central Auth Server URL.	Retrieve the value from your OAuth client.
NEED_RESOURCE_URL [Required]	Specifies if the user must provide the RESOURCE_URL while adding the OAuth connector. If you set this to True, then you must specify the value of the RESOURCE_URL while adding the OAuth provider. If you set this to False, then the user must specify the value of the RESOURCE_URL while adding the OAuth connector.	true or false
RESOURCE_URL	Specifies the resource server URL.	—
CLIENT_ID [Required]	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your OAuth client.
CLIENT_SECRET [Required]	Client secret value.	Retrieve the value from your OAuth client.

"devtools": {
"HTTP": {
"AUTH_URL": "<auth url here>",
"CLIENT_SECRET": "<client secret here>",
"TOKEN_URL": "<token url here>",
"VALIDATE_URL": "<validate url here>",
"CLIENT_ID": "<client id here>",
"SCOPE": "<scopes separated by spaces>",
"RESOURCE_URL": "<resource url here>",
"BASE_URL": "<base url here>",
"REFRESH_URL": "<refresh url here>",
"NEED_RESOURCE_URL": "<boolean value here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

JIRA

Perform the following steps every time you want to add an OAuth provider for a JIRA app:

1. Create a JIRA app.

While creating the app, set appropriate values of the following parameters:

▪ Scopes—view Jira issue data (read:jira-work), create and manage issues (write:jira-work), view user profiles (read:jira-user)

▪ Callback URL—Enter ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

2. To add an OAuth provider for JIRA, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your JIRA app.
CLIENT_SECRET	Client secret value.	Retrieve the value from your JIRA app.

"jira": {
"JIRA": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

OData

Perform the following steps every time you want to add an OAuth provider for your OData instance:

1. Configure OAuth on your OData instance.

2. As per your OAuth configuration, provide values in the OAuth configuration JSON file. Refer sample config.json. The following are example values that you might provide for loading OAuths:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your OAuth application.
CLIENT_SECRET	Client secret value.	Retrieve the value from your OAuth application.
VALIDATE_URL	Specifies the URL used to validate the access token.	Retrieve the value from your OAuth client.
REFRESH_URL	Specifies the URL to be used to obtain access tokens.	Retrieve the value from your OAuth client.
TOKEN_URL	Provides the access token.	Retrieve the value from your OAuth client.
AUTH_URL	Specifies the OAuth endpoint for token requests.	Retrieve the value from your OAuth client.

{
"name": "odata",
"created_at": "2017-02-27T09:26:46.890Z",
"updated_at": "2017-02-27T09:26:46.890Z",
"uid": "oaufe1978bc9e71d999ef2ba4",
"icon": "odata",
"version": "v1",
"__v": 0,
"title": "Dynamics 365",

"oauth2_include": [
"{\"resource\":\"{resource}\"}"
],

"oauth2_required": [
{
"title": "Tenant ID",
"id": "tenant",
"default": "common",
"description": "Enter Dynamics 365 tenant id, leave it common if you don't have it"
},

{
"title": "Resource URL",
"id": "resource",
"description": "Enter Dynamics 365 resource URL, eg: https://example.crm5.dynamics.com"
}
],

"oauth2_params_scope": [
"{\"user_impersonation\":\"User Impersonation\"}"
],

"oauth2_refresh_data": [
"{\"client_secret\":\"{client_secret}\"}",
"{\"grant_type\":\"refresh_token\"}",
"{\"client_id\":\"{client_id}\"}",
"{\"resource\":\"{resource}\"}",
"{\"refresh_token\":\"{refresh_token}\"}"
],

"oauth2_refresh_url": "/token",

"oauth2_token_data": [
"{\"redirect_uri\":\"{redirect_uri}\"}",
"{\"client_id\":\"{client_id}\"}",
"{\"client_secret\":\"{client_secret}\"}",
"{\"resource\":\"{resource}\"}",
"{\"grant_type\":\"authorization_code\"}"
],

"oauth2_token_url": "/token",

"oauth2_auth_query": [
"{\"client_id\":\"{client_id}\"}",
"{\"response_type\":\"code\"}",
"{\"resource\":\"{resource}\"}",
"{\"scope\":\"{scope}\"}",
"{\"prompt\":\"login\"}",
"{\"redirect_uri\":\"{redirect_uri}\"}"
],
"oauth2_auth_url": "/authorize",

"oauth2_no_state": false,

"env_pre_prod_params": [
"{\"client_secret\":\"{{{pre_prod.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_production_params": [
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}",
"{\"client_id\":\"{{{production.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{production.CLIENT_SECRET}}}\"}"
],
"env_staging_params": [
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}",
"{\"client_id\":\"{{{staging.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{staging.CLIENT_SECRET}}}\"}"
],
"env_development_params": [
"{\"client_id\":\"{{{development.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{development.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_local_params": [
"{\"client_id\":\"{{{local.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{local.CLIENT_SECRET}}}\"}",
],
"base_url": "https://login.microsoftonline.com/{tenant}/oauth2",
"oauth_type": "OAuth2",
"development_phase": "new",
"advanced_enabled": true,
"express_enabled": true,
"deleted_at": null,
"published": true
}

▪ Provide header information in the "oauth2_validate_headers" array, as shown in the sample array:

{
"oauth2_validate_headers": [
"{\"Authorization\":\"Bearer {access_token}\"}",
"{\"Content-Type\":\"application/json\"}"
]
}

▪ Provide scope information in the "oauth2_params_scope" array, as shown in the sample array:

{
"oauth2_params_scope": [
"{\"READ\":\"READ_PRIVILEGES\"}"
]
}

▪ Provide need URL information in "oauth2_params_other" array, as shown in the sample array:

{
"oauth2_params_other": [
"{\"needurl\":\"true\"}"
]
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

OSLC

Perform the following steps every time you want to add an OAuth provider for your OSLC server:

1. Configure OAuth on the OSLC server.

2. To add an OAuth provider for OSLC, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your OAuth client.
CLIENT_SECRET	Client secret value.	Retrieve the value from your OAuth client.
BASE_URL	Specifies the OAuth URL.	Retrieve the value from your Central Auth Server. If your OAUth client is PingFederate, this URL must be in the following format: https://<Pingfederate FQDN>:<Port>/as
VALIDATE_URL	Specifies the URL used to validate the access token.	Retrieve the value from your Central Auth Server. Example:/introspect.oauth2
RESOURCE_URL	Specifies the OSLC server URL. If you do not specify the RESOURCE_URL, then you must provide the values for OAUTH_URL, REFRESH_URL, and TOKEN_URL.	Retrieve the value from your Central Auth Server.
OAUTH_URL	Specifies the OAuth endpoint for token requests.	Retrieve the value from your Central Auth Server. Example:/authorization.oauth2
REFRESH_URL	Specifies the URL to be used to obtain access tokens.	Retrieve the value from your Central Auth Server. Example:/token.oauth2
TOKEN_URL	Provides the access token.	Retrieve the value from your Central Auth Server. Example:/token.oauth2

"oslc": {
"OSLC": {
"CLIENT_SECRET": "<client secret here>",
"OAUTH_URL": "<oauth url here>",
"VALIDATE_URL": "<validate url here>",
"VALIDATE_AUTH": "<stringified validate auth object here in format <auth>:<authObject>, authObject should be a stringified json object>",
"TOKEN_URL": "<token url here>",
"CLIENT_ID": "client id here>",
"RESOURCE_URL": "<resource url here>",
"VALIDATE_QUERY": "<stringified validate query object here in format <token>:<access_token>",
"BASE_URL": "<base url here>",
"VALIDATE_METHOD": "<validate method here>",
"REFRESH_URL": "<refresh url here>"
}
}

You must specify either the RESOURCE_URL or the authorization parameters (OAUTH_URL, REFRESH_URL, and TOKEN_URL).

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

SAP OData

Perform the following steps every time you want to add an OAuth provider for an SAP OData server:

1. Configure OAuth on the SAP server.

While configuring OAuth, provide the redirect URI as a ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

2. To add an OAuth provider for SAP OData, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your SAP OAuth client.
CLIENT_SECRET	Client secret value.	Retrieve the value from your SAP OAuth client.
BASE_URL	Specifies the Central Authorization Server URL.	https://<HostName:Port>/sap/bc/sec/oauth2
SCOPE	Space-separated list of scopes. For more information, see OAuth Scopes.	<SCOPE 1> <SCOPE 2>
RESOURCE_URL	Specifies the SAP resource URL. It is recommended to provide RESOURCE_URL while configuring OAuth. If you do not specify the RESOURCE_URL, then the user must provide it while adding an OAuth connector.	https://<Host:Port>/

"sap_odata": {
"SAP_OData": {
"CONNECTION_URL": "<SAP OData url in format https://<host>:<port>/>",
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>",
"SCOPE": "<scopes separated by space>",
"BASE_URL": "<SAP OAuth url in format https://<host>:<port>/sap/bc/sec/oauth2>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

SOAP

Perform the following steps every time you want to add an OAuth provider for your SOAP instance:

1. Configure OAuth on your SOAP instance.

2. As per your OAuth configuration, provide values in the OAuth configuration JSON file. Refer sample config.json. The following are example values that you might provide for loading OAuths:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your OAuth application.
CLIENT_SECRET	Client secret value.	Retrieve the value from your OAuth application.
VALIDATE_URL	Specifies the URL used to validate the access token.	Retrieve the value from your OAuth client.
REFRESH_URL	Specifies the URL to be used to obtain access tokens.	Retrieve the value from your OAuth client.
TOKEN_URL	Provides the access token.	Retrieve the value from your OAuth client.
AUTH_URL	Specifies the OAuth endpoint for token requests.	Retrieve the value from your OAuth client.

▪ Provide header information in the "oauth2_validate_headers" array, as shown in the sample array:

{
"oauth2_validate_headers": [
"{\"Authorization\":\"Bearer {access_token}\"}",
"{\"Content-Type\":\"application/json\"}"
]
}

▪ Provide scope information in the "oauth2_params_scope" array, as shown in the sample array:

{
"oauth2_params_scope": [
"{\"READ\":\"READ_PRIVILEGES\"}"
]
}

▪ Provide need URL information in "oauth2_params_other" array, as shown in the sample array:

{
"oauth2_params_other": [
"{\"needurl\":\"true\"}"
]
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Salesforce

Perform the following steps every time you want to add an OAuth provider for a Salesforce App:

1. Create a Salesforce app.

While creating the application, set appropriate values of the following parameters:

▪ Scopes—Provide appropriate scopes to the App.

▪ Callback URL—Enter ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

2. To add an OAuth provider for Salesforce, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Salesforce App.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Salesforce App.

"salesforce": {
"Salesforce": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

The following video demonstrates the steps required to enable OAuth configuration for Salesforce:

ServiceMax

Perform the following steps every time you want to add an OAuth provider for a ServiceMax App:

1. After logging in to ServiceMax, create a Servicemax app.

While creating the application, set appropriate values of the following parameters:

▪ Scopes—Provide appropriate scopes to the App.

▪ Callback URL—Enter ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

2. To add an OAuth provider for Servicemax, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Servicemax App.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Servicemax App.

"servicemax": {
"Servicemax": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Slack

Perform the following steps every time you want to add an OAuth provider for a Slack App:

1. Create your Slack app.

While creating the application, set appropriate values of the following parameters:

▪ Scopes—Provide appropriate scopes to the App.

▪ Redirect URL—Enter ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

2. To add an OAuth provider for Slack, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Slack App.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Slack App.

"slack": {
"Slack": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Swagger

Perform the following steps every time you want to add an OAuth provider for your Swagger instance:

1. Configure OAuth on your Swagger instance.

2. As per your OAuth configuration, provide values in the OAuth configuration JSON file. Refer sample config.json. The following are example values that you might provide for loading OAuths:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your OAuth application.
CLIENT_SECRET	Client secret value.	Retrieve the value from your OAuth application.
VALIDATE_URL	Specifies the URL used to validate the access token.	Retrieve the value from your OAuth client.
REFRESH_URL	Specifies the URL to be used to obtain access tokens.	Retrieve the value from your OAuth client.
TOKEN_URL	Provides the access token.	Retrieve the value from your OAuth client.
AUTH_URL	Specifies the OAuth endpoint for token requests.	Retrieve the value from your OAuth client.

▪ Provide header information in the "oauth2_validate_headers" array, as shown in the sample array:

{
"oauth2_validate_headers": [
"{\"Authorization\":\"Bearer {access_token}\"}",
"{\"Content-Type\":\"application/json\"}"
]
}

▪ Provide scope information in the "oauth2_params_scope" array, as shown in the sample array:

{
"oauth2_params_scope": [
"{\"READ\":\"READ_PRIVILEGES\"}"
]
}

▪ Provide need URL information in "oauth2_params_other" array, as shown in the sample array:

{
"oauth2_params_other": [
"{\"needurl\":\"true\"}"
]
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

ThingWorx

Perform the following steps every time you want to add an OAuth provider for a ThingWorx server:

1. Configure ThingWorx as a resource server to allow ThingWorx to respond to requests via the OAuth2 protocol.

2. To add an OAuth provider for ThingWorx, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your PingFederate OAuth client.
CLIENT_SECRET	Client secret value.	Retrieve the value from your PingFederate OAuth client.
BASE_URL	Specifies PingFederate OAuth URL.	https://<Pingfederate FQDN>:<Port>/as
RESOURCE_URL	Specifies the ThingWorx URL. It is recommended to provide RESOURCE_URL while configuring OAuth. If you do not specify the RESOURCE_URL, then the user must provide it while adding an OAuth connector.	https://<Thingworx FQDN>:<Port>/Thingworx

"thingworx": {
"Thingworx": {
"CLIENT_SECRET": "client secret here>",
"CLIENT_ID": "client id here>",
"RESOURCE_URL": "<Thingworx URL in format https://<Thingworx FQDN>:<port>/Thingworx>",
"BASE_URL": "<Pingfederate URL in format https://<Pingfederate FQDN>:<port>/as>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Trello

Perform the following steps every time you want to add an OAuth provider for a Trello account:

1. Create a Trello developer account and a Trello account.

In the settings, set appropriate values of the following parameter:

▪ Redirect URL—Enter ThingWorx Flow return URL under Allowed Origins, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

2. To add an OAuth provider for Trello, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CONSUMER_KEY	Specifies the consumer key to use for validation access tokens from the authorization server.	Retrieve the value from Trello developer API keys.
CONSUMER_SECRET	Consumer secret value.	Retrieve the value from Trello developer API keys.

"trello": {
"Trello": {
"CONSUMER_SECRET": "<client secret here>",
"CONSUMER_KEY": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Windchill

Perform the following steps every time you want to add an OAuth provider for a Windchill server:

1. Configure OAuth on the Windchill server.

2. To add an OAuth provider for Windchill, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your PingFederate OAuth client.
CLIENT_SECRET	Client secret value.	Retrieve the value from your PingFederate OAuth client.
BASE_URL	Specifies PingFederate OAuth URL.	https://<Pingfederate FQDN>:<Port>/as
SCOPE	Limits the application's access to a user's account by issuing access tokens on the basis of the granted scopes. To add multiple scopes, separate the scopes using comma (,).	WINDCHILL_READ, <scope1>, <scope2>
PF_IDP_ADAPTER_ID	Optional. Specifies the PingFederate IdP adapter ID from your configuration. Specify only if you have multiple IdP adapters in PingFederate.	PingFederateAdapterID
RESOURCE_URL	Optional. Specifies the Windchill URL. It is recommended to provide RESOURCE_URL while configuring OAuth. If you do not specify the RESOURCE_URL, then the user must provide it while adding an OAuth connector.	<protocol>://<Windchill FQDN>:<Port>/Windchill

"windchill": {
"Windchill": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>",
"base_url": "<base url here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Windchill RV&S

Perform the following steps every time you want to add an OAuth provider for a Windchill RV&S server:

1. Configure OAuth on the Windchill RV&S server.

2. To add an OAuth provider for Windchill RV&S, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your PingFederate OAuth client.
CLIENT_SECRET	Client secret value.	Retrieve the value from your PingFederate OAuth client.
BASE_URL	Specifies PingFederate OAuth URL.	https://<Pingfederate FQDN>:<Port>/as

"integrity": {
"integrity": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>",
"base_url": "<base url here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Zendesk

Perform the following steps every time you want to add an OAuth provider for a Zendesk app:

1. Create your Zendesk app.

While creating the application, set appropriate values of the following parameters:

▪ Scopes—Provide appropriate scopes to the App.

▪ Redirect URL—Enter ThingWorx Flow return URL, such as https://<HostName:Port>/Thingworx/Oauths/oauth/return.

The following video demonstrates the steps required to enable OAuth configuration for Zendesk:

2. To add an OAuth provider for Zendesk, provide the following values in the OAuth configuration JSON file:

Parameter	Description	Value
CLIENT_ID	Specifies the client identifier to use for validation access tokens from the authorization server.	Retrieve the value from your Zendesk App.
CLIENT_SECRET	Client secret value.	Retrieve the value from your Zendesk App.

"zendesk": {
"Zendesk": {
"CLIENT_SECRET": "<client secret here>",
"CLIENT_ID": "<client id here>"
}
}

3. Execute the LoadOAuthConfiguration service from ThingWorx Composer to load the OAuth provider to the ThingWorx Flow server.

Troubleshooting

Scenario

Solution

You cannot add an OAuth provider, if an OAuth connector is using an existing OAuth provider with the same name.

Any other valid OAuth providers present in the same JSON file are not uploaded.

• Add a unique OAuth provider name, and then load the OAuth configuration.

For example, if Gmail-1 exists in the OAuth configuration, then add Gmail-2 to the OAuth configuration JSON file as shown in the following example code:

• Delete any connectors that use the existing OAuth provider, upload the OAuth provider again, and then restart the OAuth service.

Complete the following steps to restart the OAuth service:

a. On the system where ThingWorx Flow is installed, start Command Prompt as Administrator.

b. Run the pm2 ls command to obtain the OAuth service number.

c. Run the pm2 restart <OAuth_service_number> command to restart the OAuth server.

On the system where ThingWorx Flow is installed, start Command Prompt as Administrator, and run the pm2 restart flow-oauth-server command to restart the OAuth server.

Was this helpful?