Accounts

Automatically fetch data from your external web services with accounts. Learn what is an account, how it works, and how to create accounts for external web services.

Creating accounts

Whenever you use external web services (for example, Gmail, Dropbox, Evernote, etc.) in your workflow, webMethods.io Integration platform accesses those services on your behalf to perform the specified tasks. To do this, you need to grant the necessary permissions and basic account details such as client ID, client secret to webMethods.io Integration. This can be done using accounts.

The accounts are created and used at project level. Meaning, once you create an account for a specific project, you can use it in any workflow created under that project. However, it cannot be used outside that particular project. It is important to remember that, once you create an account (let’s say for Gmail), you can use the same account for all actions and triggers of Gmail connectors. You need not create a new account for different actions of the same service. Also, there is no limit to the number of authorizations you can create for a service.

Creating accounts is very easy with webMethods.io Integration. We will understand how to create an account with the help of an example:

Let’s say you want to create an account for Trello. To do this, add the Trello connector on canvas and configure the Create Board action.

Here, you can see the Authorize Trello field. From here, you can create a new account, or access an existing account.

To create a new account, hover over the + button. You will see two options:

1. Creating account by generating keys

In the default authorization method, webMethods.io Integration platform generates necessary keys to access your account data. To do so, you need to grant the webMethods.io Integration platform the relevant permissions.

To create an account with default authorization method, click + and then select Default Authorization option.

This will take you to the Trello log in page. To authenticate yourself as a user, you need to log in to Trello by entering your credentials. Once this is done, (or if you are already logged in to Trello), the next page will ask you to authorize webMethods.io Integration to perform certain actions on your behalf. Click ALLOW to proceed.

This will redirect you to the canvas where you will be prompted to provide a suitable name for the account you are about to create. You can optionally use the default name for the account.

Once this is done, click Add. This will add the specified Trello account for your webMethods.io Integration account.

Now when you click on the Authorize Trello drop-down icon, you will see the Trello account you just created in the drop-down list.

You can now use this account in any workflow of the project for which you have created this account.

2. Creating account by using existing keys

If you have all the necessary keys and account details required to create an account, you can choose the second method. To do this, click the + button and select the (Or) option.

A pop-up window will appear on screen, where you will be prompted to enter the relevant keys/information required to create the Trello account.

Note: Apart from the Account Name field, the rest of the fields that appear in this form will vary depending on the application for which you are creating the account.

Once you have entered the required details, click Save.

This will create the account for the specified connector.

Now when you click on the Authorize Trello drop-down icon, you will see the newly created account in the drop-down list.

You can now use this account for any workflow created under the project for which you have created this account.

3. Creating account for connection-based connectors

There are some connectors, which don’t support OAuth, where you can grant webMethods.io Integration the necessary permissions to generate keys on your behalf. For such connectors, you need to provide the necessary details required by the connector API to create an account.

Let’s say you want to create an account for Salesforce CRM.

To do so, add the Salesforce CRM connector on the canvas and select any action in the Select Action drop-down list.

When you click on the + button given beside the Connect to Salesforce CRM field, a pop-up window will appear on screen.

Note: Apart from the Account Name field, the rest of the fields that appear in this form will vary depending on the application for which you are creating the account.

Provide the necessary details and click Add. This will create the account for the specified connector.

You can now use this account for any workflow created under the project for which you have created this account.

Managing project-level accounts

You can view, create, modify, and delete the accounts created under a specific project.

To do this, navigate to the relevant project, click Configurations, and click Accounts.

Viewing accounts

In the Accounts screen under Configurations tab, you can view the list of all accounts created for all connectors under the specified project. It has following details:

Creating accounts

You can create additional accounts for a specific connector by clicking on the + icon given against the existing account name. The procedure to create a new account remains same as explained here.

Note: You cannot create accounts for connection-based connectors from the Configurations tab.

Editing and deleting accounts

You can edit or delete the existing accounts. To edit or delete an account, hover over the name of the account.

You will see two icons—Edit and Delete.

Editing accounts

To edit the account, click the Edit icon, and update the relevant details in the Edit Account window that appears.

Note: If you have created the account using the Default Authorization method, you can edit only the name of the account. For all other types of accounts, you can edit all details available in the form field.

Once you have made the changes, click Save.

Deleting accounts

To delete the account, click the Delete icon.

