Summary Prerequisites and limitations Architecture Tools Epics Related resources Additional information Attachments

Implement SaaS tenant isolation for Amazon S3 by using an AWS Lambda token vending machine

Created by Tabby Ward (AWS), Sravan Periyathambi (AWS), and Thomas Davis (AWS)

Environment: PoC or pilot

Technologies: Modernization

AWS services: AWS Identity and Access Management; AWS Lambda; Amazon S3; AWS STS

Summary

Multitenant SaaS applications must implement systems to ensure that tenant isolation is maintained. When you store tenant data on the same Amazon Web Services (AWS) resource—such as multiple tenants storing data in the same Amazon Simple Storage Service (Amazon S3) bucket—you must ensure that cross-tenant access cannot occur. Token vending machines (TVMs) are one way to provide tenant data isolation. These machines provide a mechanism for obtaining tokens while abstracting the complexity of how these tokens are generated. Developers can use a TVM without having detailed knowledge of how it produces tokens.

This pattern implements a TVM by using AWS Lambda. The TVM generates a token that consists of temporary security token service (STS) credentials that limit access to a single SaaS tenant's data in an S3 bucket.

TVMs, and the code that’s provided with this pattern, are typically used with claims that are derived from JSON Web Tokens (JWTs) to associate requests for AWS resources with a tenant-scoped AWS Identity and Access Management (IAM) policy. You can use the code in this pattern as a basis to implement a SaaS application that generates scoped, temporary STS credentials based on the claims provided in a JWT token.

Prerequisites and limitations

Prerequisites

An active AWS account.
AWS Command Line Interface (AWS CLI) version 1.19.0 or later, installed and configured on macOS, Linux, or Windows. Alternatively, you can use AWS CLI version 2.1 or later.

Limitations

This code runs in Java and doesn’t currently support other programming languages.
The sample application does not include AWS cross-Region or disaster recovery (DR) support.
This pattern demonstrates how a Lambda TVM for a SaaS application can provide scoped tenant access. It is not intended to be used in production environments.

Architecture

Target technology stack

AWS Lambda
Amazon S3
IAM
AWS Security Token Service (AWS STS)

Target architecture

Generating a token to gain temporary STS credentials to access data in an S3 bucket.

Tools

AWS services

AWS Command Line Interface (AWS CLI) is an open-source tool that helps you interact with AWS services through commands in your command-line shell.
AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.
AWS Lambda is a compute service that helps you run code without needing to provision or manage servers. It runs your code only when needed and scales automatically, so you pay only for the compute time that you use.
AWS Security Token Service (AWS STS) helps you request temporary, limited-privilege credentials for users.
Amazon Simple Storage Service (Amazon S3) is a cloud-based object storage service that helps you store, protect, and retrieve any amount of data.

Code

The source code for this pattern is available as an attachment and includes the following files:

s3UploadSample.jar provides the source code for a Lambda function that uploads a JSON document to an S3 bucket.
tvm-layer.zip provides a reusable Java library that supplies a token (STS temporary credentials) for the Lambda function to access the S3 bucket and upload the JSON document.
token-vending-machine-sample-app.zip provides the source code used to create these artifacts and compilation instructions.

To use these files, follow the instructions in the next section.

Epics

Task Description Skills required

