IronCore Labs Home
  1. Docs

Getting Started with SaaS Shield CMK for Amazon S3

This guide will show you how to test for compatibility between your application and the SaaS Shield for Amazon S3 product, and how to get the product installed in your AWS environment for testing.

Checking Client Compatibility

We spent a lot of time ensuring that the S3 proxy’s interface was compatible with the Amazon S3 interface. But this is software, and you know what that is like. Your first step in assessing whether SaaS Shield for Amazon S3 will work with your application is to make sure that our interface is compatible with your code.

We have set up a global instance of the product to allow you to do some quick tests for compatibility. We are running SaaS Shield CMK for Amazon S3 in our AWS infrastructure, using a set of users and corresponding buckets that we assign to people to do testing. Just contact us to request access, and we will send you the credentials (access key and secret key) and bucket name you can use to test your S3 interface code. Or simply go to https://get.ironcorelabs.com/saas-shield-cmk-amazon-s3-try-free/ and try out the credentials we’ve made publicly available.

The URL of the global instance is https://saas-shield-for-s3-demo.ironcorelabs.com, and the buckets are all in the AWS region us-east-1. We are using both types of mapping to determine the tenant from the object name and path; inside any of the buckets, if an object has /TENANT1/ or /TENANT2/ in its path, we use that tenant. Otherwise, if the name starts with 1, it will be mapped to TENANT1, and if the name starts with 2, it will be mapped to TENANT2. Otherwise, it will not be encrypted. Alternatively, the tenant ID can be overwritten by sending the x-icl-tenant-id header with the upload request. The only available tenant IDs are TENANT1 and TENANT2.

If you are using one of the AWS SDKs to interact with S3, you will need to update the way you initialize the S3 client in your app. You need to configure the non-AWS endpoint, and the S3 proxy endpoint is configured to require SSL, so make sure you prefix the endpoint URL with https:// or set sslEnabled.

For example, if you are using the AWS SDK for Java, you can do

Java

AmazonS3 s3 = AmazonS3ClientBuilder
    .standard()
    .withEndpointConfiguration(new EndpointConfiguration("https://saas-shield-for-s3-demo.ironcorelabs.com", "us-east-1"))
    .build();

Similarly, in Javascript, you can do

JavaScript

var s3 = new AWS.S3({endpoint: "saas-shield-for-s3-demo.ironcorelabs.com", region: "us-east-1", sslEnabled: true});

Alternatively, you can use a configuration object to set the S3 client parameters:

JavaScript

var config = {endpoint: "saas-shield-for-s3-demo.ironcorelabs.com", region: "us-east-1", sslEnabled: true};
AWS.config.update(config);
s3 = new AWS.S3();

You will need to configure your S3 client with this endpoint and region, enable SSL, and specify the provided credentials (access key ID and secret access key). You are then ready to run through any of the operations you do against S3 using the provided bucket.

WARNING: we clean all data out of each of these S3 buckets nightly. They are only intended for compatibility testing. Do not place any data in there that you don’t want discarded!

Already Have SaaS Shield?

If you already have a Tenant Security Proxy running in your infrastructure, once you have completed the client compatibility checks, you can skip to the Advanced Installation page to see how to install the S3 proxy in your infrastructure.

Initial Installation

Once you have determined that your S3 client software is compatible with the S3 proxy, you are ready to install SaaS Shield for Amazon S3 into your AWS infrastructure and set up a trial system to do some deeper testing. Just purchase a subscription for the product on the AWS Marketplace. We price our subscriptions so that your first tenant is always free, so you can purchase the subscription, install it and test it in your environment with your applications, and not be billed until you are ready to start using it for your customer data.

Once you purchase a subscription on the AWS Marketplace, you will be redirected to the Configuration Broker, where you can enter the information to create an administrator account and the record for your vendor. Once you have entered that data and have an account, create a new Tenant Security Proxy (TSP) configuration. After you have created the TSP configuration, click the link labeled “download SaaS Shield for Amazon S3 Templates”. This will trigger the download of a file saas_shield_s3_cfn_templates.zip to your computer. This ZIP file contains two files - one of these, tsp_config.json, contains the TSP configuration information in JSON format. We will refer to this as the TSP Config file. The information from this file is needed by the TSP to operate and will be stored in AWS using the Secure Secret Manager. The other field, saas_shield_deployment.cfn.yaml, is a CloudFormation template that you will use to install and configure the product in your AWS infrastructure. We will refer to this as the deployment template. Save the ZIP file, then extract these two files before you continue.

Preparation for Install

In order to use the S3 Proxy, you need to be able to connect to it using your S3 client. This is much easier to configure if you have a DNS name for the endpoint. In addition, to communicate over an SSL connection, the endpoint needs a certificate for that DNS name. AWS will create a DNS Zone using Route 53 that is associated with your chosen domain, and it will generate a certificate, but you will need to add records to the DNS provider for the domain you are using. Make sure you have access to the DNS provider or can get assistance from someone that does have access, and decide on the fully qualified domain name (FQDN) that you want to use to reference the S3 proxy. For example, we used saas-shield-for-s3-demo.ironcorelabs.com when we created the global instance.

Installing the Product

