Skip to content

You are viewing documentation for Immuta version 2024.1.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

Integration Configuration Payload Reference Guide

The parameters for configuring an integration in Immuta are outlined in the table below.

Parameter
Description
Required or optional Default values
Accepted values
type string The type of integration to configure. Required -
autoBootstrap boolean When true, Immuta will automatically configure the integration in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment for you. When false, you must set up your environment manually before configuring the integration with the API. This parameter must be set to false in the Amazon S3 and Google BigQuery configurations. See the specific how-to guide for configuring your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, Snowflake. Required for all integrations except Starburst (Trino) - true or false
config object This object specifies the integration settings. See the config object description for your integration for details: Amazon S3, Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake. Required for all integrations except Starburst (Trino) - -

Amazon S3 configuration object

The config object configures the S3 integration. The table below outlines its child parameters.

Parameter
Description
Required or optional Default values
Accepted values
name string A name for the integration that is unique across all Amazon S3 integrations configured in Immuta. Required - -
awsAccountId string The ID of your AWS account. Required - -
awsRegion string The AWS region to use. Required - Any valid AWS region (us-east-1, for example)
awsLocationRole string The AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee. When a grantee accesses S3 data, the AWS Access Grants service attaches session policies and assumes this role in order to vend scoped down credentials to the grantee. This role needs full access to all paths under the S3 location prefix. Required - -
awsLocationPath string The base S3 location prefix that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta. Required - -
awsRoleToAssume string The optional AWS IAM role ARN Immuta assumes when interacting with AWS. Optional [] -
authenticationType string The method used to authenticate with AWS when configuring the S3 integration. Required -
  • auto
  • accessKey
awsAccessKeyId string The AWS access key ID for the AWS account configuring the integration. Required when authenticationType is accessKey. - -
awsSecretAccessKey string The AWS secret access key for the AWS account configuring the integration. Required when authenticationType is accessKey. - -
port number The port to use when connecting to your S3 Access Grants instance. Optional 443 0-65535

S3 data sources

The table below outlines the parameters for creating an S3 data source.

Parameter
Description
Required or optional Default values
Accepted values
type string The type of integration. Required - Native S3
integrationId number The unique identifier of the S3 integration. Required - -
dataSources.dataSourceName string The name of the S3 data source you want to create. Required - -
dataSources.prefix string The S3 prefix that creates a data source for the prefix, bucket, or object provided in the path. Required - -

S3 data source response schema

The table below outlines the response schema for successful requests.

Property
Description
dataSourceId integer The unique identifier of the data source.
prefix string The S3 path of the prefix, bucket, or object used to create the data source.
dataSourceName string The name of the data source.

Azure Synapse Analytics configuration objects

The config object configures the Azure Synapse Analytics integration. The table below outlines its child parameters.

Parameter
Description
Required or optional Default values
Accepted values
host string The URL of your Azure Synapse Analytics account. Required - Valid URL hostnames.
database string Name of an existing database where the Immuta system user will store all Immuta-generated schemas and views. Required - -
schema string Name of the Immuta-managed schema where all your secure views will be created and stored. Required - -
username string The username of the system account that can act on Azure Synapse Analytics objects and configure the integration. Required - -
password string The password of the system account that can act on Azure Synapse Analytics objects and configure the integration. Required - -
metadataDelimiters object This object is a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for parameters. Optional See the object description for default values. -
port number The port to use when connecting to your Azure Synapse Analytics account host. Optional 1433 0-65535
impersonation object Enables user impersonation. See the impersonation object description for parameters. Optional Disabled by default. See the impersonation object description for parameters. -
connectArgs string The connection string arguments to pass to the ODBC driver when connecting as the Immuta system user. Optional - -

Azure Synapse Analytics impersonation object

The impersonation object enables and defines roles for user impersonation for Azure Synapse Analytics. The table below outlines its child parameters.

Parameter
Description
Default values
Accepted values
enabled boolean When true, enables user impersonation. false true or false
role string The name of the user impersonation role. IMMUTA_IMPERSONATION -

Delete Azure Synapse Analytics payload

The credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.

Parameter
Description
Required or optional
Accepted values
authenticationType string The type of authentication used when originally configuring the Azure Synapse Analytics integration. This parameter is only required when deleting the integration, not when configuring the integration. Required userPassword
username string The username of the system account that configured the integration. Required if autoBootstrap was true when setting up the integration. -
password string The password of the system account that configured the integration. Required if autoBootstrap was true when setting up the integration. -

Metadata delimiters object

The metadataDelimiters object specifies the delimiters that Immuta uses to store profile data in Azure Synapse Analytics. The table below outlines its child parameters.

Parameter
Description
Default values
Accepted values
hashDelimiter string A delimiter used to separate key-value pairs. | -
hashKeyDelimiter string A delimiter used to separate a key from its value. : -
arrayDelimiter string A delimiter used to separate array elements. , -

Databricks Unity Catalog configuration objects

The config object configures the Databricks Unity Catalog integration. The table below outlines its child parameters.