Task	Description	Skills required
Determine variable values.	The implementation of this pattern includes several variable names that must be used consistently. Determine the values that should be used for each variable, and provide that value when requested in subsequent steps. <AWS Account ID> ─ The 12-digit account ID that is associated with the AWS account you are implementing this pattern in. For information about how to find your AWS cccount ID, see Your AWS account ID and its alias in the IAM documentation. <AWS Region> ─ The AWS Region that you are implementing this pattern in. For more information on AWS Regions, see Regions and Availability Zones on the AWS website. <sample-tenant-name> ─ The name of a tenant to use in the application. We recommend that you use only alphanumeric characters in this value for simplicity, but you can use any valid name for an S3 object key. <sample-tvm-role-name> ─ The name of the IAM role attached to the Lambda function that runs the TVM and sample application. The role name is a string that consists of uppercase and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: underscore (_), plus sign (+), equal sign (=), comma (,), period (.), at sign (@), and hyphen (-). The role name must be unique within the account. <sample-app-role-name> ─ The name of the IAM role that is assumed by the Lambda function when it generates scoped, temporary STS credentials. The role name is a string that consists of uppercase and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: underscore (_), plus sign (+), equal sign (=), comma (,), period (.), at sign (@), and hyphen (-). The role name must be unique within the account. <sample-app-function-name> ─ The name of the Lambda function. This is a string that’s up to 64 characters in length. <sample-app-bucket-name> ─ The name of an S3 bucket that must be accessed with permissions that are scoped to a specific tenant. S3 bucket names: Must be between 3 and 63 characters long. Must consist of only lowercase letters, numbers, periods (.), and hyphens (-). Must begin and end with a letter or number. Must not be formatted as an IP address (for example, 192.168.5.4). Must be unique within a partition. A partition is a grouping of Regions. AWS currently has three partitions: `aws` (Standard Regions), `aws-cn` (China Regions), and `aws-us-gov` (AWS GovCloud [US] Regions).	Cloud administrator

Determine variable values.

The implementation of this pattern includes several variable names that must be used consistently. Determine the values that should be used for each variable, and provide that value when requested in subsequent steps.

<AWS Account ID> ─ The 12-digit account ID that is associated with the AWS account you are implementing this pattern in. For information about how to find your AWS cccount ID, see Your AWS account ID and its alias in the IAM documentation.

<AWS Region> ─ The AWS Region that you are implementing this pattern in. For more information on AWS Regions, see Regions and Availability Zones on the AWS website.

<sample-tenant-name> ─ The name of a tenant to use in the application. We recommend that you use only alphanumeric characters in this value for simplicity, but you can use any valid name for an S3 object key.

<sample-tvm-role-name> ─ The name of the IAM role attached to the Lambda function that runs the TVM and sample application. The role name is a string that consists of uppercase and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: underscore (_), plus sign (+), equal sign (=), comma (,), period (.), at sign (@), and hyphen (-). The role name must be unique within the account.

<sample-app-role-name> ─ The name of the IAM role that is assumed by the Lambda function when it generates scoped, temporary STS credentials. The role name is a string that consists of uppercase and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: underscore (_), plus sign (+), equal sign (=), comma (,), period (.), at sign (@), and hyphen (-). The role name must be unique within the account.

<sample-app-function-name> ─ The name of the Lambda function. This is a string that’s up to 64 characters in length.

<sample-app-bucket-name> ─ The name of an S3 bucket that must be accessed with permissions that are scoped to a specific tenant. S3 bucket names:

Must be between 3 and 63 characters long.
Must consist of only lowercase letters, numbers, periods (.), and hyphens (-).
Must begin and end with a letter or number.
Must not be formatted as an IP address (for example, 192.168.5.4).
Must be unique within a partition. A partition is a grouping of Regions. AWS currently has three partitions: aws (Standard Regions), aws-cn (China Regions), and aws-us-gov (AWS GovCloud [US] Regions).

Cloud administrator

Task Description Skills required

Task	Description	Skills required
Create an S3 bucket for the sample application.	Use the following AWS CLI command to create an S3 bucket. Provide the <sample-app-bucket-name> value in the code snippet: `aws s3api create-bucket --bucket <sample-app-bucket-name>` The Lambda sample application uploads JSON files to this bucket.	Cloud administrator

Create an S3 bucket for the sample application.

Use the following AWS CLI command to create an S3 bucket. Provide the <sample-app-bucket-name> value in the code snippet:


aws s3api create-bucket --bucket <sample-app-bucket-name>

The Lambda sample application uploads JSON files to this bucket.

Cloud administrator

