Creating Authentications

ThingWorx Flow > ThingWorx Flow SDK > ThingWorx Flow CLI > Creating Authentications

ThingWorx Flow can handle any authentication scheme. It has a simpler handling mechanism for OAuth that can be setup by configuration. Any other authentication falls under the connection classification and must be coded by the connector developer when making a connection with the service through the Connection object.

Most of the services require authentication in some form. You can add an authentication mechanism using the add connection and add OAuth commands. ThingWorx Flow CLI and ThingWorx Flow server support OAuth 2.0 and OAuth 1.0 authentication.

Commonly used authentication methods are described in the following list:

• Basic authentication—A simple authentication scheme built into the HTTP protocol. You need to provide the user name and password when making a request.

• API Key authentication—Allows you to access data. For example, this mechanism involves sending a key value pair either as a query string parameter or a header.

• OAuth based authentication—Token-based authentication method that allows your account information to be used by any external service without exposing the password. For example, you can access the resources of a service by logging in the account.

For example, Windchill uses Basic and OAuth based authentication.

Creating OAuth

To create an OAuth, do the following:

1. From the command prompt, execute the following commands:

a. cd <user project root directory>

b. flow add oauth <oauth name>

The OAuth name cannot contain special characters except for hyphens (-).For example, your OAuth name can be connector name-oauth name.

The following options are available for the OAuth command:

Options	Description	Data Type
--version	Displays the version number.	[boolean]
--help	Displays the help.	[boolean]
--parentDir, -d	The parent directory for the project.	[default: “.”]
--logLevel, -1	Sets the log level.	[default: “info”]
--useV1	Indicates that oauth version 1 configuration is used.	[default: false]

A new folder, <connector name-oauth name>, is created in <projectDir>/auth/oauth/ consisting of the config.json file.

For example, if you use an action related to Gmail in your workflow, you need to first login to your Gmail account, and then authorize ThingWorx Flow workflow to perform certain tasks on your behalf as shown in the figure that follows.

The access parameters as shown in the figure above are set in the config.json file. The completed config.json file is as follows:

{
"_id": "56a0df8552199d8d51e0280d",
"created_at": "2017-04-11T14:08:59.858Z",
"updated_at": "2017-04-11T14:08:59.858Z",
"uid": "oau652869757c50d1cfbd1061",
"category": "Google",
"name": "google_gmail",
"title": "Gmail",
"icon": "google-mail",
"__v": 0,
"version": "v1",
"oauth2_params_other": [
"{\"access_type\":\"offline\"}"
],
"oauth2_params_scope": [
"{\"https://www.googleapis.com/auth/gmail.labels\":\"Manage mailbox labels\"}",
"{\"https://www.googleapis.com/auth/gmail.insert\":\"Insert mail into your mailbox\"}",
"{\"https://www.googleapis.com/auth/gmail.modify\":\"All read/write operations except immediate, permanent deletion of threads and messages, bypassing Trash.\"}",
"{\"https://www.googleapis.com/auth/gmail.readonly\":\"Read all resources and their metadata—no write operations.\"}",
"{\"https://www.googleapis.com/auth/gmail.compose\":\"Create, read, update, and delete drafts. Send messages and drafts.\"}",
"{\"https://www.googleapis.com/auth/gmail.send\":\"Send email on your behalf\"}"
],
"oauth2_validate_method": "GET",
"oauth2_validate_headers": [
"{\"Authorization\":\"Bearer {access_token}\"}",
"{\"Content-Type\":\"application/json\"}"
],
"oauth2_validate_url": "https://www.googleapis.com/gmail/v1/users/me/labels",
"oauth2_refresh_data": [
"{\"grant_type\":\"refresh_token\"}",
"{\"refresh_token\":\"{refresh_token}\"}"
],
"oauth2_refresh_url": "/token",
"oauth2_token_data": [
"{\"grant_type\":\"authorization_code\"}"
],
"oauth2_token_url": "/token",
"oauth2_auth_query": [
"{\"response_type\":\"code\"}",
"{\"approval_prompt\":\"force\"}",
"{\"access_type\":\"{access_type}\"}"
],
"oauth2_auth_url": "/auth",
"oauth2_no_state": false,
"env_production_params": [
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}",
"{\"client_id\":\"{{{production.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{production.CLIENT_SECRET}}}\"}"
],
"env_pre_prod_params": [
"{\"client_id\":\"{{{pre_prod.CLIENT_ID}}}\"}",
"{\"client_secret\":\"{{{pre_prod.CLIENT_SECRET}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"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}}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"base_url": "https://accounts.google.com/o/oauth2",
"oauth_type": "OAuth2",
"development_phase": "gold",
"advanced_enabled": true,
"express_enabled": true,
"deleted_at": null,
"published": true
}

