Skip to main content
The Connections tab in your Project is a central location for creating and managing all aspects of a connection to an external service. The entire connection is stored as a reusable, named object. The connection object includes all the configuration that is required to connect to a specific service. This may include a URL, username, secret, etc. Once created on the Connections tab, the object is then available for you to select in any place where you need a connection to that service, for example from within a component that queries that service. This means:
  • The URL, username, and credentials all travel together in one place.
  • The same connection configuration can be referenced across multiple components and pipelines.
  • Changing a credential on the Connections tab updates it everywhere it’s used; no pipeline edits are required.
  • You can use a “test connection” endpoint to test your connections on an environment as part of your CI/CD process.
Each connection object connects to a single provider, but you can have multiple connection objects that connect to the same provider (for example, if you wish to connect with different usernames due to differing privilege levels).
In earlier versions of , different types of connection were managed in different ways. Customers who have been accustomed to that older operating model can continue operating seamlessly under the new model, but should read Understanding the new connections model to understand the changes.

​
Manage connections

The Connections tab lists every connection available to the project. The following details are shown:
  • Name
  • Description (optional)
  • Provider (also showing the authorization type: Username & Password, OAuth, etc.)
  • Created on (date and time)
On this screen you can perform the following actions:
  • Use the Search box to search for a specific connection by name.
  • Click Add to add a connection.
  • Click the three dots … next to the connection to access a menu of actions you can take to manage that connection:
    • Edit
    • Delete
  • Editing or deleting a connection object automatically affects every component that uses that connection and may cause pipelines to fail.
  • A deleted connection can’t be recovered.

​
Add a connection

  1. Click Add on the Connections tab.
    You can also create a new connection when configuring a component, as part of setting the component’s Connection property.
  2. Select the service provider you want to connect to.
    • To create a simple secret (for example, to store a simple key or token), select Generic secret as the provider. See Generic secrets, below, for details.
    • For some service providers (for example, Salesforce), you see two provider options: the standard connections variant and a legacy variant that uses the old credential model. We recommend you always use the standard variant for all new connections.
  3. Click Continue.
  4. On the following screen, enter the details of the connection.
    • Name: Enter an appropriate name for the connection object. This name is used to reference this connection in pipelines, and cannot be changed after creation. The name may only contain letters, numbers, underscores, single spaces, parentheses, and hyphens. Any whitespace added to the start or end of the name is automatically trimmed.
    • Provider: This displays the provider selected on the previous screen and can’t be changed here. (Not required for a Generic secret.)
    • Authentication type: Select an authentication type (for example, API Key, OAuth 2.0 Authorization Code) from the drop-down. The drop-down only shows authentication types supported by the provider. (Not required for a Generic secret.)
    • Description: Optionally enter a brief description to help you identify the purpose of the connection. Maximum 255 characters.
  5. Enter the Values for the connection. These values vary depending on the Provider and the Authentication type. For an OAuth type, see Authenticate an OAuth connection, below. You need to provide Default values and/or environment-specific values. Read Understanding environment defaults, below, to learn how default and environment-specific values interact. The exact values you need to create depend on the connection type. For details, select your connection type from the tabs below.
  6. Each data provider connector must be configured depending on the requirements of the data provider. For example, some providers require you to specify a URL, or an account name, or similar, as part of the connection. For details of the connection configuration, see the component documentation for the specific connector. Generic secret is handled differently and described in Generic secrets, below. The following providers are currently supported:
    This is not an exhaustive list of data provider connectors. If a connector is not listed here, it does not use the Connections model, and you must configure the connection directly in the component’s properties.
  7. Click Add.

​
Authenticate an OAuth connection

If a connection uses OAuth 2.0 for authentication, it must be authorized through the service provider’s own portal. The exact mechanism depends on the service provider. Follow this process to authorize an OAuth.
  1. Click Authorize.
  2. A new browser tab opens, connecting you to the third party. Log in to your account, and complete the connection (e.g. in Google, click Allow). Upon success, this browser tab closes.
Your new OAuth connection is ready for use with corresponding third-party connectors. If the provider requires completion of additional fields, read the relevant guide for further details: This list does not include all the OAuth providers that are available in —if no guide is linked for a specific OAuth provider, this means that the process is simple enough that no guide is required (e.g. a single acceptance step, or similar process). The following providers don’t have a dedicated guide, but need some additional detail:

​
Bing

To create an OAuth connection for use with the Bing Ads Load and Bing Ads Query connectors, you need your Bing Ads developer token, customer ID, and account ID. To find these credentials, read the following sections of the Bing Ads API documentation:

​
Google

If you see the error “This app is blocked” from Google during the OAuth creation process, you may need to alter your Google security settings to allow app access:
  1. Log in to the Google Admin console with an account that has administrator privileges.
  2. Follow the instructions to configure a new app in the Manage app access to Google services & add apps section of the Google documentation.
  • ’s client ID is 192174083921-gcguirlj6ltqcreni233koj6r1r3ner1.apps.googleusercontent.com.
  • You need to grant Trusted access.

​
Microsoft Dynamics 365

