Connection Registration Payloads Reference Guide
The parameters for configuring an integration in Immuta are outlined in the table below.
connectionKey string
A unique name for the connection.
Required
-
connection object
Required
-
Connection object
The connection object configures the connection between the technology and Immuta. The sections below outline the child parameters specific to each technology.
Snowflake connection object
technology string
The technology backing the new connection.
Required
SnowflakeDatabricks
hostname string
The URL of your Snowflake account. This is the same as host.
Required
-
port integer
The port to use when registering your Snowflake account. Defaults to 443.
Required
0-65535
warehouse string
The default pool of compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
Required
-
role string
The privileged Snowflake role used by the Immuta system account when configuring the Snowflake connection. It must be able to see the data that Immuta will govern.
Required
-
authenticationType string
The authentication type to register the connection. Make sure this auth type is the same used when requesting the script.
Required
keyPairoAuthClientCredentialsuserPassword
username string
The username of the system account that can act on Snowflake objects and register the connection.
Required when authenticationType is keyPair or userPassword.
-
password string
The password of the system account that can act on Snowflake objects and register the connection.
Required when authenticationType is userPassword.
-
privateKeyPassword string
The Snowflake private key password.
Required when authenticationType is keyPair and the private key is encrypted.
-
oAuthClientConfig object
Required when authenticationType is oAuthClientCredentials.
-
Databricks Unity Catalog connection object
The connection object configures the Databricks Unity Catalog connection information. The table below outlines its child parameters.
technology string
The technology backing the new connection.
Required
DatabricksSnowflake
hostname string
Your Databricks workspace URL. This is the same as host and workspaceURL.
Required
-
port integer
The port to use when registering your Databricks account connection. Defaults to 443.
Required
0-65535
httpPath string
The HTTP path of your Databricks cluster or SQL warehouse.
Required
-
authenticationType string
The authentication type to register the connection. Make sure this auth type is the same used when requesting the script.
Required
token
token string
The Databricks personal access token for the service principal created for Immuta.
Required
-
Settings object
The settings object configures connection settings. The table below outlines its child parameters.
isActive boolean
If true, data objects will be active by default when created in Immuta.
Optional
truefalse
activateNewChildren boolean
If true, all new children found during object sync will be registered as active.
Optional
truefalse
infrastructureAdmins array
A list of the users and groups that are infrastructure admins on the connection. These users can crawl the connection, edit the connection, and delete data objects.
Optional
-
dataOwners array
A list of users and groups that are data owners on the connection. These users will be data owners for all the data sources under the data object they are assigned to.
Optional
-
Options object
The options object configures an option for your connection. The table below outlines its child parameter.
forceRecursiveCrawl boolean
When true, both active and inactive objects will be found by object sync.
Optional
truefalse
Native integration object
The nativeIntegration object configures integration information and options. The table below outlines its child parameters.
type string
The type of technology.
Required
SnowflakeDatabricks
autoBootstrap boolean
When false, you must set up your environment manually before registering the connection with the API.
Required
false
config object
This object specifies the integration settings. See the config object description for your technology: Snowflake or Databricks Unity Catalog.
Required
-
unityCatalog boolean
When true, the integration is for Databricks Unity Catalog.
Required if type is Databricks.
true
Snowflake config object
The config object configures the Snowflake integration information and options. The table below outlines its child parameters.
authenticationType string
The authentication type to register the connection. Make sure this auth type is the same as the config object.
Required
keyPairoAuthClientCredentialsuserPassword
username string
The username of the system account that can act on Snowflake objects and register the connection.
Required when authenticationType is keyPair or userPassword.
-
password string
The password of the system account that can act on Snowflake objects and register the connection.
Required when authenticationType is userPassword.
-
privateKeyPassword string
The Snowflake private key password.
Required when authenticationType is keyPair and the private key is encrypted**.**
-
keyName string
The Immuta-given name of your private key.
Required when authenticationType is keyPair.
PRIV_KEY_FILE
userFilename string
The name of the private key file on your machine.
Required when authenticationType is keyPair.
-
content string
The private key. Replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
In the integrations API, this is the config.privateKey attribute.
Required when authenticationType is keyPair.
-
oAuthClientConfig object
Required when authenticationType is oAuthClientCredentials.
-
host string
The URL of your Snowflake account.
Required
-
port integer
The port to use when registering your Snowflake account.
Optional. Defaults to 443.
0-65535
warehouse string
The default pool of compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
Required
-
database string
The name of the Snowflake database Immuta will create to store internal entitlements and other user data specific to Immuta. This database will only be readable for the Immuta user and should not be granted to other users. The database name may only contain letters, numbers, and underscores and cannot start with a number.
Required
-
workspaces object
This object represents an Immuta project workspace configured for Snowflake. See the workspaces object.
Optional
-
lineage object
Enables Snowflake lineage ingestion so that Immuta can apply tags added to Snowflake tables to their descendant data source columns. See the lineage object.
Optional
-
userRolePattern object
This object excludes roles and users from authorization checks. See the user role pattern object.
Optional
-
Databricks Unity Catalog config object
The config object configures the Databricks Unity Catalog integration information and options. The table below outlines its child parameters.
authenticationType string
The authentication type to register the connection. Make sure this auth type is the same used when requesting the script.
Required
token
token string
The Databricks personal access token for the service principal created for Immuta.
Required
-
host string
Your Databricks workspace URL. This is the same as hostname and workspaceURL.
Required
-
port integer
The port to use when registering your Databricks account connection. Defaults to 443.
Optional. Defaults to 443.
0-65535
httpPath string
The HTTP path of your Databricks cluster or SQL warehouse.
Required
-
catalog string
The name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.
Required
-
audit object
This object enables Databricks Unity Catalog query audit. See the audit object.
Optional
-
workspaceIds array
The optional workspaces to filter audit to.
Optional
-
enableNativeQueryParsing boolean
If true, native query parsing is enabled.
Optional
false
groupPattern object
Excludes the listed group from having data policies applied in the Databricks Unity Catalog integration. See the Databricks Unity Catalog group pattern object.
Optional
-
jobConfig object
This object controls query parsing configuration. See the Databricks Unity Catalog job config object.
Optional
-
Snowflake specific objects
Snowflake private key object
The privateKey object represents your private key in Snowflake. This object is required if you set privateKey as your authentication type. The table below outlines the object's child parameters
keyName string
The Immuta-given name of your private key.
PRIV_KEY_FILE
userFilename string
The name of the private key file on your machine.
-
content string
The private key. Replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
In the integrations API, this is the config.privateKey attribute.
-
Snowflake OAuth object
The oAuthClientConfig object represents your OAuth configuration in Snowflake. This object is required if you set oAuthClientCredentials as your authentication type. The table below outlines the object's child parameters
useCertificate boolean
Specifies whether or not to use a certificate and private key for authenticating with OAuth.
Required
truefalse
clientId string
The client identifier of your registered application.
Required
-
authorityUrl string
Authority URL of your identity provider.
Required
-
scope string
The scope limits the operations and roles allowed in Snowflake by the access token.
Required
session:role-any
resource string
An optional resource to pass to the token provider.
Optional
-
publicCertificateThumbprint string
Your certificate thumbprint.
Required if useCertificate is true.
-
oauthPrivateKey object
Required if useCertificate is true.
-
clientSecret string
Client secret of the application.
Required if useCertificate is false.
-
Snowflake OAuth private key
The oauthPrivateKey object represents your OAuth private key in Snowflake. This object is required if you set oAuthClientCredentials as your authentication type, and useCertificate is set to true. The table below outlines the object's child parameters.
keyName string
The Immuta-given name of your private key.
oauth client certificate
userFilename string
The name of your private key file on your machine.
-
content string
The private key. Replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
In the integrations API, this is the config.oauthPrivateKey attribute.
-
Snowflake impersonation object
The impersonation object enables and defines roles for user impersonation for Snowflake. The table below outlines its child parameters.
enabled boolean
When true, enables user impersonation.
true or false
role string
The name of the user impersonation role.
-
Snowflake workspace object
The workspaces object represents an Immuta project workspace configured for Snowflake. The table below outlines its child parameters.
enabled boolean
This setting enables or disables Snowflake project workspaces. If you use Snowflake secure data sharing with Immuta, set this property to true, as project workspaces are required. If you use Snowflake table grants, set this property to false; project workspaces cannot be used when Snowflake table grants are enabled.
true or false
warehouses array[string]
This array is a list of warehouses workspace users have usage privileges on.
-
Snowflake lineage object
The lineage object enables Snowflake native lineage ingestion. When this setting is enabled, Immuta automatically applies tags added to a Snowflake table to its descendant data source columns in Immuta so you can build policies using those tags to restrict access to sensitive data. The table below outlines its child parameters.
enabled boolean
When true, enables Snowflake native lineage so that Immuta can apply tags added to Snowflake data sources to their descendant data source columns in Immuta.
Optional
true or false
lineageConfig object
Configures what tables Immuta will ingest lineage history for, the number of rows to ingest per batch, and what tags to propagate. Child parameters include tableFilter, tagFilterRegex, and ingestBatchSize.
Required if enabled is true.
-
lineageConfig.tableFilter string
This child parameter of lineageConfig determines which tables Immuta will ingest lineage for. Use a regular expression that excludes / from the beginning and end to filter tables. Without this filter, Immuta will attempt to ingest lineage for every table on your Snowflake instance.
Optional
Regular expression that excludes / from the beginning and end.
lineageConfig.tagFilterRegex string
This child parameter of lineageConfig determines which tags to propagate using lineage. Use a regular expression that excludes / from the beginning and end to filter tags. Without this filter, Immuta will ingest lineage for every tag on your Snowflake instance.
Optional
Regular expression that excludes / from the beginning and end.
lineageConfig.ingestBatchSize number
This child parameter of lineageConfig configures the number of rows Immuta ingests per batch when streaming Access History data from your Snowflake instance.
Optional
Minimum value of 1.
Snowflake user role pattern object
The userRolePattern object excludes roles and users from authorization checks in the Snowflake integration. The table below outlines its child parameter.
exclude array[string]
This array is a list of roles and users to exclude from authorization checks.
-
Databricks Unity Catalog specific objects
Databricks group pattern object
The groupPattern object excludes the listed group from having data policies applied in the Databricks Unity Catalog integration. This account-level group should be used for privileged users and service accounts that require an unmasked view of data. The table below outlines its child parameter.
deny string
The name of a group in Databricks that will be excluded from having data policies applied. This account-level group should be used for privileged users and service accounts that require an unmasked view of data.
immuta_exemption_group
-
Databricks Unity Catalog job config object
The jobConfig object controls configuration settings for Databricks Unity Catalog query parsing. The table below outlines its child parameters.
workspaceDirectoryPath string
The file path of the workspace directory.
/Workspace/ImmutaArtifacts
jobClusterId string
The ID of the job cluster.
undefined
Audit object
The audit object enables query audit. The table below outlines its child parameter.
enabled boolean
If true, query audit is enabled. Set to true for the recommended configuration.
truefalse
Last updated