Connector Credentials
This page describes using credentials for connectors.

Connector Credentials

The connector APIs support credentials for the repositories that connectors access.

The following connector flavors require credentials:

The following connector flavors optionally support credentials:

Credentials

You configure credentials in the Create Connector API by using the credentials parameter. The parameter accepts a JSON object where you specify the credentials information. The credentials properties depend on the flavor of the connector. For more information, see the individual connector flavor documentation.

Credentials Policy

Along with credentials, you must configure a credentials policy. The credentials_policy parameter allows you to specify options for when the system can decrypt credentials. The parameter accepts a JSON object, containing key value pairs.

For credentials_policy, you must set the notification_email attribute. This email address allows Haven OnDemand to send you decryption tokens for the cloud flavor connectors. It also allows Haven OnDemand to send other information, such as successful decryption and failure to decrypt. This process allows you to identify potential threats, for example if you receive a notification of a decryption that you did not initiate. You can tune the types of notification emails that you want to receive by using the notification_email_frequency property in the credentials policy.

To protect the credentials, you can also set the key_expiration property to specify when your credentials policy expires. Upon expiration, you must update your credentials with a new policy to continue using either the same or new credentials.

For cloud flavor connectors, the Start Connector and Retrieve Config APIs require a decryption token. You obtain this token by email when you attempt to use these APIs. To protect the token further, you can set the token_occurrences and token_expiration options for the credentials policy, to tune your usage of connector credentials to avoid potential threats. These options allow you to indicate how many times you can use a token for decryption, and how long you can use it for before it expires.

For the full list of attributes that you can specify in the credentials policy, see the individual connector flavor documentation.

Example Notification Emails

An email with a decryption token has the following format:

For your connector dropbox3
Haven OnDemand Credentials Token Notification

The token for your connector dropbox3 is: xwfpohfjnm

An email notification for a successful decryption has the following format:

For your connector dropbox1
Haven OnDemand Connector Credentials Notification

The decryption was successfully complete for connector dropbox1

An email notification for a failed decryption has the following format:

For your connector dropbox1
Haven OnDemand Connector Credentials Notification

The decryption was unsuccessfully for connector dropbox1
The decryption was attempted on an expired policy

Create Connector API

For the connectors to support credentials, the Create Connector API supports the credentials and a credentials_policy parameters. Credentials_policy is required if you want to create a connector with credentials. For more information about credentials and credentials_policy, see the individual connector flavor documentation.

Note: If you create a connector with credentials, you cannot remove the credentials. To remove credentials settings, you must create a new connector without credentials configured.

Update Connector API

The Update Connector API supports the credentials and credentials_policy parameters.

For security reasons, you must update the credentials_policy parameter when you update the credentials for a connector. Similarly, you must update credentials (and credentials_policy) when you update any of the destination, schedule, or config parameters.

Start Connector API

The Start Connector API token parameter allows the two factor authentication to decrypt the configuration credentials. Two factor authentication is required.

When you call the Start Connector API without a token, it sends a unique decryption token to the email address you have configured in the credentials_policy notification_email property. If you already have a valid decryption token, you can use it immediately by passing it into the token parameter.

The next time you call the Start Connector API, you must specify the token that was sent in the email. If you specify an incorrect or expired token, the API generates a new decryption token and sends it by email again.

Retrieve Config API

The Retrieve Config API also supports the token parameter for two factor authentication to decrypt the configuration credentials for cloud flavor connectors.

When you set the output parameter to config_attributes, you can also set the following parameters to return the configured credentials and credentials_policy attributes:

API Type Description
include_credentials Array A list of credentials properties to return.
include_credentials_policy Array A list of credentials_policy properties to return.

If you set either of these parameters, the API attempts to decrypt the configured credentials and credentials_policy properties and return the specified values. Because the API must decrypt the credentials to return these values, you must supply a decryption token.

When you call the Retrieve Config API without a token, it sends a unique decryption token to the email address you have configured in the credentials_policy notification_email property. If you already have a valid decryption token, you can use it immediately by passing it into the token parameter.

The next time you call the Retrieve Config API, you must specify the token that was sent in the email. If you specify an incorrect or expired token, the API generates a new decryption token and sends it by email again.

Note: If you set output to config_file, and the connector has configured credentials, the API requires a decryption token to decrypt and return the credentials.

WARNING: When you use the include_credentials and include_credentials_policy parameters, your credentials and credentials_policy information returns in plain text.