The account you use to authorize the OAuth connection to Microsoft Dynamics 365 must have at least the Basic (also known as User) access level and Read privileges. For more information, read the Microsoft Dynamics 365 Security roles documentation. To create an OAuth connection for Microsoft Dynamics 365, you need:
  • Your Microsoft Dynamics 365 organization URL. This is the first part of the URL shown when you log in to Microsoft Dynamics 365, for example https://companyname.crm11.dynamics.com.
  • Your Microsoft Dynamics 365 edition.

​
Microsoft Dynamics CRM

To create an OAuth connection for Microsoft Dynamics CRM, you need:
  • Your client ID and client secret. These are created when you register an app. For more information, read the Microsoft Register an app tutorial.
  • Your Microsoft Dynamics CRM URL. This is the first part of the URL shown when you log in to Microsoft Dynamics 365, for example https://companyname.crm11.dynamics.com.
  • Your Azure tenant ID. To find this, read the Microsoft Find tenant ID through the Microsoft Entra admin center documentation.
  • Your CRM version.

​
Microsoft SharePoint

To create an OAuth connection for Microsoft SharePoint, you need your SharePoint root URL, for example https://companyname.sharepoint.com.

​
Generic secrets

The way a secret is stored (and, therefore, the way you create the secret definition) depends on whether you are using a Matillion Full SaaS or Hybrid SaaS operating model.
In a Hybrid SaaS implementation using Matillion for Snowflake, secrets are stored natively within a Snowflake schema instead. Read Secrets in Matillion for Snowflake for details.
For a full discussion of secrets, read Secrets overview. To create a generic secret, follow the process in Add a connection, above, then configure the secret as described below.

​
Create a generic secret - Matillion Full SaaS

When creating a secret, it is recommended that secret definition names do not end with a hyphen followed by six characters, as this can cause issues with the AWS Secrets Manager that Matillion Hybrid SaaS uses. To quote the AWS documentation:
Do not end your secret name with a hyphen followed by six characters. If you do so, you risk confusion and unexpected results when searching for a secret by partial ARN. Secrets Manager automatically adds a hyphen and six random characters after the secret name at the end of the ARN.
Configure your secret definition by completing the following properties:

​
Create a generic secret - Hybrid SaaS

In a Matillion Hybrid SaaS deployment model, you store secrets in AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager in your own cloud infrastructure. When you created the , you should have identified which secrets managers or key vaults it has access to. If you’re using an Azure , you can store secrets in any Azure key vault that your has access to. When you add a new secret definition, you can choose which of your key vaults the secret is stored in. The secret definition doesn’t hold the secret directly. Instead, it’s simply a pointer to the appropriate secret in your own secrets manager/key vault. Before you create this “pointer”, you must first create the secret for it to point to. For details, read Secrets and secret definitions. Configure your secret definition by completing the following properties:
If using AWS Secrets Manager, it is recommended that secret definition names do not end with a hyphen followed by six characters. To quote the AWS documentation:
Do not end your secret name with a hyphen followed by six characters. If you do so, you risk confusion and unexpected results when searching for a secret by partial ARN. Secrets Manager automatically adds a hyphen and six random characters after the secret name at the end of the ARN.

​
Understanding environment defaults

Each connection should be given default values for the connection credentials. Default values are a fallback for all environments that have defaults enabled. You can then add specific overrides for each environment as needed. Pipelines will fail in any environment that lacks either a default or an override. As you can add default values and specific overrides, it’s important to understand how they interact, and which credentials an environment uses.
  • If you only fill in the defaults for the connection, you can use that connection in any environment in the project. Every environment that uses the connection uses the default credentials.
  • If you don’t fill in the defaults for the connection, you can only use the connection in environments that you have specified overrides for. The environment uses the override credentials.
  • If you fill in the defaults for the connection and also fill in some environmental overrides, you can use that connection in any environment. Every environment that you have specified overrides for uses the override credentials. Every other environment uses the default credentials.
  • If you don’t fill in the defaults for the connection, and don’t associate the connection with any environment you have specified overrides for, the connection then becomes essentially dormant, not used or usable by any environment.
You can edit the connection at any time after creation to change the specified environment defaults. You may need to do this after creating a new environment that requires different defaults, for example.

​
Using a connection in a pipeline

Components that support connection objects have a property labeled Connection. This provides a drop-down list of connections for you to select from. Select the connection you require. No additional configuration of the connection is required in the component. If the required connection doesn’t yet exist, you can create it here. A special value, [Legacy connection], reveals additional properties in the component (for example, Username and Password) that you can use to configure the connection directly in the component instead of using a connection object. This is primarily in place to maintain compatibility with older versions of which didn’t use the connection object mechanism, but it’s also available for use in new pipelines if you prefer this method.
Any existing pipelines built with connections configured directly in the components continue to work seamlessly, using the [Legacy connection] options by default. There is no need for you to convert existing pipelines to use new connections objects.We do recommend that you use connection objects for new pipelines, and convert your legacy pipelines to use them if possible, to benefit from the improved connection management options they provide.You are not forced to convert, however, as the [Legacy connections] option is always available.