Parameter
Description
Required or optional Default values
Accepted values
port number The port to use when connecting to your Databricks account host. Optional 443 0-65535
workspaceUrl string Databricks workspace URL. For example, my-workspace.cloud.databricks.com. Required - -
httpPath string The HTTP path of your Databricks cluster or SQL warehouse. Required - -
token string The Databricks personal access token. This is the access token for the Immuta system account user. Required - -
audit object This object enables Databricks Unity Catalog query audit. See the audit object description for parameters. Optional Disabled by default. See the audit object description for parameters. -
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. Optional immuta -
groupPattern object This object allows you to exclude groups in Databricks from authorization checks. See the groupPattern object description for parameters. Optional - -

Databricks Unity Catalog audit object

The audit object enables Databricks Unity Catalog query audit. The table below outlines its child parameter.

Parameter
Description
Default values
Accepted values
enabled boolean This setting enables or disables Databricks Unity Catalog query audit. false true or false

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 parameters.

Parameter
Description
Default values
Accepted values
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 -

Google BigQuery configuration object

The config object configures the Google BigQuery integration. The table below outlines its child parameters.

Parameter
Description
Required or optional Default values
Accepted values
role string Google Cloud role used to connect to Google BigQuery. Required - -
datasetSuffix string Suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore. Required - -
dataset string Name of the BigQuery dataset to provision inside of the project for Immuta metadata storage. Optional immuta -
location string The dataset's location. After a dataset is created, the location can't be changed. Required - Any valid GCP location (us-east1, for example).
credential string The Google BigQuery service account JSON keyfile credential content. See the Google documentation for guidance on generating and downloading this keyfile. Required - -
port number The port to use when connecting to your BigQuery account host. Optional 443 0-65535

Redshift configuration objects

The config object configures the Redshift integration. The table below outlines its child parameters.

Parameter
Description
Required or optional Default values
Accepted values
host string The URL of your Redshift account. Required - Valid URL hostnames
database string Name of a new empty database that the Immuta system user will manage and store metadata in. Required - -
initialDatabase string Name of the existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database. Required if autoBootstrap is true. - -
authenticationType string The type of authentication to use when connecting to Redshift. Required -
  • userPassword
  • accessKey
  • okta
username string The username of the system account that can act on Redshift objects and configure the integration. Required if you selected userPassword as your authenticationType. - -
password string The password of the system account that can act on Redshift objects and configure the integration. Required if you selected userPassword as your authenticationType. - -
okta object This object represents your Okta configuration. See the Okta object description for parameters. Required if you selected okta as your authenticationType. - -
databaseUser string The Redshift database username. Required if you selected accessKey as your authenticationType. - -
accessKeyId string The Redshift access key ID. Required if you selected accessKey as your authenticationType. - -
secretKey string The Redshift secret key. Required if you selected accessKey as your authenticationType. - -
sessionToken string The Redshift session token. Optional if you selected accessKey as your authenticationType. - -
port number The port to use when connecting to your Redshift account host. Optional 5439 0-65535
impersonation object Enables user impersonation. See the impersonation object description for parameters. Optional Disabled by default. See the impersonation object description for parameters. -
connectArgs string The connection string arguments to pass to the ODBC driver when connecting as the Immuta system user. Optional - -

Delete Redshift integration payload

The authentication type and credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.

Parameter
Description
Required or optional
Accepted values
authenticationType string The type of authentication used when originally configuring the Redshift integration. Required if autoBootstrap was true when setting up the integration.
  • userPassword
  • accessKey
  • okta
username string The username of the system account that configured the integration. Required if you selected userPassword as your authenticationType. -
password string The password of the system account that configured the integration. Required if you selected userPassword as your authenticationType. -
databaseUser string The Redshift database username. Required if you selected accessKey as your authenticationType. -
accessKeyId string The Redshift access key ID. Required if you selected accessKey as your authenticationType. -
secretKey string The Redshift secret key. Required if you selected accessKey as your authenticationType. -
sessionToken string The Redshift session token. Optional if you selected accessKey as your authenticationType. -
okta object This object represents your Okta configuration. See the Okta object description for parameters. Required if you selected okta as your authenticationType. -

Redshift impersonation object

The impersonation object enables and defines roles for user impersonation for Redshift. The table below outlines its child parameters.

Parameter
Description
Default values
Accepted values
enabled boolean When true, enables user impersonation. false true or false
role string The name of the user impersonation role. immuta_impersonation -

Okta object

The okta object represents your Okta configuration. This object is required if you set okta as your authentication type in the Redshift integration configuration. The table below outlines its child parameters.

Parameter
Description
Required or optional Default values
Accepted values
username string The username of the system account that can act on Redshift objects and configure the integration. Required - -
password string The password of the system account that can act on Redshift objects and configure the integration. Required - -
appId string The Okta application ID. Required - -
idpHost string The Okta identity provider host URL. Required - -
role string The Okta role. Required - -

Snowflake configuration objects

The config object configures the Snowflake integration. The table below outlines its child parameters.

