Because actions connect with external software systems, you may need to authenticate your Datadog account to the corresponding integration. An app or workflow can run successfully only if every action that requires authentication can verify the identity of your Datadog account. When granting permissions to Datadog, ensure that you’re following security best practice and only granting the permissions necessary for an app or workflow to run.

Actions can be authenticated in two ways:

• Credentials and permissions configured in the integration tile
• Connection credentials

Integration tile credentials

Credentials and account authentication that you set up in the following Datadog integration tiles automatically propagate to the corresponding actions in workflows or apps:

• GitHub
• Jira
• Microsoft Teams
• Opsgenie
• PagerDuty
• Slack
• Statuspage

Configure the integration tiles by following instructions in Datadog Integrations.

If the integration you need to set up is not listed above, set up connection credentials.

Connection credentials

Connections extend your installed integrations to give you control over workflow step authentication. Use connection credentials to authenticate a generic action or any action for which the integration tile does not offer authentication. For a list of integrations that use the integration tile for authentication, see the Integration tile credentials section. Connection credentials are only available for use within the Workflow Automation and App Builder products.

Connections support the following example use cases:

• The integration you need is not available as a built-in connection.
• You wish to authenticate a custom action. For instance, you need to use the HTTP action with your own service.
• The permissions needed are not supported by the integration, such as write permissions on AWS.
• You want granular access control, for example restricting user access to certain workflows.

Connection security considerations

Before you create a connection, think about the permissions needed to fulfill the required task and grant the connection only the necessary permissions to fulfill that task. In addition, the connection should be restricted to only the people who need to use it.

Where possible, use granular connections for different workflows or apps. For example, if you have a workflow that writes to an Amazon S3 bucket, and an app that terminates Amazon EC2 instances, do not use the same connection for both. Instead, create two respective connections, each corresponding to an IAM role with limited scope.

Work with connections

View connections

1. From the Workflow Automation page or the App Builder page, click the Connections tab. The connections list opens.
2. Click on a single line to view connection details.

Create a connection

Establishing a connection requires the following information:

• What to connect to (for example, product name, URL)
• How to authenticate (for example, API key, username/password, oauth)

To create a connection:

1. From the Workflow Automation page or the App Builder page, click the Connections tab. The connections list opens.
2. Click the New Connection button in the upper right. The New Connection dialog box appears.
3. Click on an icon to choose an integration schema.
4. Fill in the appropriate fields.
   If you want to add the connection to a connection group in the future, add one or more Identifier Tags.
5. Click Create.

Alternatively, add a connection from a workflow or app page:

The example below shows the New Connection dialog box for the OpenAI connection. Each connection requires different authentication information. The OpenAI connection requires a valid Connection Name and API Token.

Edit a connection

1. From the Workflow Automation page or the App Builder page, click the Connections tab. The connections list opens.
2. Hover over the connection you would like to edit. Edit, Permissions, and Delete icons appear on the right.
3. Click the pencil (Edit) icon. A dialog box appears.
4. Update the fields you would like to change.
5. Click Save.

Delete a connection

1. Navigate to the connections list.
2. Hover over the connection you would like to delete. Edit, Permissions, and Delete icons appear on the right.
3. Click the trash can (Delete) icon. “Are you sure?” text appears.
4. Select Delete.

Restrict connection use

To learn how to restrict connection use, see Access and Authentication for Workflow Automation or App Builder.

HTTP connection

To connect to an arbitrary service, use the HTTP connection type. For authentication options and setup instructions, see the HTTP action.

Connection identifier tags

You can add identifier tags to connections. The tagging rules for connections are based on Datadog tags, with the following additional requirements:

• Identifier tags must follow the format tag:value, and additional colons are not allowed. For example, the identifier tags env:staging:east and env are invalid formats for connection tags.
• Identifier tags must start with a letter, after which they can contain:
  • Alphanumerics
  • Underscores
  • Minuses
  • Slashes
  • Exactly one colon
• default is a reserved value for connection identifier tags. It can’t be used as a stand-alone tag key or as a tag value. For example, default:yes and aws:default are invalid for connection tags.

Connection groups

You can create groups of connections so that your workflows and apps can authenticate into the correct account or accounts based on the given inputs. Connections can be grouped together only if they share the same integration (for example, you cannot group GCP and AWS connections within the same group).

You define the members of a connection group using a connection’s Identifier Tags. For example, you can create a connection group consisting of AWS accounts that have the account_id tag.

Each connection in the group must have a set of unique identifier tags so that a workflow can dynamically select the correct connection at runtime. For example:

• connectionA {account_id:123456789} and connectionB {account_id:987654321} can be grouped together.
• connectionA {account_id:123456789} and connectionC {account_id:123456789} can’t be grouped, because the group would contain duplicate tag values.

Create a connection group

To create a connection group:

1. Navigate to the connections list.
2. On the left, click Groups.
3. Click + New Group, then select an integration.
4. Enter a group name, then enter a set of up to three Identifier Tags that the connections you want to include in your group all have.
5. Under Confirm Group, use the checkboxes to select the specific members of your group.
6. Click Next, Confirm Access, then choose your desired access level for the group.
7. Click Create.

Use a connection group

To use a connection group:

1. In your workflow or app, select an action that requires a connection.
2. In the Connection field, in the drop-down, select the desired connection group under Groups.
3. Fill in the desired values for the connection group Identifiers. For example, if your connection group is defined using the env Identifier Tag, and you have two environments, prod and staging, you could use either of those values (or an expression that evaluates to one of those values).
4. Fill in any other required step values, then click Save.

Note: You can only use connections within a group if you have Resolver permission for those connections. If a workflow or app tries to use a connection you don’t have Resolver permission for, it fails with a 403 Forbidden error. To fix this issue, you can:

• Configure the workflow or app so that it can’t point to a connection that doesn’t have a Resolver permission.
• Remove the connection that doesn’t have a Resolver permission from the connection group.
  Note: If you are using a connection group for multiple workflows or multiple apps, removing a connection that another workflow relies on causes that workflow to fail.

Update a connection group

If you have edit access to a connection group, you can update the following attributes:

• Group name
• Identifier Tags (these can never be empty, but they can be completely replaced)
• Connections (a group can be empty)

Delete a connection group

To delete a connection group:

1. Hover over the group you want to delete and click the delete (trash can) icon.
2. Click Delete.

Further reading

Additional helpful documentation, links, and articles:

Getting Started with Workflow AutomationDOCUMENTATION App Builder documentationDOCUMENTATION

Do you have questions or feedback? Join the #workflows or #app-builder channel on the Datadog Community Slack.