View a markdown version of this page

Security in AWS CDK Blocks - AWS CDK Blocks

Security in AWS CDK Blocks

Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations.

Security is a shared responsibility between AWS and you. The shared responsibility model describes this as security of the cloud and security in the cloud:

  • Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the effectiveness of our security as part of the AWS Compliance Programs. AWS CDK Blocks is a framework that you install from npm. It runs in your build and in your AWS account, so compliance coverage comes from the AWS services that it provisions for your app. To learn which compliance programs apply to those services, see AWS Services in Scope by Compliance Program.

  • Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations.

This documentation helps you understand how to apply the shared responsibility model when using CDK Blocks.

How CDK Blocks manages permissions

CDK Blocks configures IAM permissions for the resources your application uses. When you create a CDK Block, it grants access to its own resource on one IAM role, the execution role.

All compute in a BlocksStack or BlocksBackend runs as this one role. That includes the default API function, every Compute you create, and the handlers for queues, schedules, and WebSocket connections. A Compute that runs one ApiNamespace or a whole Scope gets its own function, memory, and scaling, but it still runs as the shared role. If you move code to its own Compute, that code can still reach the same resources.

Because the role is shared, every API method in the stack can reach the resources of every CDK Block in the stack, not only the CDK Blocks it uses. To keep two workloads from reaching each other’s data, deploy them as separate stacks, or in separate AWS accounts.

Most grants are scoped to the CDK Block’s own resource, but they allow more actions than the CDK Block calls. EmailClient, secret AppSetting, and existing database Database grants are wider, as the table shows. The following table lists the grants for common CDK Blocks.

Block Actions granted to the execution role Resource

KVStore

dynamodb:GetItem, BatchGetItem, Query, Scan, ConditionCheckItem, PutItem, UpdateItem, DeleteItem, BatchWriteItem, DescribeTable, GetRecords, GetShardIterator. With a customer managed key, also the KMS actions to use that key.

The table, and dynamodb:Query on its indexes

FileBucket

s3:GetObject*, s3:PutObject, s3:PutObjectTagging, s3:PutObjectVersionTagging, s3:PutObjectRetention, s3:PutObjectLegalHold, s3:DeleteObject*, s3:List*, s3:GetBucket*, s3:Abort*. With a KMS key, also the KMS actions to use that key.

The bucket and its objects

Database

dsql:DbConnect on a dsql cluster, or rds-db:connect on an aurora cluster. The role connects as a database role that can only read and write data. On an existing database with DatabaseCluster.fromExisting({ name }), ssm:GetParameter instead, plus kms:Decrypt on any key for calls through SSM.

The cluster, the app’s database role on an aurora cluster, or the parameter that holds the connection string

Secret

secretsmanager:GetSecretValue, DescribeSecret, ListSecretVersionIds. With allowRuntimeWrite: true, also PutSecretValue, UpdateSecret, and UpdateSecretVersionStage.

The secret

AppSetting

ssm:GetParameter and ssm:PutParameter. With secret: true, also kms:Decrypt and kms:Encrypt.

The parameter. KMS access is limited to calls made through Parameter Store, or to your key if you set kmsKeyArn.

EmailClient

ses:SendEmail, ses:SendBulkEmail

All Amazon Simple Email Service (Amazon SES) identities and configuration sets in the account

AsyncJob

sqs:SendMessage, ReceiveMessage, DeleteMessage, ChangeMessageVisibility, GetQueueAttributes, GetQueueUrl

The job’s queue

The role also has the AWSLambdaBasicExecutionRole managed policy and read access to the app’s configuration file in Amazon S3. Authentication, Realtime, Agent, KnowledgeBase, and other CDK Blocks add their grants to the same role. CronJob invokes your compute through its own scheduler role.

See the full policy

Every cdk synth writes a report of the execution role to cdk.out/<stackName>.blocks-iam.json, or cdk.out/<stackName>.<backendId>.blocks-iam.json for a BlocksBackend inside your own stack. The report lists every statement on the role, the CDK Blocks that own the resources each statement references (empty when it names only literal ARNs or *), the managed policies, the permissions boundary, and every IAM role that CDK Blocks created. It is not deployed. The file is sorted, so a CI step can compare it with the previous build and fail when permissions grow.

