Skip to main content
Version: v2.x

Enable the S3 File Browser

tip

For full instructions showing how to protect S3 buckets with Cyral, see Track an S3 storage location.

The Cyral S3 File Browser lets data users read from and write to S3 buckets. Data users launch the S3 File Browser from the Cyral Access Portal.

Overview​

To make the S3 File Browser available, you must configure the following:

  1. Deploy your sidecar with a DNS CNAME and TLS certificate. These are required when using S3 Browser.
  2. Provide AWS permissions for the Cyral S3 Browser
  3. Track the S3 location as a repository in Cyral and bind the Cyral sidecar to it. Make sure you set the S3 browser port.
  4. Choose the Access Gateway for your S3 repository. See Enable the Cyral Access Portal for a repository.

Deploy sidecar for use with S3 Browser​

Prerequisites​

In order to support the Cyral S3 Browser, the sidecar must meet the following requirements. Ideally you will configure these when you deploy the sidecar, but you can also add them later.

  • A custom DNS CNAME that you provide. This is the address your data users will use to connect to data locations protected by the sidecar. Cyral recommends configuring this at sidecar deployment time, but you can also configure it later. See Add a CNAME or A record for the sidecar for setup steps.

  • A valid TLS certificate covering the sidecar's custom DNS CNAME. The certificate must be present in AWS Certificate Manager (CM). You can directly issue the certificate using AWS Certificate Manager, or you can manually import a valid certificate to the AWS CM. See the Cyral documentation about TLS with AWS Certificate Manager

note

The DNS CNAME and TLS certificate are only required for sidecars that will support the Cyral S3 browser. To give users Cyral-protected access without the Cyral S3 Browser, have them connect via another S3 client such as a CLI tool.

Examples of how to configure CNAME and TLS at deployment time​

The examples below assume the following:

See also the Cyral simplified documentation for Snowflake which can be used for S3 as well: Integration Guide: Protecting Snowflake with Cyral + G Suite

Terraform​

  • Download the Terraform sidecar template from the Cyral Management Console, after populating the required information

  • Open the downloaded terraform file (sidecar.tf) and add the following extra parameters after the sidecar_ports entry:

    # Certificate related changes
    load_balancer_tls_ports  = [443] # Port used to connect to the sidecar from the S3 browser
    load_balancer_certificate_arn = "arn:aws:acm:<REGION>:<AWS_ACCOUNT>:certificate/<CERTIFICATE_ID>"

    # Custom DNS name (CNAME) related changes
    sidecar_dns_hosted_zone_id = "<AWS_ROUTE_53_ZONE_ID>"
    sidecar_dns_name = "<CNAME>" # ex: "www.sidecar-custom-name.com"

    If sidecar_dns_hosted_zone_id is omitted, the sidecar_dns_name won’t be automatically created, and the sidecar alias will need to be created after the deployment. See Add a CNAME or A record for the sidecar

  • For sidecars with support for S3, it is also a good practice to also attach the list of IAM Policies giving the sidecar all the required permissions to assume IAM roles with access to S3

    # IAM Policies to be attached to the sidecar, which allow the sidecar to 
    # assume the desired IAM Roles with access to S3 buckets
    iam_policies = ["arn:aws:iam::<AWS_ACCOUNT>:policy/<POLICY_NAME>"]

All the terraform parameters used above are documented in GitHub: cyralinc/terraform-cyral-sidecar-aws: Cyral Sidecar AWS Module

CloudFormation​

  • Download the Terraform sidecar template from the Cyral Management Console, after populating the required information.

  • Go to the desired AWS Account, open the CloudFormation service and create a new stack by uploading the template downloaded from the Management Console.

  • Modify the following parameters:

    • SidecarDNSName: Add the sidecar custom CNAME
    • SidecarDNSHostedZoneId: Add the Route53 hosted zone ID
      • If SidecarDNSHostedZoneId is omitted, the SidecarDNSName won’t be automatically created, and the sidecar alias will need to be created after the deployment: Add a CNAME or A record for the sidecar | Cyral Docs
    • LoadBalancerCertificateArn: Add the ARN of the TLS certificate in AWS Certificate Manager
    • LoadBalancerTLSPorts: Add 443 to the list

  • For sidecars with support for S3, it is also a good practice to also attach the list of IAM Policies giving the sidecar all the required permissions to assume IAM roles used to communicate to S3

Helm3 (AWS/EKS)​

Download the Helm3 sidecar template from the Cyral Management Console, after populating the required information

Documentation: Install a sidecar with Helm 3 (Cyral Docs) , Values file configuration reference (Cyral Docs)

Open the downloaded terraform file (<sidecar-name>.yaml) and add these extra parameters under the service key:

service:
  dnsName: "<CNAME>" # ex: "www.sidecar-custom-name.com"
  loadBalancer:
    tlsPorts: [443]
    certificateId: "arn:aws:acm:<REGION>:<AWS_ACCOUNT>:certificate/<CERTIFICATE_ID>"

For the helm template, there is no equivalent to the terraform’s sidecar_dns_hosted_zone_id variable. It means the CNAME will need to be created after the deployment: Add a CNAME or A record for the sidecar (Cyral Docs)

Docker Compose​

Not documented as this relies on specific details of the customer environment. Docker Compose is very flexible regarding the deployment architecture

Example of how to configure CNAME and TLS after sidecar deployment​

CNAME​

Add a CNAME or A record for the sidecar (Cyral Docs)

TLS​

Terraform, Cloudformation and Helm create an AWS Network Load Balancer to manage the network traffic into the sidecar. We will need to manually modify the load balancer and attach a TLS Certificate to it.

  1. Go to AWS EC2 Load Balancers
  2. Select the Load Balancer attached to your sidecar and go to the Listeners tab:
  3. Select the desired listener (by desired port) and click on Edit
  4. Change the Protocol to TLS and select the appropriate SSL certificate from ACM (AWS Certificate Manager)
  5. Click on Save Changes and wait for them to be applied.

AWS permissions for the Cyral S3 Browser​

The Cyral S3 Browser, by default, tries to list all buckets associated with a given IAM role. In order for this operation to succeed, the IAM role should have an IAM policy allowing it to list buckets.

For example, let's look at the two IAM roles below:

<account-id>:role/S3RoleWithAccessToFinances
<account-id>:role/S3CustomRole

These should have the AWS List Bucket permission. This allows the user to list the buckets (this is the entry point for browsing) in the S3 Browser.

If the IAM role does not have the permission to List Buckets, users will receive an error message when opening the S3 Browser. In this case, users can still access a specific location by explicitly adding its bucket name in the S3 Browser URL.

For example, if the user wants to access the bucket: finance-data-company, then she can type the following URL to connect to it:

https://<management-console-endpoint>.cyral.com/app/s3Browser/finance-data-company

Permission to list all buckets​

The AWS permission to list all buckets are:

  • ListAllMyBuckets and
  • GetBucketLocation

For more information, see the AWS documentation on S3 bucket access.

Next steps​