Fortinet Document Library

Version:


Table of Contents

Configuring a connector

0.0.0
Copy Link

Use the Connector Store to install and configure connectors in FortiSOAR™. The Connector Store enables you to easily view, search, install, upgrade, and uninstall connectors that are part of the FortiSOAR™ repository. Therefore, you can now perform these operations using the FortiSOAR™ UI instead of the required CLI access. For the procedure to install a connector, click here

To configure connectors into FortiSOAR™, you must be assigned a role that has a minimum of Update access to the Connectors module.

Prerequisites to configuring a connector

  • Before you can configure a connector, you must know details of how the connector will connect to the third-party tool. You must have configuration details such as, the IP address or Hostname, or server address/URL of the server or website of the third-party tool to which you will connect and perform the automated operations and credentials, either username-password pair or API key, to access that server.
    Details of the prerequisites required for each connector is present in the Prerequisites to configuring the connector section of the respective connector documentation.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Connectors that do not require configurations

Some connectors, such as Spamhaus and PDF Reader do not require any configurations. In the case of Spamhaus, the connector looks up freely-accessible Spamhaus blocklists.

You can view such connectors in FortiSOAR™ when you click Automation > Connectors. 

Click the <connector name> row to open the connection actions and bundled playbooks.
To view the list of actions that can be performed by the connector, click the Actions tab.
To view the playbook file that is bundled with the connector, click the Playbooks tab. Click the Sample - <name of the connector> - <connector version> link, in the Playbooks tab, to open the bundled playbooks.

You can also see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the connector.

You can optionally perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint or API.  To check the connectivity to the third-party tool perform a health check, by clicking the Refresh icon that is present in the Health Check bar. If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog.
If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.

Configuring a connector in FortiSOAR™ in version 5.0.0 and later

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install and configure connectors in FortiSOAR™.  

  1. Log on to FortiSOAR™.

  2. On the left navigation pane, click Automation > Connectors.  On the Connectors page, you will see the list of installed connectors, either in grid/list view or in the card view.
    Following is an image of the Connector page in the Card view.

    In the top bar of the Connectors page, you can see the number of connectors that are installed, for example, in the above image 11 connectors are installed.
    Also, you can see the status of the connector, based on the icon present on the top-left of the connector card. A connector that is installed but not configured appears with a Settings icon on a gray background, for example, the AlienVault-OTX connector. A connector that is installed and configured, for example the IMAP connector, or a connector that does not require any configuration, for example the Utilities connector, appears with a Settings icon on a blue background.
    You can search for a connector by connector name in the Search by connector name box. You can also filter connectors by clicking the Filter drop-down list and choosing between All, Configured or Not Configured filters. The chosen filter applies only to the Installed Connectors page.
    Buttons to change the view from grid to card and vice-versa are present on the right of the Connectors page. Following is an image of the Connector page in the grid view:

    You can see a list of the connectors with their associated brief descriptions, version installed and the status. The status of the connectors will be Installed for connectors that are installed but not configured, such as AlienVault-OTX, or Configured for connectors that are installed and configured, such as IMAP, or for connectors that do not require any configuration
    Click the Connector Store link to view the connector store. 
  3. To configure a connector, click the connector row (if you are in the grid view) or the connector card (if you are in the card view) to open the Connector Configuration popup. Enter the required configuration details in the Connector Configuration popup, as shown in the following image:

    Note: You can add multiple configurations for your connector if you have more than one instance of your third-party server in your environment. You must, therefore, add a unique Name for each configuration in the Configuration Name field.
    If you have previous versions of a connector and you are configuring a newer version of that connector, with the same configuration parameters, then FortiSOAR™ fetches the configuration and input parameters of the latest available version of that connector. For example, If you have 1.0.0 and 2.0.0 versions of the Database connector and you are configuring the 2.0.0 version of the Database connector, then while configuring the 2.0.0 version, FortiSOAR™ will fetch the configuration and input parameters from the 1.0.0 version of the Database connector. You can review the configuration and input parameters, and then decide to change them or leave them unchanged.
    You can activate or deactivate a configured connector by clicking on the Activate Connector or Deactivate Connector Link.
    You can also check the Mark As Default Configuration option to make the selected configuration, the default configuration of this connector, on the particular FortiSOAR™ instance. This connector will point to this configuration by default.
    Important: In the case of the SMTP connector, you must ensure that this option is selected for the configuration that is to be used for sending system notifications.
    The password type fields in FortiSOAR™ include encryption and decryption. Passwords are encrypted before saving them into the database and decrypted when they are used in actions. In case of an upgrade, connectors that are already installed will work with stored passwords.
    Connectors also include a Verify SSL field, that specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True.
    To view the documentation associated with a connector, click the Documentation link on the top-right corner of the connector configuration pane. 
  4. To save your configuration, click Save.
    To view the list of actions that can be performed by the connector, click the Actions tab.
    To view the playbook file that is bundled with the connector, click the Playbooks tab. 

  5. (Optional) You can optionally perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint or API.
    If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog.
    If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.