You will be prompted to confirm the delete action.

Click Delete. This will delete the specified account from your project.

If you have used the account in any workflow(s), you will be prompted to remove the account from the workflow(s) first.

Once this is done, go back to the Configurations tab, and repeat this procedure.

Managing workflow-specific accounts

All accounts used in a specific workflow can be viewed and deleted via Workflow Settings panel.

To do so, open the relevant workflow on canvas, click the Workflow Settings icon located at the top-right corner of the canvas, and click Accounts.

From here, you can view and delete the accounts used in the workflow.

Note: Deleting an account from the Workflow Settings panel, will only remove it from the current workflow. It will continue to be available in all other workflows till you delete it permanently from the Configurations tab.

Configuring OAuth V2.0 authentication

While creating an account, the user associates only one connection type or authentication scheme with an account. As some SaaS providers such as Salesforce CRM offer multiple authentication options to access their APIs, you now select different authentication types for the same application while creating an account.

Let’s look at an example to understand how OAuth V2.0 authentication works. Let’s say you want to create an account for Salesforce CRM and use OAuth V2.0 type of authentication.

To configure OAuth V2.0 authentication, add the Salesforce CRM connector on canvas and configure an account.

If you already have the operations created from OAuth V2.0 type account, then select one. Else create a new custom action. Read more about custom actions.

When you click on the + button given beside the Select Action field, the Add Custom Action window appears. Let’s look at the steps involved in setting up OAuth V2.0 authentication.

1. Connect to an account

Here, you see Select Authentication type field. The field lists the connection types based on the supported authentication schemes by the connector.

Click Select Authentication type drop-down list to view the connection types available for the selected application. You will see three options:

Select OAuth V2.0 (Authorization Code Flow)

Next, you see the Authorize Salesforce CRM field. From here, you can create a new account, or access an existing account.

Hover over the + button to create a new account. You will see two options:

In the default authorization method, webMethods.io Integration platform generates necessary keys to access your account data. To do so, you need to grant the webMethods.io Integration platform the relevant permissions.

To create an account with the default authorization method, click + and then select Default Authorization option.

This will take you to the Salesforce login page. To authenticate yourself as a user, you need to log in to Salesforce by entering your credentials. Once this is done, (or if you are already logged in to Salesforce), the next page will ask you to authorize webMethods.io Integration to perform certain actions on your behalf. Click ALLOW to proceed.

This will redirect you to the canvas where you will be prompted to provide a suitable name for the account you are about to create. You can optionally use the default name for the account.

Once this is done, click Add. This will add the specified Salesforce account for your webMethods.io Integration account.

Now, when you click on the Authorize Salesforce CRM drop-down icon, you will see the Salesforce account you just created in the drop-down list.

You can now use this account in any workflow of the project for which you have created this account.

Certificates

Keystores and truststores are files that function as repositories for storage of keys and certificates necessary for SSL authentication, encryption/decryption, and digital signing/verification services. Keystores and truststores provide added layers of security and ease of administration, compared to maintaining the keys and certificates in separate files.

Keystore and truststore files exist within the file system of your operating system, and since these are critically important files, you want to maintain them in a secure directory path. If either of these files cannot be located, authentication will be disabled and no connection with the server can be made. It is recommended that only users serving as administrators have access to these certificate files.

webMethods.io Integration enables you to manage keys and certificates and stores its private keys and SSL certificates in keystore files and the trusted roots for the certificates in truststore files. Keystores and truststores are secure files with industry-standard file formats.

If you want to run services that submit HTTPS requests to other resources on the Internet, your server will be acting as a client and will receive certificates from these resources. In order for these transactions to work, your server must have copies of their public keys and signing CA certificates.

To identify a particular keystore or truststore file, or private key within a keystore, webMethods.io Integration uses aliases. The use of aliases simplifies keystore and truststore management, because you do not need to enter the path information when specifying a keystore, truststore, or the private key.

For a webMethods.io Integration component to be SSL authenticated, it must have a valid, authorized X.509 certificate installed in a keystore file and the private key and signing certificate for the certificate issuer (CA) installed in a truststore file.
The following figure illustrates these requirements and the relationship between the two files.

As shown in the above figure, the same truststore file can contain multiple trusted root certificates (public keys for the signing CAs). These trusted roots might be associated with numerous keystore files. A keystore file can contain the key pairs for multiple webMethods.io Integration components, and the entire certificate chain required for a component’s authentication.

