A standardized, secure way to provision and manage personal EC2 workstations using AWS SSO and AWS Systems Manager Session Manager (no inbound SSH required).
This system provides automated EC2 workstation provisioning with modern AWS security practices including SSO authentication, attribute-based access control (ABAC), and Session Manager connectivity. Perfect for teams that need secure, cost-effective cloud workstations with zero network exposure.
- SSO-first: Users authenticate with AWS IAM Identity Center (SSO) and receive short-lived credentials.
- Zero inbound: Access via Session Manager. No SSH keys, no open ports.
- ABAC: Attribute-based access control using a
usernameprincipal tag; instances are taggedOwner=<username>. - Automated: One-command scripts to create, connect to, and stop workstations.
- Cost-aware: Easy stop/terminate & (later) idle-stop automation.
- Simple sync: Trivial file sync between an EC2 directory and
s3://<bucket>/<prefix>/<username>/. - Infrastructure as code: All infrastructure defined in code (AWS CDK Python).
- Custom AMIs: Automated EC2 Image Builder pipeline for standardized workstation images.
- Local sync: User files stored in EC2 directory synchronized with corresponding MacBook directory.
flowchart LR
A["MacBook<br/>AWS CLI + SSO"] -->|aws sso login| B["IAM Identity Center<br/>(Permission Set with ABAC)"]
B -->|STS creds| C["AWS APIs<br/>(EC2, SSM)"]
C -->|Control plane| D[Session Manager]
D <-->|"Stream shell<br/>Port 443 outbound only"| E[(EC2 Workstation)]
subgraph VPC
E -.->|Optional logs| G[("CloudWatch Logs/S3")]
end
Notes
- Public subnet is acceptable without any inbound rules because SSM is outbound-only; later you can place instances in private subnets with VPC interface endpoints for
ssm,ec2messages,ssmmessages(and optionallys3,logs). - Instances require IMDSv2 and an instance profile with
AmazonSSMManagedInstanceCorepolicy attached. - SSM Agent (pre-installed on Amazon Linux 2023) establishes outbound HTTPS connection to Session Manager service.
- S3 workspace sync (not shown) provides per-user file synchronization via
s3://<bucket>/<prefix>/<username>/.
- AWS CLI installed with SSO configured
- Session Manager plugin for AWS CLI (required to connect to workstations)
- Node.js and npm installed (for AWS CDK)
- Python 3.13+ and uv installed (for CDK Python dependencies)
Install Session Manager plugin:
# Option 1: Using Homebrew (recommended)
brew install awscli # If not already installed
brew install --cask session-manager-plugin
# Option 2: Manual installation (requires admin privileges)
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"
unzip sessionmanager-bundle.zip
sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-pluginAdd both developer and administrator profiles to your AWS config:
[sso-session bcm-sso]
sso_start_url = https://d-9a6707c126.awsapps.com/start
sso_region = us-east-2
sso_registration_scopes = sso:account:access
[profile sub-dev-dev]
sso_session = bcm-sso
sso_account_id = 058264484340
sso_role_name = Submissions-Dev-Developer
region = us-east-1
[profile sub-dev-admin]
sso_session = bcm-sso
sso_account_id = 058264484340
sso_role_name = AWSAdministratorAccess
region = us-east-1Run these commands in order:
# 1. Install AWS CDK CLI globally
npm install -g aws-cdk
# 2. Login with admin profile for bootstrapping
aws sso login --profile sub-dev-admin
# 3. Create default VPC if none exists
aws ec2 create-default-vpc --profile sub-dev-admin
# 4. Bootstrap IAM resources for SSM
./infra/scripts/bootstrap-iam-for-ssm.sh sub-dev-admin us-east-1
# 5. Bootstrap CDK toolkit (optional, for future CDK deployments)
cd cdk
uv sync
uv run cdk bootstrap --profile sub-dev-adminaws sso login --profile sub-dev-dev./infra/scripts/create-workstation.sh \
--profile sub-dev-dev \
--region us-east-1 \
--project <project-name> \
--instance-type t3.small \
--arch x86_64 \
--volume-gb 50 \
--subnet-id subnet-042e2fa6a0489e19b # Use us-east-1a for better instance type supportNote: The --username parameter is optional and will be auto-detected from your current AWS SSO session if not provided.
aws ssm start-session --target <instance-id> --profile sub-dev-dev --region us-east-1./infra/scripts/stop-workstation.sh sub-dev-dev us-east-1 [username] [project]Note: The username parameter is optional and will be auto-detected from your current AWS SSO session if not provided.
Create standardized AMIs with pre-installed development tools using EC2 Image Builder:
# Create Image Builder pipeline and start first build
./infra/image-builder/scripts/create-ami.sh \
--subnet-id subnet-042e2fa6a0489e19b \
--security-group sg-060f1c9f0d0b54238 \
--profile sub-dev-admin \
--start-build
# Monitor build progress (builds take ~20-30 minutes)
aws imagebuilder list-image-builds --profile sub-dev-admin --region us-east-1 \
--query 'imageBuildVersionList[0].{Status:state.status,Reason:state.reason,Progress:state.progress}'
# List completed AMIs
aws ec2 describe-images --owners self --profile sub-dev-admin --region us-east-1 \
--filters 'Name=name,Values=AL2023-Workstation-*' \
--query 'Images[].{Name:Name,ImageId:ImageId,CreationDate:CreationDate}' \
--output tableOnce built, update your workstation creation to use the custom AMI:
# Find your latest custom AMI
CUSTOM_AMI=$(aws ec2 describe-images --owners self --profile sub-dev-admin --region us-east-1 \
--filters 'Name=name,Values=AL2023-Workstation-*' \
--query 'Images | sort_by(@, &CreationDate) | [-1].ImageId' --output text)
# Create workstation with custom AMI
./infra/scripts/create-workstation.sh \
--profile sub-dev-admin \
--region us-east-1 \
--project <project-name> \
--instance-type t3.small \
--arch x86_64 \
--volume-gb 50 \
--subnet-id subnet-042e2fa6a0489e19b \
--ami-id $CUSTOM_AMIThe Image Builder pipeline creates Amazon Linux 2023 AMIs with:
- Development tools: tmux, git, emacs-nox, wget, curl, unzip
- Node.js 20: Latest LTS with npm
- Python tooling: uv (fast Python package manager)
- AWS tools: AWS CLI v2, Session Manager plugin
- Automatic updates: Weekly builds every Sunday at 09:00 UTC
"SessionManagerPlugin is not found" Install the Session Manager plugin:
brew install --cask session-manager-plugin"No default VPC found"
aws ec2 create-default-vpc --profile sub-dev-admin"Unsupported instance type in Availability Zone"
- Specify a different subnet with
--subnet-idparameter - Try us-east-1a subnet:
subnet-042e2fa6a0489e19b - Use t3.small instead of t3.micro/t3.nano for better AZ support
"Permission denied" when running scripts
# Use bash explicitly
bash ./infra/scripts/create-workstation.sh [options]"CDK deployment fails with permission boundaries"
- Use the admin profile for initial bootstrap:
--profile sub-dev-admin - The system works without CDK deployment - IAM resources are created by bootstrap script
"Duplicate security group rule"
- This is expected on subsequent runs - the script will continue successfully
- Security groups are reused between workstation creations
us-east-1a: subnet-042e2fa6a0489e19b (recommended)
us-east-1b: subnet-0ad98f118ac401462
us-east-1c: subnet-05b62d63755840714
us-east-1d: subnet-019592a79b5036329
us-east-1e: subnet-07338f9d6c34cf90f
us-east-1f: subnet-00b31d438ae1f2a53
We suggest a dedicated directory on EC2, e.g., /home/ec2-user/workspace, synced to s3://<bucket>/<prefix>/<username>/.
- One-way upload from EC2 → S3 during/after work:
./infra/scripts/s3-sync.sh push <bucket> <prefix> [username] [path] [profile] [region]
- One-way download from S3 → EC2 at start:
./infra/scripts/s3-sync.sh pull <bucket> <prefix> [username] [path] [profile] [region]
- For convenience, use
infra/scripts/s3-sync.shas shown above. Theusername,path,profile, andregionparameters are optional with sensible defaults. - Avoid FUSE mounts (e.g., s3fs) for POSIX-heavy or latency-sensitive workloads; S3 is object storage, not a POSIX filesystem.
Note: The username will be auto-detected from your current AWS SSO session if not provided.
Example that lets signed-in principals with a username principal tag read/write only their own prefix. Replace <bucket> and <prefix>.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowUserPrefixRW",
"Effect": "Allow",
"Principal": "*",
"Action": ["s3:GetObject","s3:PutObject","s3:DeleteObject"],
"Resource": "arn:aws:s3:::<bucket>/<prefix/${aws:PrincipalTag/username}>/*",
"Condition": {"StringLike": {"aws:PrincipalTag/username": "*"}}
}
]
}Ensure IAM Identity Center maps your directory attribute to the principal tag
username(Settings → Attribute mappings). All users then get access only to/<prefix>/<username>/by default.
- Default: No inbound rules required. Session Manager uses outbound HTTPS (443) to AWS endpoints.
- If SSH is ever required: Prefer EC2 Instance Connect Endpoint or AWS Client VPN (SAML) over a public port 22. Keep this out-of-scope initially.
shared/
image-builder/
components/
workstation-dev-tools.yml
infra/
scripts/
common-utils.sh # Shared utility functions
bootstrap-iam-for-ssm.sh
create-workstation.sh
start-session.sh
stop-workstation.sh
s3-sync.sh
image-builder/
scripts/
create-ami.sh
policies/
permission-set-abac.json
permission-set-abac-explicit-deny.json
cdk/
app.py
workstation_baseline.py
image_builder.py
pyproject.toml
- Username auto-detection: Scripts automatically extract username from SSO session to ensure ABAC compliance
- Instance tagging:
Owner=<sso-username>,Project=<project>,Name=<project>-<sso-username> - ABAC security: Permission set allows run/start/stop/terminate/SSM only when
Ownermatches${aws:PrincipalTag/username} - IMDSv2 required: All instances launched with metadata service v2 enforced
- Zero inbound access: Security groups have no inbound rules, all access via Session Manager
- Idle stop: EventBridge rule + Lambda/SSM Automation to detect idle (no SSM sessions, CPU/Network low, no batch jobs) and stop. Note: A tmux session containing processes like bash, less, and vim should not be sufficient for the EC2 instance to be considered non-idle.
- Private subnets + endpoints for SSM, S3, (Logs) to remove public IPs entirely.
- Session logs to CloudWatch/S3.
- MacBook sync: Direct synchronization between MacBook and EC2 workspace directories (beyond S3 sync).
Q: Why not just SSH?
A: SSM removes inbound exposure, centralizes audit, and avoids key management.
Q: Why not s3fs?
A: S3 is object storage; POSIX semantics are partial and latency can bite. aws s3 sync is predictable and robust for content-based workflows.
Q: Which IaC should we use?
A: Since we are AWS-only and Python-strong, use AWS CDK (Python) to define shared infra (SSM logging, VPC endpoints, buckets, KMS). Keep per-user workstation lifecycle as CLI scripts.