npx cdk synth --quiet jq '.executionRole.statements[] | {actions, blocks}' cdk.out/my-app.blocks-iam.json
Grant access to your own resources

You don’t need to write IAM policies for CDK Block resources. If you add your own CDK resources in the CDK layer, you grant their permissions yourself. Grant them to stack.executionRole, where stack is the stack that BlocksStack.create(…​) returns (blocksStack in the project templates). Pass the resource’s name or ARN to your code with registerConfig. Every compute reads it from process.env at startup.

// cdk-blocks/index.cdk.ts import * as sns from 'aws-cdk-lib/aws-sns'; import { registerConfig } from 'aws-cdk-blocks/cdk'; const topic = new sns.Topic(blocksStack, 'Alerts'); topic.grantPublish(blocksStack.executionRole); registerConfig(blocksStack, 'ALERTS_TOPIC_ARN', topic.topicArn);

In your backend code, read the ARN with process.env.ALERTS_TOPIC_ARN.

Cap every role with a permissions boundary

Set defaults.permissionsBoundary to attach an IAM permissions boundary to every role that CDK Blocks creates. This covers the execution role, the helper roles that CDK Blocks create, the CDK custom resource roles, and the roles that Hosting creates. A boundary is a ceiling, not a grant. The role’s effective permissions are what both its policies and the boundary allow. Pass a policy name, a full policy ARN (needed when the policy has a path), or an iam.IManagedPolicy.

The examples on this page keep the template’s preset choice, sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production, and add settings to it. If you spread BlocksPresets.production alone, sandboxes also get production settings, such as no localhost CORS origins and retained resources.

// cdk-blocks/index.cdk.ts export const blocksStack = await BlocksStack.create(app, stackName, { backendHandlerPath: join(__dirname, 'index.handler.ts'), backendCDKPath: join(__dirname, 'index.ts'), defaults: { ...(sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production), permissionsBoundary: 'my-app-boundary' }, });

A boundary limits the shared role, but it does not split it. Every handler still runs as the same role.

Authentication

CDK Blocks provides the Auth Block to handle user identity. Sessions are kept server side and sent as HTTP-only cookies. Signing out deletes the session, and a password reset ends every session the user had.

Default store

Uses an Amazon Cognito user pool. Supports email and password sign-in, multi-factor authentication (MFA) with SMS, TOTP, or email codes, passkeys, user groups, and account recovery flows. Email codes need an Amazon Simple Email Service (Amazon SES) sender, set with the email option. Social, SAML, and OIDC providers sign in through Cognito, and each user becomes a user pool user.

store: 'builtin'

Creates no user pool. Your backend verifies each OIDC or OAuth 2.0 sign-in itself and keeps only the session.

For more information, see Authentication.

Best practices:

  • Define namespaces that hold signed-in methods with auth.protect, so a forgotten or unawaited guard can’t leave a method open.

  • Every ApiNamespace method is a public endpoint until it calls requireAuth. The local implementation applies no authentication, so a method that you forget to protect passes every local check. Call auth.requireAuth(context) server-side in every API method that accesses user data. Never trust client-side authentication alone.

  • Scope data access by user.userSub to prevent unauthorized cross-user access. It stays the same for the user’s lifetime.

  • Mark attributes that you use for authorization, such as a role or tenant ID, with userWritable: false, so end users can’t write them.

  • Set removalPolicy: 'retain' on any Auth Block whose user pool holds real users.

Data protection

CDK Blocks uses the following data protection mechanisms:

Encryption at rest

CDK Blocks encrypt stored data at rest as follows:

  • KVStore: DynamoDB encryption with the AWS managed key aws/dynamodb. Set encryption: 'customer-managed' to create a customer managed key for the table, or set encryption: KVStore.fromKmsKey(keyArn) to use a key that you already own.

  • FileBucket: S3 server-side encryption with Amazon S3 managed keys (SSE-S3). The same encryption option selects a KMS key instead. FileBucket also blocks all public access and rejects requests that do not use TLS. For records that must not change, set objectLock: { mode, retentionDays }. To log requests to a bucket, set accessLogging: true on the bucket, or defaults.storageAccessLogging: true for every bucket in the stack.

  • Database: Aurora DSQL encryption with an AWS owned key on a dsql cluster. An aurora cluster also encrypts its storage with an AWS owned key, because the express configuration accepts no customer managed KMS key. An existing database keeps the encryption that you configured for it.

  • Secret: AWS Secrets Manager encryption with the aws/secretsmanager key. AppSetting with secret: true: Parameter Store SecureString with the aws/ssm key, or your key if you set kmsKeyArn.