Task Description Skills required

Task	Description	Skills required
Create a TVM role.	Use one of the following AWS CLI commands to create an IAM role. Provide the <sample-tvm-role-name> value in the command. For macOS or Linux shells: `aws iam create-role \ --role-name <sample-tvm-role-name> \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}'` For the Windows command line: `aws iam create-role ^ --role-name <sample-tvm-role-name> ^ --assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Principal\": {\"Service\": \"lambda.amazonaws.com\"}, \"Action\": \"sts:AssumeRole\"}]}"` The Lambda sample application assumes this role when the application is invoked. The capability to assume the application role with a scoped policy gives the code broader permissions to access the S3 bucket.	Cloud administrator
Create an inline TVM role policy.	Use one of the following AWS CLI commands to create an IAM policy. Provide the <sample-tvm-role-name>, <AWS Account ID>, and <sample-app-role-name> values in the command. For macOS or Linux shells: `aws iam put-role-policy \ --role-name <sample-tvm-role-name> \ --policy-name assume-app-role \ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>" } ]}'` For the Windows command line: `aws iam put-role-policy ^ --role-name <sample-tvm-role-name> ^ --policy-name assume-app-role ^ --policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": \"sts:AssumeRole\", \"Resource\": \"arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>\"}]}"` This policy is attached to the TVM role. It gives the code the capability to assume the application role, which has broader permissions to access the S3 bucket.	Cloud administrator
Attach the managed Lambda policy.	Use the following AWS CLI command to attach the `AWSLambdaBasicExecutionRole` IAM policy. Provide the <sample-tvm-role-name> value in the command: `aws iam attach-role-policy \ --role-name <sample-tvm-role-name> \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole` For the Windows command line: `aws iam attach-role-policy ^ --role-name <sample-tvm-role-name> ^ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole` This managed policy is attached to the TVM role to permit Lambda to send logs to Amazon CloudWatch.	Cloud administrator

Create a TVM role.

Use one of the following AWS CLI commands to create an IAM role. Provide the <sample-tvm-role-name> value in the command.

For macOS or Linux shells:


aws iam create-role \
--role-name <sample-tvm-role-name> \
--assume-role-policy-document '{
    "Version": "2012-10-17", 
    "Statement": [
        {
            "Effect": "Allow", 
            "Principal": {
                "Service": "lambda.amazonaws.com"
            }, 
            "Action": "sts:AssumeRole"
        }
    ]}'

For the Windows command line:


aws iam create-role ^
--role-name <sample-tvm-role-name> ^
--assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Principal\": {\"Service\": \"lambda.amazonaws.com\"}, \"Action\": \"sts:AssumeRole\"}]}"

The Lambda sample application assumes this role when the application is invoked. The capability to assume the application role with a scoped policy gives the code broader permissions to access the S3 bucket.

Cloud administrator

Create an inline TVM role policy.

Use one of the following AWS CLI commands to create an IAM policy. Provide the <sample-tvm-role-name>, <AWS Account ID>, and <sample-app-role-name> values in the command.

For macOS or Linux shells:


aws iam put-role-policy \
--role-name <sample-tvm-role-name> \
--policy-name assume-app-role \
--policy-document '{
    "Version": "2012-10-17", 
    "Statement": [
        {
            "Effect": "Allow", 
            "Action": "sts:AssumeRole", 
            "Resource": "arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>"
        }
    ]}'

For the Windows command line:


aws iam put-role-policy ^
--role-name <sample-tvm-role-name> ^
--policy-name assume-app-role ^
--policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": \"sts:AssumeRole\", \"Resource\": \"arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>\"}]}"

This policy is attached to the TVM role. It gives the code the capability to assume the application role, which has broader permissions to access the S3 bucket.

Cloud administrator

Attach the managed Lambda policy.

Use the following AWS CLI command to attach the AWSLambdaBasicExecutionRole IAM policy. Provide the <sample-tvm-role-name> value in the command:


