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
-
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 |
|---|---|---|
|
|
|
The table, and |
|
|
|
The bucket and its objects |
|
|
|
The cluster, the app’s database role on an |
|
|
|
The secret |
|
|
|
The parameter. KMS access is limited to calls made through Parameter Store, or to your key if you set |
|
|
|
All Amazon Simple Email Service (Amazon SES) identities and configuration sets in the account |
|
|
|
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 synthwrites a report of the execution role tocdk.out/<stackName>.blocks-iam.json, orcdk.out/<stackName>.<backendId>.blocks-iam.jsonfor aBlocksBackendinside 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, wherestackis the stack thatBlocksStack.create(…)returns (blocksStackin the project templates). Pass the resource’s name or ARN to your code withregisterConfig. Every compute reads it fromprocess.envat 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.permissionsBoundaryto 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 thatHostingcreates. 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 aniam.IManagedPolicy.The examples on this page keep the template’s preset choice,
sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production, and add settings to it. If you spreadBlocksPresets.productionalone, sandboxes also get production settings, such as nolocalhostCORS 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
emailoption. 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
ApiNamespacemethod is a public endpoint until it callsrequireAuth. The local implementation applies no authentication, so a method that you forget to protect passes every local check. Callauth.requireAuth(context)server-side in every API method that accesses user data. Never trust client-side authentication alone. -
Scope data access by
user.userSubto 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 anyAuthBlock 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 keyaws/dynamodb. Setencryption: 'customer-managed'to create a customer managed key for the table, or setencryption: KVStore.fromKmsKey(keyArn)to use a key that you already own. -
FileBucket: S3 server-side encryption with Amazon S3 managed keys (SSE-S3). The sameencryptionoption selects a KMS key instead.FileBucketalso blocks all public access and rejects requests that do not use TLS. For records that must not change, setobjectLock: { mode, retentionDays }. To log requests to a bucket, setaccessLogging: trueon the bucket, ordefaults.storageAccessLogging: truefor every bucket in the stack. -
Database: Aurora DSQL encryption with an AWS owned key on adsqlcluster. Anauroracluster 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 theaws/secretsmanagerkey.AppSettingwithsecret: true: Parameter Store SecureString with theaws/ssmkey, or your key if you setkmsKeyArn.
-
- 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 ofSecretand secretAppSettingBlocks. 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
RealtimeWebSocket stage. For more information, see API protection.- Front door
-
The
apiFrontDooroption onBlocksStack.createorBlocksBackend.createsets 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 callpublicApiUrl, which is also theApiUrlstack output. When you pass the backend toHosting, the browser reaches the API on the same origin through the hosting front door, except withfrontDoor: 'none', where it calls the API cross-origin. Neither option makes CloudFront the only way in: the API Gatewayexecute-apiURL 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 passapiWaf: { webAclArn }to attach a web ACL that you already have. UnderapiFrontDoor: 'cloudfront', the web ACL must be inus-east-1, so outside that Region passwebAclArn.apiWafdoes not cover theRealtimeWebSocket API. Browser traffic that arrives throughHostingis not rate limited byapiWaf; turn on the WAF of the hosting front door for that. WhenHosting’s CloudFront distribution serves the API under `apiFrontDoor: 'cloudfront',apiWafcreates no web ACL at all, andcdk synthwarns about it. - Access logs
-
API Gateway access logging is off in both presets, and
cdk synthwarns about this for the production preset. Turn it on withdefaults.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 everyFileBucket, each with its own log bucket. To keep those off, also setdefaults.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 plainErrorthrown 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 innew ApiError(message, 404, { name: 'NotFoundError' }), and check it withisBlocksErrorfromaws-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
RealtimeWebSocket stage fromdefaults.throttling. The API Gateway front doors thatHostingcreates 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, overridethrottling, as shown in the following example. For a limit on each client, use the rate rule inapiWaf. - CORS
-
Your API accepts cross-origin requests only from the origins in
defaults.allowedOrigins, plus the hosting front door’s origin when you useHosting. Each entry inallowedOriginsis a regular expression, so escape the dots. The production preset lists no origins. The sandbox preset allowslocalhostand127.0.0.1, so a local frontend can call a deployed sandbox. WithHosting, 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.