Overview
When integrating Bizagi with external systems, you can use two types of connectors (as described in Creating connectors): Easy REST and Custom connectors. The preferred and recommended choice when creating connectors is Easy REST, but one of the variables you must consider before deciding to use this type of connector is the authentication methods supported.
Supported authentication methods
Easy REST connectors use predefined authentication standards for the login of your connector in the external system you want to connect with. These standards can be selected when creating the connector from the Connector Editor. On the other hand, for Custom connectors the authentication mechanism needs to be coded by the author creating the connector (and can use any type of authentication beyond those supported by the Easy REST).
The authentication methods supported by Easy REST Connectors are:
•Basic
The typical HTTP basic authentication using a username and password (https://tools.ietf.org/html/rfc2617).
•Digest
Can be seen as similar to basic authentication but while adding some encryption features for the password (https://tools.ietf.org/html/rfc2617).
•OAuth 2.0
OAuth is a relatively new protocol with all of its potential oriented to cloud services (https://tools.ietf.org/html/rfc6749) that consider authorization aspects. Due to its quick evolution, OAuth 2.0 version has a significant flexibility and offers several sub-types (i.e grant types) which imply variants in the authentication flow spec. Bizagi Easy REST connectors support three of these grant types (additional ones need to be approached via a Custom connector):
oClient credentials grant.
oResource owner password.
oAuthorization Code Grant.
|
Consider that regardless of the authentication method, Bizagi connectors support responses from external systems in a JSON format (XML-based responses are not supported). |
Authentication methods configuration
Within your Easy REST connector, each action can be configured with a different authentication method. To do these configurations, consider following:
1.When you create a new action in your connector, go to the Authorization tab and select any of the available authentication methods.
Every time that you create a new action, you can select the authentication method that suits the action.
|
Note that you may select any authentication method for each action (or none at all). If you download a connector from the Connector Xchange, the actions will not have an authentication method configured, hence, you will need to configure each action's authentication method before using the connector. For more information about these options, refer to Connector Editor user interface explained. |
2.When installing and configuring your connector in Bizagi Studio, make sure you select from the drop down list that corresponding authentication method.
|
When using more than one authentication method within your actions, you will need to create a new configuration instance for that connector per each of the authentication method you want to use. For more information about these options, refer to Installing and configuring connectors. |
3.Finally, provide the values for the parameters that are prompted for that given type of authentication.
The exact parameters will depend on each authentication method.
Refer to the following section to check the parameters used by each authentication method.
For more information on how to configure the authentication methods in Bizagi go to this article.
Authentication parameters
Each authentication method has a number of parameters required for its configuration, these are listed below.
Basic Authentication
Basic authentication typically uses username and password with which the user identifies himself in the external system (provider):
Digest Authentication
Digest authentication typically uses username and password with which the user identifies himself in the external system (provider):
OAuth2 Authentication
OAuth2 authentication uses different parameters according to its sub-type of authentication.
Client credentials grant
Parameter |
Description |
|---|---|
grant_type |
Required parameter. Its value MUST be set to "client_credentials". By default, this parameter is not editable (as it does not change). |
client_id |
Required parameter. Identifier provided by the external system (provider) during the registration process. |
client_secret |
Required parameter. The password provided by the external system (provider) during the registration process. This field is masked to prevent unauthorized users from viewing it and should be treated as a password. |
token_url |
Required parameter. URL that provides the access token for the specified resources. This value can usually be found in the provider's documentation. The URL MUST use the https protocol. |
scope |
Optional parameter. Defines which resources are accessed from the resource server. Depending on the system Bizagi is connecting to, the scope can be configured from the connected system or directly within the external system (provider). Multi-scoped values are typically delimited by spaces. This value can usually be found in the provider's documentation. |
Resource owner credentials grant
Parameter |
Description |
|---|---|
grant_type |
Required parameter. Its value MUST be set to "password". By default, this parameter is not editable (as it does not change). |
token_url |
Required parameter. URL that provides the access token for the specified resources. This value can usually be found in the provider's documentation. The URL MUST use the https protocol. |
username |
Required parameter. Corresponds to the name with which the user identifies himself in the external system (provider). |
password |
Required parameter. Corresponds to the password with which the user is authenticated in the external system (provider).. This field is masked to prevent unauthorized users from viewing it and should be treated as a password. |
scope |
Optional parameter. Defines which resources are accessed from the resource server. Depending on the system Bizagi is connecting to, the scope can be configured from the connected system or directly within the external system (provider). Multi-scoped values are typically delimited by spaces. This value can usually be found in the provider's documentation. |
Authorization Code Grant
Parameter |
Description |
|---|---|
response_type |
Required parameter. Its value MUST be set to "code". By default, this parameter is not editable (as it does not change). |
redirect_uri |
Required parameter. After completing its interaction with the resource owner, the authorization server directs the resource owner's user-agent to the client. The authorization server redirects the user-agent to the client redirection endpoint (previously established with the authorization server during the client registration process or when making the authorization request). In Bizagi Studio, this parameter is by default https://build.bizagi.com/redirectOauth2.html (site that is always available and supports HTTPS, considering that some OAuth2 providers demand this protocol for configuring the Authorization Code Grant grant type). |
client_id |
Required parameter. Identifier provided by the external system (provider) during the registration process. |
client_secret |
Required parameter. The password provided by the external system (provider) during the registration process. This field is masked to prevent unauthorized users from viewing it and should be treated as a password. |
auth_url |
Required parameter. URL of the external system (provider) that displays to the user an authorization screen. This value can usually be found in the provider's documentation. The URL MUST use the https protocol. |
token_url |
Required parameter. URL that provides the access token for the specified resources. This value can usually be found in the provider's documentation. The URL MUST use the https protocol. |
scope |
Optional parameter. Defines which resources are accessed from the resource server. Depending on the system Bizagi is connecting to, the scope can be configured from the connected system or directly within the external system (provider). Multi-scoped values are typically delimited by spaces. This value can usually be found in the provider's documentation. |
access_type |
Optional parameter in some external systems (providers). Its values are offline and online. If the value is offline, the first time the access token is obtained, a refresh token its also received. Once the access token expires, Bizagi can use the refresh token to connect with the external system again. On the contrary, if the value is online, only an access token is received. Bizagi recommends reviewing the provider's documentation to know how to obtain the refresh token. |
Multi-environment credentials
Note that you may provide different values for authentication parameters in each of the different environments (development, test and production), by switching between tabs.
It is not necessary to input details for test and production environments right away because you can edit or fill out blanks at any moment (if you do not have the intention to deploy your process at this point).
Last Updated 1/9/2024 12:28:56 PM