1 of 1

Configure an Amazon S3 Integration

Private preview: This integration is available to select accounts. Contact your Immuta representative for details.

The Amazon S3 resource allows you to create, configure, and manage your S3 integration. In this integration, Immuta provides coarse-grained access controls for data in S3 by performing permission grants using the Access Grants API so that users don't have to manage individual IAM policies themselves.

Use the /integrations endpoint to

Requirements

S3 integration enabled in Immuta; contact your Immuta representative to enable this integration
; contact your Immuta representative to get this feature enabled
No location is registered in your AWS Access Grants instance before configuring the integration in Immuta

Permissions

APPLICATION_ADMIN Immuta permission to configure the integration
CREATE_S3_DATASOURCE Immuta permission to register S3 prefixes
There are two AWS roles that you will set up in AWS before configuring the integration in Immuta:

Set up S3 Access Grants instance and IAM roles

. AWS supports one Access Grants instance per region per AWS account.
Create a permissions policy with the following permissions. You will attach this permissions policy to your location IAM role once created.
If you use server-side encryption with AWS Key Management Service (AWS KMS) keys to encrypt your data, the following permissions are required for the IAM role in the policy. If you do not use this feature, do not include these permissions in your IAM policy:

Location IAM role

role and select AWS account as the trusted entity type.
Edit the trust policy to give the S3 Access Grants service principal access to this role in the resource policy file. The trust policy for this role should include at least the permissions provided in the example below, but might need additional permissions depending on other local setup factors.
Attach the permissions policy you created in the previous step to this IAM role to grant the permissions to the role. Once you begin configuring the integration in Immuta, you will add this role to your integration configuration so that Immuta can register this role with your Access Grants location.

Authentication IAM role (or user)

Create a permissions policy with the permissions in the sample policy below. Replace <location_role_arn> and <access_grants_instance_arn> in the example below with the ARNs of the location IAM role you created and your Access Grants instance, respectively. The Access Grants instance resource ARN should be scoped to apply to any future locations that will be created under this Access Grants instance. For example, "Resource": "arn:aws:s3:us-east-2:6********499:access-grants/default*" ensures that the role would have permissions for both of these locations:
1. arn:aws:s3:us-east-2:6********499:access-grants/default/newlocation1

Configure the integration in Immuta

This request configures the integration using the AWS access key authentication method.

Copy the request example. The example uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and with your own.
Change the

See the for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the S3 integration configuration connection. See the for details about the response schema.

A successful response includes the validation tests statuses.

An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.

Get an integration

Copy the request example.
Replace the Immuta URL and with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the .

Response

The response returns an S3 integration configuration. See the for details about the response schema. An unsuccessful response returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.

Get all integrations

Copy the request example.
Replace the Immuta URL and with your own.

Response

The response returns the configuration for all integrations. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.

Update an integration configuration

Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML.

See the for parameter definitions, value types, and additional configuration options.

Replace the Immuta URL and with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values from above to your own. The editable values listed below are the only parameters that can change from the integration's existing configuration. The required parameters listed below must match the integration's existing configuration.

Response

The response returns the status of the Amazon S3 integration configuration connection. See the for details about the response schema.

A successful response includes the validation tests statuses.

An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.

Delete an integration

Copy the request example.
Replace the Immuta URL and with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

The response returns the status of the S3 integration configuration that has been deleted. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.

Configure an Amazon S3 Integration

Private preview: This integration is available to select accounts. Contact your Immuta representative for details.

Use the /integrations endpoint to

Requirements

S3 integration enabled in Immuta; contact your Immuta representative to enable this integration
; contact your Immuta representative to get this feature enabled
No location is registered in your AWS Access Grants instance before configuring the integration in Immuta

Permissions

APPLICATION_ADMIN Immuta permission to configure the integration
CREATE_S3_DATASOURCE Immuta permission to register S3 prefixes
There are two AWS roles that you will set up in AWS before configuring the integration in Immuta:

Set up S3 Access Grants instance and IAM roles

. AWS supports one Access Grants instance per region per AWS account.
Create a permissions policy with the following permissions. You will attach this permissions policy to your location IAM role once created.
If you use server-side encryption with AWS Key Management Service (AWS KMS) keys to encrypt your data, the following permissions are required for the IAM role in the policy. If you do not use this feature, do not include these permissions in your IAM policy:

Location IAM role

