Private preview: The Amazon S3 integration is available to select accounts. Reach out to 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
S3 integration enabled in Immuta; contact your Immuta representative to enable this integration
No location is registered in your AWS Access Grants instance before configuring the integration in Immuta
APPLICATION_ADMIN Immuta permission to configure the integration
CREATE_S3_DATASOURCE Immuta permission to register S3 data sources
The AWS account credentials or optional AWS IAM role you provide Immuta when configuring the integration must
have ownership of the buckets Immuta will enforce policies on
have the following permissions to create locations and issue grants:
s3:CreateAccessGrant
s3:CreateAccessGrantsLocation
s3:DeleteAccessGrant
s3:DeleteAccessGrantsLocation
s3:GetAccessGrant
s3:GetAccessGrantsInstance
s3:GetAccessGrantsInstanceForPrefix
s3:GetAccessGrantsInstanceResourcePolicy
s3:GetAccessGrantsLocation
s3:ListAccessGrants
s3:ListAccessGrantsInstances
s3:ListAccessGrantsLocations
iam:PassRole
iam:GetRole
Follow AWS documentation to create an Access Grants instance using the S3 console, AWS CLI, AWS SDKs, or the REST API. AWS supports one Access Grants instance per region per AWS account.
Follow the instructions at the top of the "Register a location" page in AWS documentation to create an AWS IAM role and give the S3 Access Grants service principal access to this role in the resource policy file. You will add this role to your integration configuration in Immuta so that Immuta can register this role with your Access Grants location. The AWS documentation linked above gives a complete policy example, but your policy should include the following permissions:
sts:AssumeRole
sts:SetSourceIdentity
sts:SetContext
Follow the instructions at the top of the "Register a location" page in AWS documentation to create an IAM policy with the following permissions, and attach the policy to the IAM role you created to grant the permissions to the role. The AWS documentation linked above gives a complete example, but the policy should at least include the following permissions:
s3:GetObject
s3:GetObjectVersion
s3:GetObjectAcl
s3:GetObjectVersionAcl
s3:ListMultipartUploadParts
s3:PutObject
s3:PutObjectAcl
s3:PutObjectVersionAcl
s3:DeleteObject
s3:DeleteObjectVersion
s3:AbortMultipartUpload
s3:ListBucket
s3:ListAllMyBuckets
iam:passRole
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:
kms:Decrypt
kms:GenerateDataKey
Opt to create an AWS IAM role that Immuta can use to create Access Grants locations and issue grants. This role must have the S3 permissions listed in the permissions section.
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 API key with your own.
Change the config values to your own, where
name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.
awsAccountId is the ID of your AWS account.
awsRegion is the account's AWS region (such as us-east1).
awsLocationRole is 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.
awsLocationPath is 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.
awsAccessKeyId is the AWS access key ID of the AWS account configuring the integration.
awsSecretAccessKey is the AWS secret access key of the AWS account configuring the integration.
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. Work with 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.
Copy the request example. The example uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and API key with your own.
Change the config values to your own, where
name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.
awsAccountId is the ID of your AWS account.
awsRegion is the account's AWS region (such as us-east1).
awsLocationRole is 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.
awsLocationPath is the base S3 location that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.
See the config object description for parameter definitions, value types, and additional configuration options.
The response returns the status of the S3 integration configuration connection. See the response schema reference 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 HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key 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 GET /integrations endpoint.
The response returns an S3 integration configuration. See the response schema reference for details about the response schema. An unsuccessful response returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
The response returns the configuration for all integrations. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
The response returns the status of the S3 integration configuration that has been deleted. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example. The example uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and API key with your own.
Change the integrationsID to the ID of your S3 integration. This ID can be retrieved with the GET /integrations request.
Change the dataSources values to your own, where
dataSourceName is the name of your data source.
prefix creates a data source for the prefix, bucket, or object provided in the path. If the data source prefix ends in a wildcard (), it protects all items starting with that prefix. If the data source prefix ends without a wildcard (), it protects a single object.
See the S3 data source payload description for parameter definitions and value types.
The response returns the ID, name, and prefix of the data source. See the response schema reference for details about the response schema. An unsuccessful response returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.