IronCore Labs Home
  1. Docs
  2. SaaS Shield
  3. Suite
  4. Amazon S3
  5. Advanced Installs
  1. Docs
  2. SaaS Shield
  3. Suite
  4. Amazon S3
  5. Advanced Installs

Advanced Installation of SaaS Shield CMK for Amazon S3

The Getting Started instructions will guide you through installing an initial instance of the product in AWS. These instructions are meant to help you proceed with setting up an environment that is more appropriate for your production application.

We also include instructions for setting up the S3 proxy if you are already running SaaS Shield in your infrastructure; you can just skip to the last section below, Adding an S3 Proxy to an Existing Installation.

Per-Region Installation

Like S3 buckets, CloudFormation stacks are created in a single region. If you have buckets owned by a single account in multiple regions, you should use that account and install SaaS Shield CMK for Amazon S3 in each region; the S3 proxy does not allow cross region access of buckets, with the exception of copying an object from a bucket in one region to a bucket in another.

You need to choose a unique domain name for the new instance, so that requests are routed to the appropriate instance of the product. You can create the stacks in each region using the same templates. Stack names are not required to be unique across regions, so you can use the same stack name in each region, if you prefer. We do recommend that instead of using the same TSP Configuration file for each region, you log into the Configuration Broker and create a new Tenant Security Proxy (TSP) for the installation in each region. When you download the deployment files, the TSP Config file contains new values, including new secret keys for encryption and signing. There is not a problem using the same TSP configuration for stacks in multiple regions, but generating a new configuration gives you additional revocation and audit flexibility. The deployment template is identical for each new TSP, so you can create a stack using that template as often as desired.

Multiple Installations in One Region

You can install SaaS Shield CMK for Amazon S3 multiple times in a single region using the same AWS account. A possible use case might be configuring a dev test environment and a separate QA environment. Simply use the correct account in the Configuration Broker to create a TSP and download the deployment files, then use those files to create separate stacks in CloudFormation. As with the other installations, you need to choose a separate DNS domain for for each installation and update your DNS server appropriately, but you can run the instances in the same AWS region with no issues.

Customizing the Installation

We generated the CloudFormation deployment template with the goal of making it easy to create an instance of SaaS Shield CMK for Amazon S3 for testing. To simplify the installation, we minimized the number of available choices and configuration options. After you have worked with the test system and are ready to move toward a production installation, you will probably want to make different choices in your configuration. Some likely adjustments include replacing the test bucket and the test user to access that bucket with the actual buckets and users you will want for production.

Although you could configure an entire installation manually in AWS, we recommend that you use CloudFormation to manage each installation; CloudFormation provides an easy way to upgrade the containers running the S3 proxy and the TSP, gets the networking configured correctly, sets up a CloudWatch log group, and simplifies other essential tasks. To modify the installation, edit the deployment template before using it to create the CloudFormation stack. For instance, you can remove the stanzas labeled S3TargetBucket and S3User if you want to use buckets and users that you already have configured in AWS.

Note, however, that the S3AccessKey in the deployment references the user, so if you remove the S3User, you need to update the UserName in the S3AccessKey properties with the name of the user you want to use for S3 access. Likewise, when the task is created to run the S3 proxy, it sets the S3_CONFIG_BUCKET environment variable to the name of the S3TargetBucket, so you will need to edit that value and specify the name of the bucket where the S3 proxy will create or load its tenant mapping configuration.

If you do modify the CloudFormation template, we recommend keeping the template that we provided as well, ideally in a version control system that can track the changes. As we release updates to the product that change the templates, you will need to identify and merge the changes into your customized templates.

Remember to update the tenant mapping file to match the tenants you will be using with the installation.

Removing Installations