role and select AWS account as the trusted entity type.
Edit the trust policy to give the S3 Access Grants service principal access to this role in the resource policy file. The trust policy for this role should include at least the permissions provided in the example below, but might need additional permissions depending on other local setup factors.
Attach the permissions policy you created in the previous step to this IAM role to grant the permissions to the role. Once you begin configuring the integration in Immuta, you will add this role to your integration configuration so that Immuta can register this role with your Access Grants location.

Authentication IAM role (or user)

Create a permissions policy with the permissions in the sample policy below. Replace <location_role_arn> and <access_grants_instance_arn> in the example below with the ARNs of the location IAM role you created and your Access Grants instance, respectively. The Access Grants instance resource ARN should be scoped to apply to any future locations that will be created under this Access Grants instance. For example, "Resource": "arn:aws:s3:us-east-2:6********499:access-grants/default*" ensures that the role would have permissions for both of these locations:
1. arn:aws:s3:us-east-2:6********499:access-grants/default/newlocation1

Configure the integration in Immuta

This request configures the integration using the AWS access key authentication method.

Copy the request example. The example uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and with your own.
Change the

See the for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the S3 integration configuration connection. See the for details about the response schema.

A successful response includes the validation tests statuses.

An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.

Get an integration

Copy the request example.
Replace the Immuta URL and with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the .

Response

Get all integrations

Copy the request example.
Replace the Immuta URL and with your own.

Response

Update an integration configuration

Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML.

See the for parameter definitions, value types, and additional configuration options.

Replace the Immuta URL and with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values from above to your own. The editable values listed below are the only parameters that can change from the integration's existing configuration. The required parameters listed below must match the integration's existing configuration.

Response

The response returns the status of the Amazon S3 integration configuration connection. See the for details about the response schema.

A successful response includes the validation tests statuses.

An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.

Delete an integration

Copy the request example.
Replace the Immuta URL and with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

Authentication IAM role (or user): Immuta uses this role to authenticate with AWS, set up the integration, and issue grants. This entity must

have ownership of the buckets Immuta will enforce policies on
have the permissions to perform the following actions to create locations and issue grants:
- accessgrantslocation resource:
  - s3:CreateAccessGrant
  - s3:DeleteAccessGrantsLocation
- accessgrantsinstance resource:
  - s3:CreateAccessGrantsInstance
  - s3:CreateAccessGrantsLocation
- accessgrant resource:
  - s3:DeleteAccessGrant
  - s3:GetAccessGrant
- bucket resource: s3:ListBucket
- role resource:
  - iam:GetRole
  - iam:PassRole
- all resources: s3:ListAccessGrantsInstances

This request configures the integration using the automatic authentication method, which searches and obtains credentials using the AWS SDK's default credential provider chain. This method requires a configured IAM role for a service account and is only supported if you're using a self-managed deployment of Immuta. Contact your Immuta representative to customize your deployment and set up an IAM role for a service account that can give Immuta the credentials to set up the integration. Your Immuta representative will

Provide the AWS account to add to your trust policy.
Update the Immuta AWS configuration to allow Immuta to assume the role of your service principal.

Then, complete the steps below.

curl -X 'POST' \
    'https://<your-immuta-url.com>/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-api-key>' \
    -d '{
    "type": "Native S3",
    "autoBootstrap": false,
    "config": {
      "name": "<name-of-your-integration>",
      "awsAccountId": "<your-aws-account-id>",
      "awsRegion": "<your-aws-region>",
      "awsLocationRole": "<arn:aws:iam::your-location-role-arn:role/access-grants-instance-role>",
      "awsLocationPath": "<your-s3-location-path>",
      "authenticationType": "auto"
    }
    }'

Copy the request example. The example uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and with your own.
Change the config values to your own, where

