CloudFormation Deployment

Overview

The Britive onboarding repository ships one CloudFormation template, britive_integration_resources.yaml, and four ways to deploy it:

All of it is in cloudformation/aws/, with a generate-parameters.sh helper and a sample Service Control Policy.

What the Template Creates

MaxSessionDuration (default 3600 seconds) is what you enter, in hours, as Duration of backend connection in the Britive application.

Before You Begin

• A Britive tenant with administrator access
• AWS credentials that can create IAM roles, policies and SAML providers in the target account; the StackSet options also need the management account (or a StackSets delegated administrator) with trusted access enabled
• AWS CLI v2 installed and configured

Step 1 — Download the SAML Metadata and Generate the Parameters

git clone https://github.com/britive/onboarding.git
cd onboarding/cloudformation/aws

./generate-parameters.sh your-tenant /path/to/britive-saml-metadata.xml
# writes ./parameters.json (gitignored)

Option 1 — Single Account

Directory: cloudformation/aws/single-account-stack/

The quickest path to connecting one account. Also what the management account of an organization needs, because service-managed StackSets never deploy there.

aws cloudformation deploy \
  --stack-name britive-integration \
  --template-file britive_integration_resources.yaml \
  --parameter-overrides file://parameters.json \
  --capabilities CAPABILITY_NAMED_IAM

aws cloudformation describe-stacks --stack-name britive-integration \
  --query 'Stacks[0].Outputs' --output table

Parameters:

Outputs: AccountId, BritiveSamlProviderName, BritiveIntegrationRoleName, MaxSessionDurationSeconds — the values for Step 2.

Option 2 — Member Accounts with a StackSet

Directory: cloudformation/aws/stackset-templates/

Deploys the same template to every account under the OUs you target with a service-managed StackSet. Accounts that join those OUs later are onboarded automatically. The management account is not included — deploy Option 1 there as well, or use Option 3.

Prerequisites: credentials for the management account (or a delegated administrator, adding --call-as DELEGATED_ADMIN), AWS Organizations with all features enabled, and trusted access for StackSets:

aws organizations enable-aws-service-access \
  --service-principal member.org.stacksets.cloudformation.amazonaws.com

aws cloudformation create-stack-set \
  --stack-set-name britive-integration \
  --template-body file://britive_integration_resources.yaml \
  --parameters file://parameters.json \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false \
  --capabilities CAPABILITY_NAMED_IAM

aws cloudformation create-stack-instances \
  --stack-set-name britive-integration \
  --deployment-targets OrganizationalUnitIds=r-xxxx \
  --regions us-east-1 \
  --operation-preferences FailureToleranceCount=10,MaxConcurrentCount=10,RegionConcurrencyType=PARALLEL

IAM is global, so one region is enough. Replace r-xxxx (the root, from aws organizations list-roots) with specific OU IDs to limit scope. Watch the rollout with aws cloudformation list-stack-instances --stack-set-name britive-integration.

Option 3 — Whole Organization in One Stack

Directory: cloudformation/aws/organization-stackset/

A wrapper template, deploy_britive_integration_resources.yaml, deploys the integration template twice from the management account: as a nested stack in the management account itself, and as a service-managed StackSet to the member accounts. Both read the template from an S3 bucket in the management account, in the same region as the stack.

aws s3 cp britive_integration_resources.yaml s3://my-britive-templates/

cd organization-stackset
cp parameters.example.json parameters.json
# set S3BucketName, OrganizationalUnitIds, TenantName; paste the escaped
# SamlMetadataDocumentXmlContent value generated in Step 1

aws cloudformation deploy \
  --stack-name britive-organization \
  --template-file deploy_britive_integration_resources.yaml \
  --parameter-overrides file://parameters.json \
  --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND

Outputs: ManagementAccountId, IdentityProviderName, IntegrationRoleName, BackendConnectionDurationHours.

Option 4 — Full Lab

Directory: cloudformation/aws/full-lab-setup/

A complete environment to demonstrate Britive on AWS. For demonstrations and proofs of concept only.

Resources created:

• The integration (SAML provider, integration role, invalidation permissions) and the four sample JIT roles
• VPC 10.0.0.0/16, two public subnets, internet gateway; a security group open to AllowedIngressCidr only (0.0.0.0/0 is rejected by a template rule)
• Amazon Linux 2023 t3.micro and Windows Server 2022 t3.small instances, IMDSv2, encrypted disks, one key pair whose private key EC2 stores in Parameter Store
• RDS MySQL db.t3.micro, encrypted with a KMS key, credentials in Secrets Manager, deleted with the stack

./generate-parameters.sh your-tenant /path/to/britive-saml-metadata.xml -o /tmp/base.json
cd full-lab-setup
cp parameters.example.json parameters.json
# copy SamlMetadataDocumentXmlContent from /tmp/base.json; set TenantName and
# AllowedIngressCidr to your public IP as a /32 (curl -s https://checkip.amazonaws.com)

aws cloudformation deploy \
  --stack-name britive-lab \
  --template-file britive_lab_resources.yaml \
  --parameter-overrides file://parameters.json \
  --capabilities CAPABILITY_NAMED_IAM
# 10-15 minutes, mostly RDS

The outputs include LinuxInstancePublicIp, WindowsInstanceId, WindowsInstancePublicIp, RdsEndpoint, RdsSecretArn and KeyPairId; the directory README shows how to fetch the key from Parameter Store and reach each target.

Step 2 — Register the AWS Account in Britive

aws cloudformation describe-stacks --stack-name britive-integration \
  --query 'Stacks[0].Outputs' --output table

Protecting the Britive-Managed Paths

With session invalidation or Access Builder enabled, apply the Service Control Policy in cloudformation/aws/scp/ from the management account, so nothing but the integration role can modify policy/britive/managed/* and role/britive/managed/*.

Verify End-to-End

# After checking out an IAM role profile in Britive, set the credentials
export AWS_ACCESS_KEY_ID=<from checkout>
export AWS_SECRET_ACCESS_KEY=<from checkout>
export AWS_SESSION_TOKEN=<from checkout>

aws sts get-caller-identity
# Expected: the assumed-role ARN, e.g. arn:aws:sts::123456789012:assumed-role/Poweruser-role/britive-session

After checking in (or session expiry):

aws sts get-caller-identity
# Expected: ExpiredTokenException — session token is no longer valid

Updating and Removing

A new SAML certificate means a new metadata file: run generate-parameters.sh again and re-run the same deploy (or update-stack-set) command. aws cloudformation deploy keeps parameters you do not pass; with update-stack, pass UsePreviousValue=true for every unchanged parameter.

Remove the application from Britive before deleting a stack. Deleting also needs iam:DeleteRole, iam:DeleteRolePolicy, iam:DetachRolePolicy and iam:DeleteSAMLProvider.

Troubleshoot