With a certificate chain, it is necessary to validate each subsequent signature in the list until a trusted CA certificate is reached. For webMethods.io Integration, you must include the entire chain of certificates in a keystore and truststore. Also, any root CA certificates in use by clients must be in a webMethods.io Integration truststore.

You can add, edit, delete, or view keystore and truststore aliases from the Certificates page (Projects > Select a Project > Configurations > Certificates) and can use them to secure your Accounts. See Accounts to learn what is an account, how it works, and how to create accounts for external web services.

To add a Keystore, from the webMethods.io Integration navigation bar, click Projects > Select a Project > Configurations > Certificates > + New Certificate > New Keystore.

To add a Truststore, from the webMethods.io Integration navigation bar, click Projects > Select a Project > Configurations > Certificates > + New Certificate > New Truststore.

Add Keystore

webMethods.io Integration uses a special file called a keystore to store SSL certificates and keys. A keystore file contains one or more pairs of a private key and signed certificate for its corresponding public key. The keystore should be strongly protected with a password, and stored (either on the file system or elsewhere) so that it is accessible only to administrators.

You can upload a Keystore file to store SSL certificates and keys. From the Add Keystore Certificate window, you can create aliases for the Keystore, so that they can be referenced while creating an Account in webMethods.io Integration.

The default, certificate file format for the webMethods.io Integration keystore is JKS (Java keystore), the proprietary keystore implementation provided by Oracle. You can also use PKCS12, a commonly used and standardized certificate file format that provides a high degree of portability. Other keystore types can be made available by loading additional security providers.

You can create webMethods.io Integration keystores at the command line using keytool, the Oracle Java certificate editor. You can also use other standard tools such as OpenSSL and Portecle. Software AG does not provide its own set of keystore utilities for creating keystore files.

To add a Keystore

  1. From the webMethods.io Integration navigation bar, click Projects > Select a Project > Configurations > Certificates > + New Certificate > New Keystore.

  2. Provide a name and description for the Keystore file.

  3. In the Type field, select the Keystore file format. This is the certificate file format of the keystore file, which by default is JKSfor keystores. You can also use PKCS12 format for a keystore.

  4. In the Provider field, select the provider from the list of available providers. This is the provider that is used for the keystore type. The corresponding provider will be available in the provider list.

  5. Click Browse to select the Keystore file.

  6. In the Passphrase field, enter the passphrase for the Keystore file. The passphrase must have been defined at the time the Keystore was created.

  7. Click Next to protect the Key Aliases with passphrases. A key alias is a label for a specific key within a Keystore. Enter a passphrase for each Key Alias found in the Keystore file, and then click Finish to upload the Keystore file. The uploaded Keystore file can be used while creating an Account. See Accounts to learn what is an account, how it works, and how to create accounts for external web services.

Add Truststore

webMethods.io Integration uses a truststore to store its trusted root certificates, which are the public keys for the signing CAs. Although a truststore can contain the trusted roots for entire certificate chains, there is no requirement for the organization of certificates within a truststore. It simply functions as a database containing all the public keys for CAs within a specified trusted directory.

The default format for a truststore is JKS. You can create and manage JKS truststores at the command line using keytool, the Oracle Java certificate editor.

webMethods.io Integration allows you to upload a Truststore file, which contains the trusted root of the certificate or signing authority (CA). From this screen, you can create aliases for the Truststore, so that they can be referenced while creating an Account for an Application.

To add a Truststore

  1. From the webMethods.io Integration navigation bar, click Projects > Select a Project > Configurations > Certificates > + New Certificate > New Truststore.

  2. Provide a name and description for the Truststore file.

  3. In the Type field, select the Truststore file format. This is the certificate file format of the truststore, which by default is JKS.

  4. In the Provider field, select the provider from the list of available providers. This is the provider that is used for the truststore type.

  5. Click Browse to select the Truststore file.

  6. In the Passphrase field, enter the passphrase for the Truststore file. The passphrase must have been defined at the time the Truststore was created and is used to protect the contents of the Truststore.

  7. Click Save to upload the Truststore file. The uploaded Truststore file can be used while creating an Account. See Accounts to learn what is an account, how it works, and how to create accounts for external web services.