Points to be considered for connector configurations while upgrading to a newer version of the connector

If you are upgrading a connector to a newer version,  you must be assigned a role that has a minimum of Upgrade access to the Connectors module. For example, if you are upgrading the Symantec Security Analytics connector version from v1.0.0 to v2.0.0, then keep a note of the following points:

  • Existing (older) connector configuration fields retain their value, i.e., the value from the older configuration will be displayed in the configuration pane of the newer connector version. New connector configuration field(s), if any, will be added to the connector configuration pane. 

  • If the newly added configuration field is mandatory, and FortiSOAR™ has specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain the default value for this configuration field. For more information on the connector framework and the info.json file, see the Building a custom connector chapter.  For information on common connector framework issues, see the Common connector framework errors section in the Debugging common playbook and connector issues article present in the Fortinet Knowledge Base.

  • If the newly added configuration field is mandatory, and FortiSOAR™ has not specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain a blank value for this configuration field. If you also do not specify a value for this mandatory configuration field, then the connector configuration pane will display Partially Configured, and an error will also be displayed in the Playbook Execution Log. For more information on the Playbook Execution Log, see the Debugging and Optimizing Playbooks chapter in the "Playbooks Guide."

  • If the field type of a mandatory configuration field is changed from the older version to the newer version, for example from a text field to a drop-down list, then the value of that field will not be retrieved from the older version. However, if FortiSOAR™ has specified its default value (in the info.json file of the connector), then that value will be displayed for this configuration field the configuration pane of the newer version of the connector. If however FortiSOAR™ has not defined the default value and you also do not specify a value for this mandatory configuration field, then the configuration pane of the newer version of the connector will contain a blank value for this configuration field, and the connector configuration pane will display Partially Configured. An error will also be displayed in the Playbook Execution Log. For more information on the Playbook Execution Log, see the Debugging and Optimizing Playbooks chapter in the "Playbooks Guide."

  • If the newly added configuration field is optional, and FortiSOAR™ has specified its default value (in the info.json file of the connector), then the configuration pane of the newer version of the connector will contain the default value for this configuration field.  If there is no default value is set, then its value is set as blank.

Configuring a connector in versions 4.10.x, 4.11.x, and 4.12.x

  1. Log on to FortiSOAR™.
  2. On the left navigation pane, click Automation > Connectors.
    On the Connectors page, you will see the list of installed connectors.
  3. To configure the connector parameters, click the connector row to open the Configurations tab. Enter the required configuration details in the Configurations tab.
    Details of the configuration details required for each connector is present in the Configuration parameters section of the respective connector documentation.
    Note: You can add multiple configurations for your connector if you have more than one instance of your third-party server in your environment. You must, therefore, add a unique Name for each configuration in the Configuration Name field.
    If you have previous versions of a connector and you are configuring a newer version of that connector, with the same configuration parameters, then FortiSOAR™ fetches the configuration and input parameters of the latest available version of that connector. For example, If you have 1.0.0 version of the Symantec ATP connector and you are configuring the 1.1.0 version of the Symantec ATP connector, then while configuring the 1.1.0 version, FortiSOAR™ will fetch the configuration and input parameters from the 1.0.0 version of the Symantec ATP connector. You can review the configuration and input parameters, and then decide to change them or leave them unchanged.
    If you have previous versions of a connector and you are configuring a newer version of that connector that has different configuration parameters, then FortiSOAR™ does not fetch the configuration and input parameters of the older version of the connector, and you must reconfigure the newer version of the connector.
    You can activate or deactivate the connector by clicking on the Activate Connector or Deactivate Connector link.
    From 4.10.3 onwards, you can check the Mark As Default Configuration option to make the selected configuration, the default configuration of this connector, on the particular FortiSOAR™ instance. This connector will point to this configuration by default.
    From 4.11 onwards, password type fields are enhanced to include encryption and decryption. Passwords are encrypted before saving them into the database and decrypted when they are used in actions. In case of an upgrade, connectors that are already installed will work with stored passwords.
  4. To save your configuration, click Save.
    To view the list of actions that can be performed by the connector, click the Actions tab.
    To view the playbook file that is bundled with the connector, click the Playbooks tab. Click the Sample - <name of the connector> - <connector version> link, in the Playbooks tab, to open the bundled playbooks.
    For example, if you importing the Symantec ATP, you will see Sample - Symantec-ATP - 1.1.0 link in the Playbooks tab.
    You can also see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the connector.
  5. (Optional) You can optionally perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint or API.
    If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog.
    If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.