Parameter
Description
Required or optional Default values
Accepted values
host string The URL of your Snowflake account. Required - Valid URL hostnames
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 Name of a new empty database that the Immuta system user will manage and store metadata in. Required - -
authenticationType string The type of authentication to use when connecting to Snowflake. Required -
  • userPassword
  • keyPair
  • oAuth
username string The username of the system account that can act on Snowflake objects and configure the integration. Required if you selected userPassword as your authenticationType. - -
password string The password of the system account that can act on Snowflake objects and configure the integration. Required if you selected userPassword as your authenticationType. - -
privateKey string The private key. Replace new lines in the private key with a backslash before the new line character: \n. Required if you selected keyPair as your authenticationType. - -
oAuthClientConfig object This object represents your OAuth configuration. To use this authentication method, autoBootstrap must be false. See the oAuthClientConfig object description for parameters. Required if you selected oAuth as your authenticationType. - -
role string The privileged Snowflake role used by the Immuta system account when configuring the Snowflake integration. Required when autoBootstrap is true. - -
port number The port to use when connecting to your Snowflake account host. Optional 443 0-65535
audit object This object enables Snowflake query audit. See the audit object description for parameters. Optional Disabled by default. See the audit object description for parameters. -
impersonation object Enables user impersonation. See the impersonation object description for parameters. Optional Disabled by default. See the impersonation object description for parameters. -
userRolePattern object This object excludes roles and users from authorization checks. See the userRolePattern object description for parameters. Optional {[]} -
workspaces object This object represents an Immuta project workspace configured for Snowflake. See the workspaces object description for parameters. Optional Disabled by default. See the workspaces object description for parameters. -
connectArgs string The connection string arguments to pass to the ODBC driver when connecting as the Immuta system user. Optional - -
privilegedConnectArgs string The connection string arguments to pass to the ODBC driver when connecting as the privileged user. Optional when autoBootstrap is true. - -
lineage object Enables Snowflake lineage ingestion so that Immuta can apply tags added to Snowflake tables to their descendant data source columns. See the native lineage ingestion object description for parameters. Optional - -

Audit object

The audit object enables Snowflake query audit. The table below outlines its child parameters.

Parameter
Description
Default values
Accepted values
enabled boolean This setting enables or disables Snowflake query audit. false true or false
historicalIngestionMonths number The number of months of historical audit records to ingest. 3 1 - 12

Delete Snowflake integration payload

The authentication type and credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.

Parameter
Description
Required or optional
Accepted values
authenticationType string The type of authentication used when originally configuring the integration. Required if autoBootstrap was true when configuring the integration.
  • userPassword
  • keyPair
  • oAuth
username string The username of the system account that configured the integration. Required for the Azure Synapse Analytics integration or if you selected userPassword as your authenticationType for Redshift or Snowflake. -
password string The password of the system account that configured the integration. Required for the Azure Synapse Analytics integration or if you selected userPassword as your authenticationType for Redshift or Snowflake. -
privateKey string The private key used to configure the integration. Replace new lines in the private key with a backslash before the new line character: \n. Required if you selected keyPair as your authenticationType. -
oAuthClientConfig object This object represents your OAuth configuration. See the oAuthClientConfig object description for parameters. Required if you selected oAuth as your authenticationType. -
role string The privileged Snowflake role used by the Immuta system account when configuring the Snowflake integration. Required when autoBootstrap is true for Snowflake. -

Snowflake impersonation object

The impersonation object enables and defines roles for user impersonation for Snowflake. The table below outlines its child parameters.

Parameter
Description
Default values
Accepted values
enabled boolean When true, enables user impersonation. false true or false
role string The name of the user impersonation role. IMMUTA_IMPERSONATION -

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.

Parameter
Description
Required or optional Default values
Accepted values
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 false 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 1000 Minimum value of 1.

OAuth configuration object

The oAuthClientConfig object represents your OAuth configuration in Snowflake. This object is required if you set oAuth as your authentication type in the Snowflake integration configuration, and you must set autoBootstrap to false. The table below outlines the object's child parameters.

Parameter
Description
Required or optional Default values
Accepted values
provider string The identity provider for OAuth, such as Okta. Required - -
clientId string The client identifier of your registered application. Required - -
authorityUrl string Authority URL of your identity provider. Required - -
useCertificate boolean Specifies whether or not to use a certificate and private key for authenticating with OAuth. Optional true true or false
publicCertificateThumbprint string Your certificate thumbprint. Required if useCertificate is true. - -
oauthPrivateKey string The private key content. Required if useCertificate is true. - -
clientSecret string Client secret of the application. Required if useCertificate is false. - -
resource string An optional resource to pass to the token provider. Optional - -

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.

Parameter
Description
Default values
Accepted values
exclude array[string] This array is a list of roles and users to exclude from authorization checks. [] -

Workspaces object

The workspaces object represents an Immuta project workspace configured for Snowflake. The table below outlines its child parameters.

Parameter
Description
Default values
Accepted values
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. false true or false
warehouses array[string] This array is a list of warehouses workspace users have usage privileges on. [] -