aws iam attach-role-policy \
--role-name <sample-tvm-role-name> \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

For the Windows command line:


aws iam attach-role-policy ^
--role-name <sample-tvm-role-name> ^
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

This managed policy is attached to the TVM role to permit Lambda to send logs to Amazon CloudWatch.

Cloud administrator

Task Description Skills required

Task	Description	Skills required
Create the application role.	Use one of the following AWS CLI commands to create an IAM role. Provide the <sample-app-role-name>, <AWS Account ID>, and <sample-tvm-role-name> values in the command. For macOS or Linux shells: `aws iam create-role \ --role-name <sample-app-role-name> \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name>" }, "Action": "sts:AssumeRole" } ]}'` For the Windows command line: `aws iam create-role ^ --role-name <sample-app-role-name> ^ --assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\",\"Principal\": {\"AWS\": \"arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name>\"},\"Action\": \"sts:AssumeRole\"}]}"` The Lambda sample application assumes this role with a scoped policy to get tenant-based access to an S3 bucket.	Cloud administrator
Create an inline application role policy.	Use one of the following AWS CLI commands to create an IAM policy. Provide the <sample-app-role-name> and <sample-app-bucket-name> values in the command. For macOS or Linux shells: `aws iam put-role-policy \ --role-name <sample-app-role-name> \ --policy-name s3-bucket-access \ --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::<sample-app-bucket-name>/" }, { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::<sample-app-bucket-name>" } ]}'` For the Windows command line: `aws iam put-role-policy ^ --role-name <sample-app-role-name> ^ --policy-name s3-bucket-access ^ --policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"s3:PutObject\", \"s3:GetObject\", \"s3:DeleteObject\"], \"Resource\": \"arn:aws:s3:::<sample-app-bucket-name>/\"}, {\"Effect\": \"Allow\", \"Action\": [\"s3:ListBucket\"], \"Resource\": \"arn:aws:s3:::<sample-app-bucket-name>\"}]}"` This policy is attached to the application role. It provides broad access to objects in the S3 bucket. When the sample application assumes the role, these permissions are scoped to a specific tenant with the TVM's dynamically generated policy.	Cloud administrator

Create the application role.

Use one of the following AWS CLI commands to create an IAM role. Provide the <sample-app-role-name>, <AWS Account ID>, and <sample-tvm-role-name> values in the command.

For macOS or Linux shells:


aws iam create-role \
--role-name <sample-app-role-name> \
--assume-role-policy-document '{
    "Version": "2012-10-17", 
    "Statement": [
        {
            "Effect": 
            "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name>"
            },
            "Action": "sts:AssumeRole"
        }
    ]}'

For the Windows command line:


aws iam create-role ^
--role-name <sample-app-role-name> ^
--assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\",\"Principal\": {\"AWS\": \"arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name>\"},\"Action\": \"sts:AssumeRole\"}]}"

The Lambda sample application assumes this role with a scoped policy to get tenant-based access to an S3 bucket.

Cloud administrator

Create an inline application role policy.

Use one of the following AWS CLI commands to create an IAM policy. Provide the <sample-app-role-name> and <sample-app-bucket-name> values in the command.

For macOS or Linux shells:


aws iam put-role-policy \
--role-name <sample-app-role-name> \
--policy-name s3-bucket-access \
--policy-document '{
    "Version": "2012-10-17", 
    "Statement": [
        {
            "Effect": "Allow", 
            "Action": [
                "s3:PutObject", 
                "s3:GetObject", 
                "s3:DeleteObject"
            ], 
            "Resource": "arn:aws:s3:::<sample-app-bucket-name>/*"
        }, 
        {
            "Effect": "Allow", 
            "Action": ["s3:ListBucket"], 
            "Resource": "arn:aws:s3:::<sample-app-bucket-name>"
        }
    ]}'

For the Windows command line:


aws iam put-role-policy ^
--role-name <sample-app-role-name> ^
--policy-name s3-bucket-access ^
--policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"s3:PutObject\", \"s3:GetObject\", \"s3:DeleteObject\"], \"Resource\": \"arn:aws:s3:::<sample-app-bucket-name>/*\"}, {\"Effect\": \"Allow\", \"Action\": [\"s3:ListBucket\"], \"Resource\": \"arn:aws:s3:::<sample-app-bucket-name>\"}]}"

This policy is attached to the application role. It provides broad access to objects in the S3 bucket. When the sample application assumes the role, these permissions are scoped to a specific tenant with the TVM's dynamically generated policy.

Cloud administrator

Task Description Skills required

Task	Description	Skills required
Download the compiled source files.	Download the `s3UploadSample.jar` and `tvm-layer.zip` files, which are included as attachments. The source code used to create these artifacts and compilation instuctions are provided in `token-vending-machine-sample-app.zip`.	Cloud administrator
Create the Lambda layer.	Use the following AWS CLI command to create a Lambda layer, which makes the TVM accessible to Lambda. Note: If you aren’t running this command from the location where you downloaded `tvm-layer.zip`, provide the correct path to `tvm-layer.zip` in the `--zip-file` parameter. `aws lambda publish-layer-version \ --layer-name sample-token-vending-machine \ --compatible-runtimes java11 \ --zip-file fileb://tvm-layer.zip` For the Windows command line: `aws lambda publish-layer-version ^ --layer-name sample-token-vending-machine ^ --compatible-runtimes java11 ^ --zip-file fileb://tvm-layer.zip` This command creates a Lambda layer that contains the reusable TVM library.	Cloud administrator, App developer
Create the Lambda function.	Use the following AWS CLI command to create a Lambda function. Provide the <sample-app-function-name>, <AWS Account ID>, <AWS Region>, <sample-tvm-role-name>, <sample-app-bucket-name>, and <sample-app-role-name> values in the command. Note: If you aren’t running this command from the location where you downloaded `s3UploadSample.jar`, provide the correct path to `s3UploadSample.jar` in the `--zip-file` parameter. `aws lambda create-function \ --function-name <sample-app-function-name> \ --timeout 30 \ --memory-size 256 \ --runtime java11 \ --role arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name> \ --handler com.amazon.aws.s3UploadSample.App \ --zip-file fileb://s3UploadSample.jar \ --layers arn:aws:lambda:<AWS Region>:<AWS Account ID>:layer:sample-token-vending-machine:1 \ --environment "Variables={S3_BUCKET=<sample-app-bucket-name>, ROLE=arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>}"` For Windows command line: `aws lambda create-function ^ --function-name <sample-app-function-name> ^ --timeout 30 ^ --memory-size 256 ^ --runtime java11 ^ --role arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name> ^ --handler com.amazon.aws.s3UploadSample.App ^ --zip-file fileb://s3UploadSample.jar ^ --layers arn:aws:lambda:<AWS Region>:<AWS Account ID>:layer:sample-token-vending-machine:1 ^ --environment "Variables={S3_BUCKET=<sample-app-bucket-name>,ROLE=arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>}"` This command creates a Lambda function with the sample application code and the TVM layer attached. It also sets two environment variables: `S3_BUCKET` and `ROLE`. The sample application uses these variables to determine the role to assume and the S3 bucket to upload JSON documents to.	Cloud administrator, App developer

Download the compiled source files.

Download the s3UploadSample.jar and tvm-layer.zip files, which are included as attachments. The source code used to create these artifacts and compilation instuctions are provided in token-vending-machine-sample-app.zip.

Cloud administrator

Create the Lambda layer.

Use the following AWS CLI command to create a Lambda layer, which makes the TVM accessible to Lambda.

Note: If you aren’t running this command from the location where you downloaded tvm-layer.zip, provide the correct path to tvm-layer.zip in the --zip-file parameter.