Use the Connector Store to install and configure connectors in FortiSOAR™. The Connector Store enables you to easily view, search, install, upgrade, and uninstall connectors that are part of the FortiSOAR™ repository. Therefore, you can now perform these operations using the FortiSOAR™ UI instead of the required CLI access. For the procedure to install a connector, click here

To configure connectors into FortiSOAR™, you must be assigned a role that has a minimum of Update access to the Connectors module.

Prerequisites to configuring a connector

Connectors that do not require configurations

Some connectors, such as Spamhaus and PDF Reader do not require any configurations. In the case of Spamhaus, the connector looks up freely-accessible Spamhaus blocklists.

You can view such connectors in FortiSOAR™ when you click Automation > Connectors. 

Click the <connector name> row to open the connection actions and bundled playbooks.
To view the list of actions that can be performed by the connector, click the Actions tab.
To view the playbook file that is bundled with the connector, click the Playbooks tab. Click the Sample - <name of the connector> - <connector version> link, in the Playbooks tab, to open the bundled playbooks.

You can also see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the connector.

You can optionally perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint or API.  To check the connectivity to the third-party tool perform a health check, by clicking the Refresh icon that is present in the Health Check bar. If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog.
If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.

Configuring a connector in FortiSOAR™ in version 5.0.0 and later

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install and configure connectors in FortiSOAR™.  

  1. Log on to FortiSOAR™.

  2. On the left navigation pane, click Automation > Connectors.  On the Connectors page, you will see the list of installed connectors, either in grid/list view or in the card view.
    Following is an image of the Connector page in the Card view.

    In the top bar of the Connectors page, you can see the number of connectors that are installed, for example, in the above image 11 connectors are installed.
    Also, you can see the status of the connector, based on the icon present on the top-left of the connector card. A connector that is installed but not configured appears with a Settings icon on a gray background, for example, the AlienVault-OTX connector. A connector that is installed and configured, for example the IMAP connector, or a connector that does not require any configuration, for example the Utilities connector, appears with a Settings icon on a blue background.
    You can search for a connector by connector name in the Search by connector name box. You can also filter connectors by clicking the Filter drop-down list and choosing between All, Configured or Not Configured filters. The chosen filter applies only to the Installed Connectors page.
    Buttons to change the view from grid to card and vice-versa are present on the right of the Connectors page. Following is an image of the Connector page in the grid view:

    You can see a list of the connectors with their associated brief descriptions, version installed and the status. The status of the connectors will be Installed for connectors that are installed but not configured, such as AlienVault-OTX, or Configured for connectors that are installed and configured, such as IMAP, or for connectors that do not require any configuration
    Click the Connector Store link to view the connector store. 
  3. To configure a connector, click the connector row (if you are in the grid view) or the connector card (if you are in the card view) to open the Connector Configuration popup. Enter the required configuration details in the Connector Configuration popup, as shown in the following image:

    Note: You can add multiple configurations for your connector if you have more than one instance of your third-party server in your environment. You must, therefore, add a unique Name for each configuration in the Configuration Name field.
    If you have previous versions of a connector and you are configuring a newer version of that connector, with the same configuration parameters, then FortiSOAR™ fetches the configuration and input parameters of the latest available version of that connector. For example, If you have 1.0.0 and 2.0.0 versions of the Database connector and you are configuring the 2.0.0 version of the Database connector, then while configuring the 2.0.0 version, FortiSOAR™ will fetch the configuration and input parameters from the 1.0.0 version of the Database connector. You can review the configuration and input parameters, and then decide to change them or leave them unchanged.
    You can activate or deactivate a configured connector by clicking on the Activate Connector or Deactivate Connector Link.
    You can also check the Mark As Default Configuration option to make the selected configuration, the default configuration of this connector, on the particular FortiSOAR™ instance. This connector will point to this configuration by default.
    Important: In the case of the SMTP connector, you must ensure that this option is selected for the configuration that is to be used for sending system notifications.
    The password type fields in FortiSOAR™ include encryption and decryption. Passwords are encrypted before saving them into the database and decrypted when they are used in actions. In case of an upgrade, connectors that are already installed will work with stored passwords.
    Connectors also include a Verify SSL field, that specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True.
    To view the documentation associated with a connector, click the Documentation link on the top-right corner of the connector configuration pane. 
  4. To save your configuration, click Save.
    To view the list of actions that can be performed by the connector, click the Actions tab.
    To view the playbook file that is bundled with the connector, click the Playbooks tab. 

  5. (Optional) You can optionally perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint or API.
    If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog.
    If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.