OAUTH_ENDPOINT_OAUTH_RETURN is automatically filed by the Flow server based on the value in deploymentConfig.json file.

The table lists the various important fields and significance of the config.json file.

config.json file properties
Property	Description
base_url	Base URL. For more information, refer to the Identity Provider (IdP) documentation.
oauth_type	Do not edit this property. By default, CLI generates the OAuth2 configuration. To generate a OAuth1 configuration, use the –useV1 option.
oauth2_params_scope	Scopes defined by the application and it determines what operations can be performed on the system. The token will have scopes that the user grants the application access.
oauth2_auth_url	Generates the screen for the user name and password prompts, for the application. This value can be absolute or relative to the base URL.
oauth2_auth_query	Parameters that are required by the IdP when making a request to the auth url.
oauth2_token_url	Used to request an access token or refresh token. This value can be an absolute URL or a URL relative to the base URL.
oauth2_token_data	Contains the data that needs to be sent to the oauth2_token_url.
oauth2_refresh_url	Generates a refresh token. Some IdPs use the same URL as the token URL for requesting a refresh token.
oauth2_refresh_data	Contains data that needs to be sent to the oauth2_refresh_url.
oauth2_validate_url	Validates a token
oauth2_validate_headers	Headers that are sent in the request to the oauth2_validate_url.
oauth2_validate_method	HTTP method is used to make the validation request.

The configuration file contains information that ThingWorx Flow uses to execute various OAuth2 operations.

The property values are arrays of strings and hence need escaping. The values can be constant values or you can use text substitution. The env_local_params, env_staging_params, and env_production_params allow varying the value of various parameters to vary, based on the deployment.

The important pieces of information in the config.json file are client_id and client_secret.

For information on deploying the connectors, refer to the deployment section.

OAuth configurations should not contain sensitive information or information that is tenant specific. It includes client_id and client_secret. The information is specified as follows:

"env_pre_prod_params": [
"{\"client_id\":\"{{pre_prod.CLIENT_ID}}\"}",
"{\"client_secret\":\"{{pre_prod.CLIENT_SECRET}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],
"env_staging_params": [],
"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}}\"}",
"{\"redirect_uri\":\"{OAUTH_ENDPOINT_OAUTH_RETURN}\"}"
],

If the information is not specific to a deployment, then it should not be prefixed with the deployment name such as local or development.

For help on creating applications that use the google APIs, refer to the API Console Help. For any other application, refer to the IdP or system documentation.

For more information on creating OAuth configuration, refer to the Tutorial B.

Configuring OAuths for Out-of the-Box Connectors

ThingWorx Flow ships with a number of connectors that require OAuth to perform authorization. The first step is to create a OAuth load file. You may choose to enable all or just a few of the OAuth configurations. The OAuth load file has the following format:

{
"onedrive": {
"OneDrive": {
"CLIENT_ID": "<client-id-here>"
"CLIENT_SECRET": "<client-secret-here>"
}
}
"trello": {
"Trello": {
"CONSUMER_KEY":"<consumer-key-here>",
"CONSUMER_SECRET":"<consumer-secret-here>"
}
}
}

In the file above, the keys at the top level are names of connectors.An example of OAuth2 configuration and OAuth1 configuration is OneDrive.

Refer to the document to acquire the client-id and client-secret for each of the connectors. The display name of the OAuth configuration is at the next level. This is the text that is displayed in OAuth2 drop-downs as Add <display name> login.

Use the flow-deploy tool to load the OAuths into the system. If a matching configuration based on connector and displayName , it is updated or a new one is created.

For information on configuring OAuth for the other out of the box connectors, refer to the ThingWorx Help Center

For more information, refer to the topic Deploying Connectors.

After the tool successfully completes deployment, the new OAuths are available .

Was this helpful?