aws lambda publish-layer-version \
--layer-name sample-token-vending-machine \
--compatible-runtimes java11 \
--zip-file fileb://tvm-layer.zip

For the Windows command line:


aws lambda publish-layer-version ^
--layer-name sample-token-vending-machine ^
--compatible-runtimes java11 ^
--zip-file fileb://tvm-layer.zip

This command creates a Lambda layer that contains the reusable TVM library.

Cloud administrator, App developer

Create the Lambda function.

Use the following AWS CLI command to create a Lambda function. Provide the <sample-app-function-name>, <AWS Account ID>, <AWS Region>, <sample-tvm-role-name>, <sample-app-bucket-name>, and <sample-app-role-name> values in the command.

Note: If you aren’t running this command from the location where you downloaded s3UploadSample.jar, provide the correct path to s3UploadSample.jar in the --zip-file parameter.


aws lambda create-function \
--function-name <sample-app-function-name>  \
--timeout 30 \
--memory-size 256 \
--runtime java11 \
--role arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name> \
--handler com.amazon.aws.s3UploadSample.App \
--zip-file fileb://s3UploadSample.jar \
--layers arn:aws:lambda:<AWS Region>:<AWS Account ID>:layer:sample-token-vending-machine:1 \
--environment "Variables={S3_BUCKET=<sample-app-bucket-name>,
ROLE=arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>}"

For Windows command line:


aws lambda create-function ^
--function-name <sample-app-function-name>  ^
--timeout 30 ^
--memory-size 256 ^
--runtime java11 ^
--role arn:aws:iam::<AWS Account ID>:role/<sample-tvm-role-name> ^
--handler com.amazon.aws.s3UploadSample.App ^
--zip-file fileb://s3UploadSample.jar ^
--layers arn:aws:lambda:<AWS Region>:<AWS Account ID>:layer:sample-token-vending-machine:1 ^
--environment "Variables={S3_BUCKET=<sample-app-bucket-name>,ROLE=arn:aws:iam::<AWS Account ID>:role/<sample-app-role-name>}"

This command creates a Lambda function with the sample application code and the TVM layer attached. It also sets two environment variables: S3_BUCKET and ROLE. The sample application uses these variables to determine the role to assume and the S3 bucket to upload JSON documents to.

Cloud administrator, App developer

Task Description Skills required

Task	Description	Skills required
Invoke the Lambda sample application.	Use one of the following AWS CLI commands to start the Lambda sample application with its expected payload. Provide the <sample-app-function-name> and <sample-tenant-name> values in the command. For macOS and Linux shells: `aws lambda invoke \ --function <sample-app-function-name> \ --invocation-type RequestResponse \ --payload '{"tenant": "<sample-tenant-name>"}' \ --cli-binary-format raw-in-base64-out response.json` For the Windows command line: `aws lambda invoke ^ --function <sample-app-function-name> ^ --invocation-type RequestResponse ^ --payload "{\"tenant\": \"<sample-tenant-name>\"}" ^ --cli-binary-format raw-in-base64-out response.json` This command calls the Lambda function and returns the result in a `response.json` document. On many Unix-based systems, you can change `response.json` to `/dev/stdout` to output the results directly to your shell without creating another file. Note: Changing the <sample-tenant-name> value in subsequent invocations of this Lambda function alters the location of the JSON document and the permissions the token provides.	Cloud administrator, App developer
View the S3 bucket to see created objects.	Browse to the S3 bucket ( <sample-app-bucket-name>) that you created earlier. This bucket contains an S3 object prefix with the value of <sample-tenant-name>. Under that prefix, you will find a JSON document named with a UUID. Invoking the sample application multiple times adds more JSON documents.	Cloud administrator
View Cloudwatch logs for the sample application.	View the Cloudwatch logs associated with the Lambda function named <sample-app-function-name>. For instructions, see Accessing Amazon CloudWatch logs for AWS Lambda in the AWS Lambda documentation. You can view the tenant-scoped policy generated by the TVM in these logs. This tenant-scoped policy gives permissions for the sample application to the Amazon S3 PutObject, GetObject, DeleteObject, and ListBucket APIs, but only for the object prefix associated with <sample-tenant-name>. In subsequent invocations of the sample application, if you change the <sample-tenant-name>, the TVM updates the scoped policy to correspond to the tenant provided in the invocation payload. This dynamically generated policy shows how tenant-scoped access can be maintained with a TVM in SaaS applications. The TVM functionality is provided in a Lambda layer so that it can be attached to other Lambda functions used by an application without having to replicate the code. For an illustration of the dynamically generated policy, see the Additional information section.	Cloud administrator