Points to be considered for connector configurations while upgrading to a newer version of the connector

If you are upgrading a connector to a newer version,  you must be assigned a role that has a minimum of Upgrade access to the Connectors module. For example, if you are upgrading the Symantec Security Analytics connector version from v1.0.0 to v2.0.0, then keep a note of the following points:

Configuring a connector in versions 4.10.x, 4.11.x, and 4.12.x

  1. Log on to FortiSOAR™.
  2. On the left navigation pane, click Automation > Connectors.
    On the Connectors page, you will see the list of installed connectors.
  3. To configure the connector parameters, click the connector row to open the Configurations tab. Enter the required configuration details in the Configurations tab.
    Details of the configuration details required for each connector is present in the Configuration parameters section of the respective connector documentation.
    Note: You can add multiple configurations for your connector if you have more than one instance of your third-party server in your environment. You must, therefore, add a unique Name for each configuration in the Configuration Name field.
    If you have previous versions of a connector and you are configuring a newer version of that connector, with the same configuration parameters, then FortiSOAR™ fetches the configuration and input parameters of the latest available version of that connector. For example, If you have 1.0.0 version of the Symantec ATP connector and you are configuring the 1.1.0 version of the Symantec ATP connector, then while configuring the 1.1.0 version, FortiSOAR™ will fetch the configuration and input parameters from the 1.0.0 version of the Symantec ATP connector. You can review the configuration and input parameters, and then decide to change them or leave them unchanged.
    If you have previous versions of a connector and you are configuring a newer version of that connector that has different configuration parameters, then FortiSOAR™ does not fetch the configuration and input parameters of the older version of the connector, and you must reconfigure the newer version of the connector.
    You can activate or deactivate the connector by clicking on the Activate Connector or Deactivate Connector link.
    From 4.10.3 onwards, you can check the Mark As Default Configuration option to make the selected configuration, the default configuration of this connector, on the particular FortiSOAR™ instance. This connector will point to this configuration by default.
    From 4.11 onwards, password type fields are enhanced to include encryption and decryption. Passwords are encrypted before saving them into the database and decrypted when they are used in actions. In case of an upgrade, connectors that are already installed will work with stored passwords.
  4. To save your configuration, click Save.
    To view the list of actions that can be performed by the connector, click the Actions tab.
    To view the playbook file that is bundled with the connector, click the Playbooks tab. Click the Sample - <name of the connector> - <connector version> link, in the Playbooks tab, to open the bundled playbooks.
    For example, if you importing the Symantec ATP, you will see Sample - Symantec-ATP - 1.1.0 link in the Playbooks tab.
    You can also see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the connector.
  5. (Optional) You can optionally perform a Health Check by clicking the Refresh icon that is present in the Health Check bar. The Health Check checks if the configuration parameters you have specified are correct and if connectivity can be established to the specified server, endpoint or API.
    If all the details are correct and the connectivity to the server can be established, then on the Connectors page, Available is displayed in the health check dialog.
    If any or all the details are incorrect or if the connectivity to the server cannot be established then on the Connectors page, Disconnected is displayed in the health check dialog.