1. Docs

SaaS Shield Tenant Security Proxy

The Tenant Security Proxy (TSP) is a service that is delivered as a Docker container. You run that container within your SaaS infrastructure. The TSP acts as a gateway between your application and your customers’ cloud security infrastructure. It has the ability to communicate with cloud KMS instances running in AWS, GCP, Azure, and Thales (see full list of supported services here, depending on which providers your tenants are using. Tenant admins configure their own KMSes using the Configuration Broker.

The TSP service does not require any persistent storage. When it starts, it reads configuration that is provided to the container, and it uses that information to fetch further configuration values, including the tenant KMS configurations, from the Configuration Broker and decrypt them. All KMS configurations are held in memory.

Logging Service

As of version 4.0.0, the TSP has a companion logging service, the Tenant Security Logdriver. (Prior to 4.0.0, the Logdriver was built into same the container as the TSP.) This service supports SaaS Shield’s Real Time Security Events, which creates rich audit trails containing detailed security events from your TSP, such as requests to wrap or unwrap keys, and pushes them to your tenants’ logging / SIEM systems.


The TSP Docker container is hosted publicly on the IronCore Labs Docker registry. Find the latest tag available and pull down the image by running this command:

docker pull gcr.io/ironcore-images/tenant-security-proxy:{tag}

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

After you have successfully pulled the TSP, you should be able to see the image listed in your docker images list.


In order to successfully start the Docker container, you need to provide it with a configuration generated from the Configuration Broker. Once you have this configuration, you can run

docker run \ --env-file config-broker-config.env \ -p 32804:7777 \ -m 256M \ gcr.io/ironcore-images/tenant-security-proxy:{tag}

The exposed port 32804 can be changed to a different value of your choosing if you want to run the service on a different port. If the image starts successfully, then the TSP service is running locally on the provided port. You’ll need to provide the full domain and port where the container is running when using the Tenant Security Client Libraries.

The -m argument to Docker sets the amount of memory available to the container. We recommend allocating at least 256MB for the container. If you anticipate large numbers of tenants, you should increase the memory limit by roughly 20KB per tenant.

When the TSP service starts, it immediately attempts to make a request to the Configuration Broker to retrieve and decrypt all of the KMS configurations that were created by each of your tenants. The decrypted configurations are kept in memory only.

Every 10 minutes, the container re-fetches encrypted tenant configurations from the Configuration Broker. This allows the TSP to get updates on any new, changed, or removed KMS configurations for your tenants.

Once the container has successfully started, it can be accessed from your applications via the Tenant Security Client, allowing your apps to encrypt and decrypt your customers’ data using keys they control and to generate security events that can be delivered to your customers’ logging and SIEM services by a companion Tenant Security Logdriver.

Running with Tenant Security Logdriver

You should run the TSP (version 4.0.0 and after) and Logdriver together in your environment. Logdriver’s configuration section provides more detail regarding starting up both services together.

Starting Locally for Development

If you want to run the TSP in Docker running on your local machine, the command is slightly different

docker run --env-file <CONFIG-FILE> -p 32804:7777 -m 256M \ gcr.io/ironcore-images/tenant-security-proxy:{tag}

The Logdriver deployment section has an example showing how you can start the TSP and Logdriver together using docker compose.

Deployment and Tuning

Running TSP in a production deployment is usually more involved than just starting it up. See the deployment documentation for Kubernetes and Docker compose examples, health check information, configuration, performance tuning, and troubleshooting information.

Was this page helpful?