If you have installed a stack and want to remove it, you should follow these steps.

  1. Remove the contents of the test bucket associated with the deployment stack. The bucket contains at least the tenant mapping file, and because it is not empty, CloudFormation cannot remove the bucket. Go to the stack in the CloudFormation console, open the Resources tab, and find the entry with logical ID S3TargetBucket.
  2. Click the link to open the S3 console for the bucket, and delete its contents. You can leave the bucket; CloudFormation can now remove it, since it is empty.
  3. Close the tab for the S3 console, and return to the CloudFormation tab. Find the resource with logical ID S3DNSZone.
  4. Click the link to open the Route 53 console for the DNS zone. Delete the record with type CNAME. Now CloudFormation will be able to remove the DNS Zone.
  5. Close the tab for the Route 53 console, and return to the CloudFormation tab. Click the Delete button at the top to remove the CloudFormation stack and all the resources that it manages.

Adding an S3 Proxy to an Existing Installation

If you have already set up a Tenant Security Proxy in your infrastructure to use SaaS Shield features, you can easily add the S3 Proxy to your installation. The proxy is distributed as a Docker container, like the Tenant Security Proxy. The image can be obtained from the Google Container Registry. You can find the latest tag available for the proxy and pull down the Docker image by running this command:

bash

docker pull gcr.io/ironcore-images/saas-shield-s3-proxy:{tag}

You can see the changes in each version of the S3 Proxy in its changelog.

The S3 Proxy requires the following configuration information to be provided. It gets the value for each setting from an environment variable. The first five can be managed in your infrastructure using static environment variables (AWS) or a config map (GCP).

  • TSP_URL: the URL that the S3 Proxy should use to communicate with the TSP. This can be the address of the TSP instance or of the load balancer in front of a pool of TSPs
  • S3_CONFIG_BUCKET: the name of the S3 bucket that holds the tenant mapping configuration file
  • S3_CONFIG_REGION: the region where the S3 bucket is located
  • S3_CONFIG_KEY: the name (S3 key) of the tenant mapping configuration file (i.e. tenant-mapping.conf)
  • PROXY_DNS_NAME: the hostname of the VM running the S3 proxy. This is the address the clients will use to send requests to the proxy
  • CORS_ALLOWED_ORIGIN: a hostname that is allowed to make cross origin requests to the s3 proxy. This must include both the protocol and the port number if applicable. It can also be specified as * to allow all origins. If omitted, no cross origin requests will be allowed.

The next two settings are also provided to the container as environment variables, but they should be managed as secrets in your infrastructure, since they contain sensitive information: TSP_API_KEY: the API key from your TSP configuration that is used to authenticate requests S3_CREDENTIALS: a list of the S3 access keys and corresponding secret keys that could be used by clients submitting requests to S3

There must be at least one pair of S3 credentials provided, but there can be more than one. The credentials should be provided as a JSON object, such as

{
  "AKIAU0XXXXXXXXXXXXXX":{secret-key:"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
}

or

{
  "AKIAU1XXXXXXXXXXXXXX":{secret-key:"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
  "AKIAU2XXXXXXXXXXXXXX":{secret-key:"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
  "AKIAU3XXXXXXXXXXXXXX":{secret-key:"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
}

You can optionally provide an EXPLICIT_TENANT_ID in the environment; if you set this, the S3 Proxy will use that value and ignore any tenant IDs specified in the incoming requests. If you do not set the explicit tenant ID, you can set REJECT_UNKNOWN_TENANT_ID in the environment to true if you want any requests that contain a tenant ID that is not recognized to be rejected.

If you do not use an EXPLICT_TENANT_ID, you will want to set up the mapping that allows the S3 proxy to determine the appropriate tenant for each request. There is more information about tenant IDs and mapping them to buckets in the Creating and Mapping Tenants section. Your mapping will be in the S3 object specified by the S3_CONFIG_REGION, S3_CONFIG_BUCKET, and S3_CONFIG_KEY that you provided.

If you need further assistance or have questions, please email saas.shield.support@ironcorelabs.com.