Invoke the Lambda sample application.

Use one of the following AWS CLI commands to start the Lambda sample application with its expected payload. Provide the <sample-app-function-name> and <sample-tenant-name> values in the command.

For macOS and Linux shells:


aws lambda invoke \
--function <sample-app-function-name> \
--invocation-type RequestResponse \
--payload '{"tenant": "<sample-tenant-name>"}' \
--cli-binary-format raw-in-base64-out response.json

For the Windows command line:


aws lambda invoke ^
--function <sample-app-function-name> ^
--invocation-type RequestResponse ^
--payload "{\"tenant\": \"<sample-tenant-name>\"}" ^
--cli-binary-format raw-in-base64-out response.json

This command calls the Lambda function and returns the result in a response.json document. On many Unix-based systems, you can change response.json to /dev/stdout to output the results directly to your shell without creating another file.

Note: Changing the <sample-tenant-name> value in subsequent invocations of this Lambda function alters the location of the JSON document and the permissions the token provides.

Cloud administrator, App developer

View the S3 bucket to see created objects.

Browse to the S3 bucket ( <sample-app-bucket-name>) that you created earlier. This bucket contains an S3 object prefix with the value of <sample-tenant-name>. Under that prefix, you will find a JSON document named with a UUID. Invoking the sample application multiple times adds more JSON documents.

Cloud administrator

View Cloudwatch logs for the sample application.

View the Cloudwatch logs associated with the Lambda function named <sample-app-function-name>. For instructions, see Accessing Amazon CloudWatch logs for AWS Lambda in the AWS Lambda documentation. You can view the tenant-scoped policy generated by the TVM in these logs. This tenant-scoped policy gives permissions for the sample application to the Amazon S3 PutObject, GetObject, DeleteObject, and ListBucket APIs, but only for the object prefix associated with <sample-tenant-name>. In subsequent invocations of the sample application, if you change the <sample-tenant-name>, the TVM updates the scoped policy to correspond to the tenant provided in the invocation payload. This dynamically generated policy shows how tenant-scoped access can be maintained with a TVM in SaaS applications.

The TVM functionality is provided in a Lambda layer so that it can be attached to other Lambda functions used by an application without having to replicate the code.

For an illustration of the dynamically generated policy, see the Additional information section.

Cloud administrator

Related resources

Isolating Tenants with Dynamically Generated IAM Policies (blog post)
Applying Dynamically Generated Isolation Policies in SaaS Environment (blog post)
AWS SaaS Boost (an open-source reference environment that helps you move your SaaS offering to AWS)

Additional information

The following Amazon Cloudwatch log shows the dynamically generated policy produced by the TVM code in this pattern. In this screenshot, the <sample-app-bucket-name> is DOC-EXAMPLE-BUCKET and the <sample-tenant-name> is test-tenant-1. The STS credentials returned by this scoped policy are unable to perform any actions on objects in the S3 bucket except for objects that are associated with the object key prefix test-tenant-1.

JSON policy document allowing S3 actions on a specific bucket with prefix conditions.

Attachments

To access additional content that is associated with this document, unzip the following file: attachment.zip

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Deploy nested applications using AWS SAM

Implement the serverless saga pattern by using AWS Step Functions