Make sure you have the two files that you downloaded from the Configuration Broker, along with the FQDN. To install and configure the product in AWS, follow these steps:

  1. Log into the AWS console.
  2. Select the AWS region where you want to install the product.
  3. Go to CloudFormation in the AWS Console.
  4. Create the stack that will run SaaS Shield CMK for Amazon S3.
    1. Select Create stack.
    2. Select Template is ready, Upload a template file, Choose file. Select the deployment template you downloaded from the Config Broker.
    3. Select Next.
    4. Name the stack.
    5. CloudFormation will prompt you to enter values for two parameters. The first one is the S3DNSName - enter the FQDN you selected. We recommend leaving the TspRustLog parameter set to the default value. You can set ExplicitTenantId and RejectUnknownTenantId based on your use cases and security needs or leave them set to their permissive defaults.
    6. Select Next, then Next.
    7. On the last step, acknowledge that the template creates IAM resources (it is creating a user to access the test S3 bucket).
    8. Select Create stack.

As CloudFormation creates the resources in the stack, you can select the Events tab and refresh periodically to watch its progress as it creates resources. Shortly after the deployment starts, you can enter the configuration information the TSP will need. Follow these steps:

  1. Select the Resources tab and find the entry with Logical ID TSPConfigSecret. If it is not yet created, wait 30 seconds or so and hit the refresh button on the events tab. It shouldn’t take long to create. The Physical ID is a link that will take you to the corresponding entry in the AWS Secure Secret Manager.
  2. Follow that link to go to the secret manager. Find the button labeled Retrieve secret value and press it, then press the Edit button.
  3. Select the Plaintext tab - it should display the text REPLACE-ME.
  4. Find the TSP Config File that you downloaded along with the deployment template, and copy the JSON from that file into the edit box.
  5. Click Save. This should parse the JSON and update the secret to have a sequence of key-value pairs, including the SERVICE_ACCOUNT_ID, SERVICE_CONFIG_ID, and API_KEY.

You can close the tab that opened to run the Secure Secret Manager and go back to the tab running the CloudFormation deployment. The deployment will get to a point where it is blocked trying to create the S3Certificate. This should happen after it has completed creation of the S3DNSBaseEntry and S3DNSWildcardEntry. In order to complete creation of the certificate, AWS must verify that you control the domain for which it is generating the certificate. This can happen automatically, but you need to add the records to your DNS provider for the check to succeed. Follow these steps:

  1. Select the Resources tab and find the entry with Logical ID S3DNSZone. The Physical ID is a link that will take you to the appropriate DNS Zone entry in Route 56.
  2. Click the link to open the DNS Zone Entry. You should see a list of DNS records.
  3. Find the record with type NS - the Value for the record contains four different host names (one for each of the top level domains .com, .org, .net, and .co.uk).
  4. Go to your root DNS provider and add a corresponding NS record for the domain name you are creating, with one of these four hostnames.

After you have added the NS records, you can close the tab that opened to run the Route 53 editor and return to the tab running the CloudFormation deployment. CloudFormation will be able to complete validation of the certificate, and it will proceed with the deployment. When the deployment completes successfully, CloudFormation has done the following:

  1. Created a stack that manages several secrets (using the Secure Secret Manager). These entries are all named with a /saas_shield_s3/${StackName}/ prefix.
  2. Created a stack that manages a number of different resources necessary to run the product, including the following:
    1. Additional AWS Secure Secret Manager secrets for secret values required by the TSP - all secrets are named with a /saas_shield_s3/${StackName}/ prefix.
    2. An instance of the S3 Proxy running in Elastic Container Service (ECS)
    3. An instance of the Tenant Security Proxy (TSP) running in ECS
    4. A test bucket named ironcore-test-${DomainName}, where DomainName is the FQDN you provided, with the periods replaced by underscores
    5. A test user named ${StackName}-S3User- followed by a random suffix. This user has permission to access the test bucket, and the credentials for this user are the ones that you will need to send requests to the S3 proxy
    6. An additional secret, named /saas-shield-s3/${StackName}/proxy/s3-credentials, that contains the API Key ID and secret key for the test user
    7. A DNS Zone for your selected domain name, and a certificate for that domain and all subdomains of it
    8. Additional network services, load balancers, and supporting infrastructure to run the product
    9. A CloudWatch log group named ${Stackname}

After the stack has been created, you need to retrieve the values of the credentials for the test user that was created, so you can supply them to your S3 clients. To do this, go back to the Resources tab of the new deployment stack, find the entry with Logical ID S3CredsSecret and click on the link under Physical ID. This will take you to the entry in the Secrets Manager. Find the Secret value section and click Retrieve secret value. This will display the access key ID and the secret key that you need to provide to your S3 client.

The S3 proxy is now ready to start processing requests. You will need to set up a tenant mapping before you can use it to encrypt data - see the Creating and Mapping Tenants section for details.

Update Your App

The S3 proxy is now ready to go. You should just update the configuration for your S3 client library much like you did when you went through the steps in the Checking Client Compatibility section. Provide the access key ID and secret access key, add an endpoint using the FQDN you created, enable SSL, and the client should be configured to use the new S3 proxy. If you write to the test bucket, everything should be encrypted, and the encryption key is wrapped using the KMS you set up in your AWS account.

If you write an object to the bucket, you can examine it in the S3 console and see that it is encrypted, and that the tenant ID and wrapped encryption key are stored in tags on the object. If you get the object from S3 using the proxy, it will be decrypted automatically.

Advanced Installation

We have information on our Advanced Installation page about how to install the product in additional regions, or to install a version for development, QA, or production.

Need Help?

If you encounter issues when installing or running the product, the first troubleshooting step is to check the logs that are written to CloudWatch in your AWS account. Just find the log group named ${StackName}, then examine the s3-proxy/s3-proxy/* log stream. This is the log from the S3 Proxy container. This will often provide information about the cause of an issue.

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

Was this page helpful?