> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Connections
export const m_runner = "Maia runner";
export const maia = "Maia";
The **Connections** tab in your [Project](/docs/guides/projects) 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 {maia}, 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](/docs/guides/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](#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](#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](#authenticate-an-oauth-connection), below.
You need to provide **Default values** and/or environment-specific values. Read [Understanding environment defaults](#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](#generic-secrets), below.
The following providers are currently supported:
* [Facebook Ads](/docs/components/facebook-ads)
* [Facebook Load](/docs/components/facebook-load)
* [HubSpot Load](/docs/components/hubspot-load)
* Instagram
* [Microsoft Dynamics CRM Load](/docs/components/microsoft-dynamics-crm-load)
* [NetSuite SuiteAnalytics Load](/docs/components/netsuite-suiteanalytics-load)
* [Oracle Fusion Cloud Financials Load](/docs/components/oracle-fcf-load)
* [Oracle Fusion Cloud Procurement Load](/docs/components/oracle-fcp-load)
* [Oracle Fusion Cloud Project Management Load](/docs/components/oracle-fcpm-load)
* [Salesforce Load](/docs/components/salesforce-load)
* [SAP NetWeaver Load](/docs/components/sap-netweaver-load)
* [Shopify Load](/docs/components/shopify-load)
* [SugarCRM Load](/docs/components/sugarcrm-load)
* [X Ads Load](/docs/components/x-ads-load)
This is not an exhaustive list of {maia} 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:
* [HubSpot](/docs/guides/hubspot-authentication-guide)
* [Jira](/docs/guides/jira-authentication-guide)
* [Kafka](/docs/guides/kafka-authentication-guide)
* [Kafka Confluent Cloud](/docs/guides/kafka-authentication-guide)
* [Marketo](/docs/guides/marketo-authentication-guide)
* [Microsoft Fabric Lakehouse](/docs/guides/microsoft-fabric-lakehouse-authentication-guide)
* [NetSuite](/docs/guides/netsuite-query-authentication-guide)
* [NetSuite SuiteAnalytics](/docs/guides/netsuite-suiteanalytics-authentication-guide)
* [Oracle Autonomous Database](/docs/guides/oracle-autonomous-database-authentication-guide)
* [Salesforce](/docs/guides/salesforce-authentication-guide)
* [ServiceNow](/docs/guides/servicenow-authentication-guide)
* [Workday](/docs/guides/workday-authentication-guide)
This list does not include all the OAuth providers that are available in {maia}—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](/docs/components/bing-ads-load) and [Bing Ads Query](/docs/components/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:
* [Get a developer token](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13#get-developer-token)
* [Get your account and customer IDs](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13#get-ids)
### 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](https://admin.google.com/) 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](https://support.google.com/a/answer/7281227?hl=en#trustorlimit\&zippy=%2Cconfigure-a-new-app) section of the Google documentation.
* {maia}'s client ID is `192174083921-gcguirlj6ltqcreni233koj6r1r3ner1.apps.googleusercontent.com`.
* You need to grant {maia} **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](https://learn.microsoft.com/en-us/dynamics365/customerengagement/on-premises/admin/security-roles-privileges) 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](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/walkthrough-register-app-azure-active-directory) 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](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant) 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](/docs/guides/runner-overview#matillion-full-saas-vs-hybrid-saas) operating model.
In a Hybrid SaaS implementation using [Matillion {m_runner} for Snowflake](/docs/guides/snowflake-runner-install), secrets are stored natively within a Snowflake schema instead. Read [Secrets in Matillion {m_runner} for Snowflake](/docs/guides/snowflake-runner-secrets) for details.
For a full discussion of secrets, read [Secrets overview](/docs/administration/secrets-overview).
To create a generic secret, follow the process in [Add a connection](#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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-secretsmanager-secret.html):
> *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:
| Property | Description |
| -------- | ---------------------------------------------------------------------- |
| Value | Enter the value of the secret, for example the password, SSH key, etc. |
### 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 {m_runner}](/docs/guides/create-a-runner), you should have identified which secrets managers or key vaults it has access to.
If you're using an [Azure {m_runner}](/docs/guides/create-a-runner), you can store secrets in any Azure key vault that your {m_runner} has access to. When you add a new secret definition, you can choose which of your key vaults the secret is stored in.
The {maia} 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](/docs/guides/secrets-and-secret-definitions).
Configure your secret definition by completing the following properties:
| Property | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runner | Select the [{m_runner}](/docs/guides/create-a-runner) that's used to manage the secret. The type of runner selected (AWS, Azure, or GCP) determines your other configuration options. |
| GCP Project ID | For **Google Cloud** {m_runner}s only. Your Google Cloud project ID. The special value `[Environment Default]` uses the Google Cloud project defined in the environment. For more information, read the [Google Cloud documentation](https://cloud.google.com/resource-manager/docs/creating-managing-projects). |
| Vault name | For **Azure** {m_runner}s only. Select the [Azure key vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) that this project uses to store secrets. Select \[Default] to use the default key vault specified in the {m_runner} environment variables. |
| Secret name | Select a named entry created in your secret manager. In addition to any character restrictions imposed by your cloud provider, you cannot use `@`, `~`, or whitespace characters in your secret names. |
| Secret key | For **AWS** {m_runner}s only. Select a named secret key tied to your secret name. |
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-secretsmanager-secret.html):
> *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 {maia} 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.