Creating and Mapping Tenants

Once the S3 proxy is configured and connected to the Tenant Security Proxy, it is ready to start processing requests. However, it is using a default tenant mapping file that does not contain any mappings, so it will not actually encrypt any objects uploaded to S3. You are now ready to create a tenant. Return to the Configuration Broker, or log in again, select Tenants, and add a new tenant. Assign a name and a tenant ID, and provide an email address for the tenant administrator. When you enter the data and click Invite, the Configuration Broker will send an email to that address that contains a sign-up link. Clicking on the link will take the user to a page on the Configuration Broker where they can enter the information for the tenant. Once this is done, the admin can add a new KMS Configuration. If you are setting up the initial test system, we suggest that you create a key in your AWS KMS - just create an AWS KMS configuration and follow the instructions.

Once the tenant is created and has an active primary KMS configuration, you can use that tenant to encrypt data. If you are using the installation created by our CloudFormation template, you can go to the test bucket in S3 (ironcore-test-${DomainName}) and find an object named tenant-mapping.conf. This is the mapping file that specifies which tenant controls the encryption key for each object written to the S3 proxy. If you set up the S3 proxy to work with an existing installation, you specified the region, bucket, and key for the mapping file.

Mapping File Format

The tenant mapping file uses HOCON, a JSON superset, with the following form:

Conf

mapping = [
   { explicit-tenant-regex = {BUCKET_AND_KEY_REGEX}, tenant-id = {TENANT_ID} },
   { capture-tenant-regex = {CAPTURE_TENANT_REGEX} },
]

The initial mapping file has no elements in the mapping array - you will need to add a mapping entry for your test bucket. After you have created the first tenant, you can download the mapping file (tenant-mapping.conf or the name you provided) from S3 and edit it. For our test installation, it should look something like this, if your FQDN is tryit.foo.com and you added a tenant with ID TENANT1:

Conf

mapping = [
   { explicit-tenant-regex = "ironcore-labs-tryit-foo-com/.*", tenant-id = "TENANT1" }
]

This specifies that everything written to the test bucket should be encrypted using TENANT1’s KMS.

There are more details on the mapping file and on the internals of the S3 proxy in the How It Works section.