[
  {
    "id": "1",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
      {
        "name": "Initial Validation: Basic Connection Test",
        "status": "passed"
      },
      {
        "name": "Initial Validation: Default Warehouse Access Test",
        "status": "passed",
        "result": []
      },
      {
        "name": "Initial Validation: Validate access to Privileged Role",
        "status": "passed",
        "result": []
      },
      {
        "name": "Validate Automatic: Database Does Not Exist",
        "status": "passed"
      },
      {
        "name": "Validate Automatic: Impersonation Role Does Not Exist",
        "status": "skipped"
      },
      {
        "name": "Validate Automatic Bootstrap User Grants",
        "status": "passed"
      }
    ] },
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "port": 443,
      "audit": {
        "enabled": false
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "lineage": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "<REDACTED>",
      "password": "<REDACTED>",
      "role": "ACCOUNTADMIN"
    }
    },
  {
    "id": "123456789",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "There is no existing integration matching this configuration",
          "status": "passed"
        },
        {
          "name": "The provided integration name is unique across Immuta S3 integrations",
          "status": "passed"
        },
        {
          "name": "The provided access grants location role is a valid ARN format",
          "status": "passed"
        },
        {
          "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
          "status": "passed"
        },
        {
          "name": "The provided S3 path exists and Immuta can list prefixes",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants location does not yet exist for the provided path",
          "status": "passed"
        }
      ] },
      "type": "Native S3",
      "autoBootstrap": false,
      "config": {
        "port": 443,
        "name": "S3 integration",
        "awsAccountId": "123456789",
        "awsRegion": "us-east-1",
        "awsLocationRole": "arn:aws:iam::123456789:role/access-grants-instance-role",
        "awsLocationPath": "s3://",
        "authenticationType": "accessKey",
        "awsAccessKeyId": "123456789",
        "awsSecretAccessKey": "123456789"
      }
  }
]

[
  {
    "id": "1",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
      {
        "name": "Initial Validation: Basic Connection Test",
        "status": "passed"
      },
      {
        "name": "Initial Validation: Default Warehouse Access Test",
        "status": "passed",
        "result": []
      },
      {
        "name": "Initial Validation: Validate access to Privileged Role",
        "status": "passed",
        "result": []
      },
      {
        "name": "Validate Automatic: Database Does Not Exist",
        "status": "passed"
      },
      {
        "name": "Validate Automatic: Impersonation Role Does Not Exist",
        "status": "skipped"
      },
      {
        "name": "Validate Automatic Bootstrap User Grants",
        "status": "passed"
      }
    ] },
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "port": 443,
      "audit": {
        "enabled": false
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "lineage": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "<REDACTED>",
      "password": "<REDACTED>",
      "role": "ACCOUNTADMIN"
    }
    },
  {
    "id": "123456789",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "There is no existing integration matching this configuration",
          "status": "passed"
        },
        {
          "name": "The provided integration name is unique across Immuta S3 integrations",
          "status": "passed"
        },
        {
          "name": "The provided access grants location role is a valid ARN format",
          "status": "passed"
        },
        {
          "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
          "status": "passed"
        },
        {
          "name": "The provided S3 path exists and Immuta can list prefixes",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants location does not yet exist for the provided path",
          "status": "passed"
        }
      ] },
      "type": "Native S3",
      "autoBootstrap": false,
      "config": {
        "port": 443,
        "name": "S3 integration",
        "awsAccountId": "123456789",
        "awsRegion": "us-east-1",
        "awsLocationRole": "arn:aws:iam::123456789:role/access-grants-instance-role",
        "awsLocationPath": "s3://",
        "authenticationType": "accessKey",
        "awsAccessKeyId": "123456789",
        "awsSecretAccessKey": "123456789"
      }
  }
]

Configure an Amazon S3 Integration

hashtagRequirements

hashtagPermissions

hashtagSet up S3 Access Grants instance and IAM roles

hashtagLocation IAM role

hashtagAuthentication IAM role (or user)

hashtagConfigure the integration in Immuta

hashtagResponse

hashtagGet an integration

hashtagResponse

hashtagGet all integrations

hashtagResponse

hashtagUpdate an integration configuration

hashtagResponse

hashtagDelete an integration

hashtagResponse

Configure an Amazon S3 Integration

hashtagRequirements

hashtagPermissions

hashtagSet up S3 Access Grants instance and IAM roles

hashtagLocation IAM role

hashtagAuthentication IAM role (or user)

hashtagConfigure the integration in Immuta

hashtagResponse

hashtagGet an integration

hashtagResponse

hashtagGet all integrations

hashtagResponse

hashtagUpdate an integration configuration

hashtagResponse

hashtagDelete an integration

hashtagResponse

Requirements

Permissions

Set up S3 Access Grants instance and IAM roles

Location IAM role

Authentication IAM role (or user)

Configure the integration in Immuta

Response

Get an integration

Response

Get all integrations

Response

Update an integration configuration

Response

Delete an integration

Response

Requirements

Permissions

Set up S3 Access Grants instance and IAM roles

Location IAM role

Authentication IAM role (or user)

Configure the integration in Immuta

Response

Get an integration

Response

Get all integrations

Response

Update an integration configuration

Response

Delete an integration

Response