Encryption in transit

All communication between your application and AWS services uses TLS. API Gateway endpoints use HTTPS exclusively.

Local development

During local development, data is stored unencrypted in the .bb-data/ directory on your machine. This includes the values of Secret and secret AppSetting Blocks. This directory should be added to .gitignore (which CDK Blocks does by default) and should not contain production data.

Network security

By default, CDK Blocks deploys your API behind Amazon API Gateway, which provides:

  • HTTPS-only endpoints (HTTP is not supported)

  • DDoS protection via AWS Shield Standard

  • Request throttling, which CDK Blocks turns on for the backend API stage and the Realtime WebSocket stage. For more information, see API protection.

    Front door

    The apiFrontDoor option on BlocksStack.create or BlocksBackend.create sets how clients reach the API. With 'apigateway' (the default), clients call the API Gateway endpoint directly. With 'cloudfront', CDK Blocks puts an Amazon CloudFront distribution in front of the API. Either way, clients should call publicApiUrl, which is also the ApiUrl stack output. When you pass the backend to Hosting, the browser reaches the API on the same origin through the hosting front door, except with frontDoor: 'none', where it calls the API cross-origin. Neither option makes CloudFront the only way in: the API Gateway execute-api URL stays reachable. Changing the option later changes the API’s domain and signs out every user, so choose it before you have real users.

    Web application firewall

    AWS WAF is off by default. Set apiWaf: { enabled: true } to create a web ACL with the AWS managed Common and Known Bad Inputs rule groups and a rate limit for each IP address (rateLimit, default 1000 requests in 5 minutes). Or pass apiWaf: { webAclArn } to attach a web ACL that you already have. Under apiFrontDoor: 'cloudfront', the web ACL must be in us-east-1, so outside that Region pass webAclArn. apiWaf does not cover the Realtime WebSocket API. Browser traffic that arrives through Hosting is not rate limited by apiWaf; turn on the WAF of the hosting front door for that. When Hosting’s CloudFront distribution serves the API under `apiFrontDoor: 'cloudfront', apiWaf creates no web ACL at all, and cdk synth warns about it.

    Access logs

    API Gateway access logging is off in both presets, and cdk synth warns about this for the production preset. Turn it on with defaults.accessLogging: true. It sets the API Gateway logging role, which the whole account shares in each Region, so turn it on for only one CDK Blocks stack per Region. The same setting also turns on Amazon S3 server access logs for every FileBucket, each with its own log bucket. To keep those off, also set defaults.storageAccessLogging: false. The following example turns on access logs and the WAF.

    // cdk-blocks/index.cdk.ts export const blocksStack = await BlocksStack.create(app, stackName, { backendHandlerPath: join(__dirname, 'index.handler.ts'), backendCDKPath: join(__dirname, 'index.ts'), defaults: { ...(sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production), accessLogging: true }, apiWaf: { enabled: true, rateLimit: 2000 }, });
    VPC

    For additional network isolation, place your compute in a virtual private cloud (VPC) with defaults.vpc. CDK Blocks puts your compute functions in the VPC’s private subnets, creates the VPC endpoints that your CDK Blocks need, and wires the security groups. A VPC adds cost, such as network address translation (NAT) gateways and interface endpoints, so use one only when you need it.

    // cdk-blocks/index.cdk.ts (the template already imports cdk) import * as ec2 from 'aws-cdk-lib/aws-ec2'; // A VPC must live in a stack. Create it in a small network stack. const network = new cdk.Stack(app, `${stackName}-network`); const vpc = new ec2.Vpc(network, 'AppVpc', { maxAzs: 2, natGateways: 1 }); export const blocksStack = await BlocksStack.create(app, stackName, { backendHandlerPath: join(__dirname, 'index.handler.ts'), backendCDKPath: join(__dirname, 'index.ts'), defaults: { ...(sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production), vpc: { network: vpc } }, });

API protection

Input validation

Always validate inputs in your API methods. CDK Blocks does not perform automatic input validation. Your API methods receive whatever the client sends. To reject bad input, throw ApiError(message, 400). A plain Error thrown in an API method reaches the client as a nameless error with status 500 and the message "Internal error", so your message is lost. To let the frontend check for a specific error, pass a name, as in new ApiError(message, 404, { name: 'NotFoundError' }), and check it with isBlocksError from aws-cdk-blocks/client.

// cdk-blocks/index.ts import { ApiNamespace, ApiError } from 'aws-cdk-blocks'; export const api = new ApiNamespace(scope, 'api', (context) => ({ async createItem(title: string) { if (!title || title.length > 200) { throw new ApiError('Title must be 1-200 characters', 400); } // ... return { title }; }, }));
Rate limiting

CDK Blocks sets throttling on the backend API stage and the Realtime WebSocket stage from defaults.throttling. The API Gateway front doors that Hosting creates do not get these limits. The production preset allows 1,000 requests per second with a burst of 2,000. The sandbox preset allows 200 with a burst of 400. To change the limits, override throttling, as shown in the following example. For a limit on each client, use the rate rule in apiWaf.

CORS

Your API accepts cross-origin requests only from the origins in defaults.allowedOrigins, plus the hosting front door’s origin when you use Hosting. Each entry in allowedOrigins is a regular expression, so escape the dots. The production preset lists no origins. The sandbox preset allows localhost and 127.0.0.1, so a local frontend can call a deployed sandbox. With Hosting, browser calls through the hosting front door use the same origin, so you don’t need to configure CORS. If you host your frontend somewhere else, add its origin.

// cdk-blocks/index.cdk.ts export const blocksStack = await BlocksStack.create(app, stackName, { backendHandlerPath: join(__dirname, 'index.handler.ts'), backendCDKPath: join(__dirname, 'index.ts'), defaults: { ...(sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production), throttling: { rateLimit: 2000, burstLimit: 4000 }, allowedOrigins: ['https://app\\.example\\.com'], }, });

Managing secrets

Don’t hardcode secrets (API keys, database passwords, third-party tokens) in your source code. Don’t put them in Lambda environment variables or in registerConfig either. Anyone who can read the function’s configuration, or the app’s configuration file, can read those values. Store production secrets in the Secret Block. Each Secret is one AWS Secrets Manager secret, and your code reads it when it needs the value.

// cdk-blocks/index.ts import { ApiNamespace, ApiError, Scope, Secret } from 'aws-cdk-blocks'; const scope = new Scope('my-app'); const paymentKey = new Secret(scope, 'payment-api-key'); export const api = new ApiNamespace(scope, 'api', (context) => ({ async charge(amount: number) { const key = await paymentKey.get(); if (key === null) { throw new ApiError('Payments are not configured', 503); } // Call the payment provider with key ... return { charged: amount }; }, }));

A Secret is read-only at runtime by default. The object has no put() method, and the execution role can only read the secret. get() returns null until a value is set. Set the value outside your app: from your stack’s settings resource group in the AWS Resource Groups console, which the app’s /aws-blocks/settings route opens, or with aws secretsmanager put-secret-value. The default name comes from the stack and CDK Block IDs, so the CLI works without a name. Set name if you want one that does not depend on them. Your app reads a new value within 5 minutes, or the time you set with cacheTtlSeconds.

If your app sets or rotates the value itself, pass allowRuntimeWrite: true. Then put() is available and the role can write the secret:

const token = new Secret(scope, 'service-token', { allowRuntimeWrite: true }); await token.put('new-value');

For a random value that only your app uses, such as a signing key, pass generate: true.

AppSetting with secret: true stores the value as a Parameter Store SecureString. It is a free fallback for a secret of little value in a prototype. For any secret that protects a production app, use Secret.

Least privilege for deployment

The IAM user or role that deploys your CDK Blocks application needs permissions to create and manage the underlying resources (Lambda, DynamoDB, API Gateway, CloudFormation, etc.). We recommend:

  • Use a dedicated deployment role with scoped permissions.

  • Don’t deploy with your personal administrator credentials in production.

  • Use CI/CD pipelines with OIDC-based authentication (no long-lived access keys).

  • If your deployment role requires a permissions boundary on every role it creates, set defaults.permissionsBoundary. For more information, see How CDK Blocks manages permissions.