Skip to content
Serverless SaaS

Onboarding and offboarding

A system admin registers a tenant in the control plane, and the application plane provisions it automatically. The two planes only communicate through EventBridge events.

Onboarding

Section titled “Onboarding”
Onboarding a tenant
Tier Provisioning does Typical time
Basic, Standard, Premium Creates the admin user and group in the pooled user pool about 2 minutes
Platinum Downloads the latest source.zip, runs cdk deploy for a new silo stack, then creates the admin in the new pool about 8 minutes

The tenant admin gets an email from Cognito with a temporary password. The SaaS app asks for a new one at first sign-in.

Offboarding

Section titled “Offboarding”

DELETE /tenant-registrations/{id} emits offboardingRequest, and server/scripts/deprovision-tenant.sh:

  • Pooled: deletes the tenant’s users and group, and every item in shards <tenantId>-1..9 of the product and order tables.
  • Platinum: deletes the tenant’s stack, which also removes its row from the mapping table.

Then it emits deprovisionSuccess, and the registration’s status becomes Deleted.

Why a script job

Section titled “Why a script job”

SBT’s core application plane makes provisioning just a bash script running in CodeBuild, with Step Functions connecting it to EventBridge and turning the script’s exported environment variables into the outgoing event. The same mechanism creates a user for a pooled tenant or deploys a whole stack for a Platinum one.

Each job gets least-privilege IAM, not *. The Platinum branch deploys through the CDK bootstrap roles, so the job only needs sts:AssumeRole on cdk-* plus read access to the source bucket. The job runs on an ARM64 CodeBuild image because the Lambdas are ARM64 and CDK bundles them with Docker.

Watching it happen

Section titled “Watching it happen”

Every event on the bus is copied to the log group /aws/events/serverless-saas-event-bus-watcher:

sbt_aws_onboardingRequest   acme
sbt_aws_provisionSuccess    326b44d6-...
sbt_aws_offboardingRequest  acme
sbt_aws_deprovisionSuccess  326b44d6-...

Known limitation

Section titled “Known limitation”

SBT looks up GET /tenant-config/{name} by name and only marks offboarded tenants inactive. If you offboard a tenant and onboard a new one with the same name, the lookup may return either record. Use unique tenant names, or filter inactive tenants in a production control plane.