CloudFormation Deployment

Overview

The Britive onboarding repository provides CloudFormation templates for three deployment scenarios:

Template	Purpose
Single account	Minimal setup — SAML IdP + integration role in one AWS account
Full lab	Demo environment — VPC, EC2, RDS, KMS, sample IAM roles, ~$52/month
Organization StackSet	Deploys to every account in an AWS Organization automatically

All templates are in the britive/onboarding repository.

What Every Stack Creates

Regardless of which template you use, the core resources are the same:

SAML Identity Provider — named britive-<tenant-name>, trusts the Britive SAML metadata
Integration IAM Role — named britive-<tenant-name>-integration-role, assumed by Britive to enumerate account resources
- Attached policies: IAMReadOnlyAccess, AWSOrganizationsReadOnlyAccess
- Optional: session invalidation permissions (sts:GetCallerIdentity, invalidation-specific actions)

Before You Begin

A Britive tenant with administrator access
AWS credentials with IAMFullAccess and cloudformation:* permissions
AWS CLI installed and configured (aws configure)

Step 1 — Download the SAML Metadata

Britive acts as the SAML Identity Provider. You need to supply the metadata XML to CloudFormation as a parameter.

Download the metadata file

In the Britive console, go to Settings → Identity Providers → AWS → Download SAML Metadata. Save the file locally.

Format the metadata for CloudFormation

CloudFormation requires the XML as a single-line string. Use the helper script from the repo, or run these commands manually:

# Clone the onboarding repo
git clone https://github.com/britive/onboarding.git
cd onboarding/cloudformation/aws

# Format using the helper script
bash generate-parameters.sh /path/to/britive-metadata.xml

Or manually:

# Remove newlines and escape for use as a parameter
SAML_METADATA=$(cat /path/to/britive-metadata.xml | tr -d '\n' | sed 's/"/\\"/g')
echo $SAML_METADATA

Option 1 — Single Account Stack

Full template: cloudformation/aws/single-account-stack/

Creates the SAML IdP and integration role in a single AWS account. This is the quickest path to connecting one account to Britive.

Deploy via AWS CLI:

cloudformation/aws/single-account-stack/britive_integration_resources.yaml

# Clone the templates repo if you don't have it yet, then enter the template dir
git clone https://github.com/britive/onboarding.git
cd onboarding/cloudformation/aws/single-account-stack

aws cloudformation deploy \
  --template-file britive_integration_resources.yaml \
  --stack-name britive-integration \
  --parameter-overrides \
    BritiveTenantName="your-tenant-name" \
    SAMLMetadata="$SAML_METADATA" \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-east-1

Key parameters:

Parameter	Description
`BritiveTenantName`	Your Britive tenant subdomain (e.g. `mycompany` for `mycompany.britive-app.com`)
`SAMLMetadata`	The formatted SAML metadata XML string
`EnableInvalidation`	`true` to enable session invalidation (recommended)

Stack outputs:

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

Output key	Value
`IntegrationRoleARN`	ARN of the role Britive will assume — needed for the next step
`SAMLProviderARN`	ARN of the SAML Identity Provider

Option 2 — Full Lab Setup

Full template: cloudformation/aws/full-lab-setup/

Creates a complete demo environment with sample infrastructure and JIT roles. Use this for proof-of-concept or training environments.

Resources created:

VPC (10.0.0.0/16), 2 public subnets, Internet Gateway
Amazon Linux 2 EC2 instance (t2.micro) + auto-generated key pair
Windows Server EC2 instance (t3.small)
RDS MySQL 8.0 instance (db.t3.micro) with credentials in Secrets Manager, encrypted with KMS
Four sample JIT IAM roles: EC2ReadOnly, RDSAdmin, AdminRole, TestRole
All core Britive integration resources (SAML IdP + integration role)

The full lab stack costs approximately $52/month in AWS charges (EC2, RDS, NAT Gateway). Delete the stack when it is no longer needed.

Deploy:

cloudformation/aws/full-lab-setup/britive_lab_resources.yaml

# Clone the templates repo if you don't have it yet, then enter the template dir
git clone https://github.com/britive/onboarding.git
cd onboarding/cloudformation/aws/full-lab-setup

aws cloudformation deploy \
  --template-file britive_lab_resources.yaml \
  --stack-name britive-lab \
  --parameter-overrides \
    BritiveTenantName="your-tenant-name" \
    SAMLMetadata="$SAML_METADATA" \
    EnableInvalidation="true" \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-east-1

Sample JIT role structure created by the template:

cloudformation/aws/full-lab-setup/britive_lab_resources.yaml

EC2ReadOnlyRole:
  Type: AWS::IAM::Role
  Properties:
    RoleName: !Sub "EC2ReadOnly-${BritiveTenantName}"
    AssumeRolePolicyDocument:
      Statement:
        - Effect: Allow
          Principal:
            Federated: !Ref BritiveSAMLProvider
          Action: sts:AssumeRoleWithSAML
          Condition:
            StringEquals:
              SAML:aud: "https://signin.aws.amazon.com/saml"
    ManagedPolicyArns:
      - arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess

All four sample roles use the same AssumeRolePolicyDocument pattern — the federated principal is the Britive SAML IdP and the action is sts:AssumeRoleWithSAML.

Option 3 — Organization StackSet

Full template: cloudformation/aws/stackset-templates/

Deploys the Britive integration role to every account in your AWS Organization using CloudFormation StackSets. New accounts added to the organization automatically receive the role.

Prerequisites:

AWSCloudFormationStackSetAdministrationRole exists in the management account
AWSCloudFormationStackSetExecutionRole exists in each member account (or use service-managed permissions)
AWS Organizations with all features enabled

Deploy to the entire organization:

cloudformation/aws/stackset-templates/britive_integration_resources_stackset.yaml

# Clone the templates repo if you don't have it yet, then enter the template dir
git clone https://github.com/britive/onboarding.git
cd onboarding/cloudformation/aws/stackset-templates

aws cloudformation create-stack-set \
  --stack-set-name britive-org-integration \
  --template-body file://britive_integration_resources_stackset.yaml \
  --parameters \
    ParameterKey=BritiveTenantName,ParameterValue="your-tenant-name" \
    ParameterKey=SAMLMetadata,ParameterValue="$SAML_METADATA" \
  --capabilities CAPABILITY_NAMED_IAM \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false

# Deploy to all accounts in the root OU
aws cloudformation create-stack-instances \
  --stack-set-name britive-org-integration \
  --deployment-targets OrganizationalUnitIds=r-xxxx \
  --regions us-east-1

With AutoDeployment enabled and SERVICE_MANAGED permission model, the integration role is automatically deployed to new accounts as they are created or moved into the target OU — no manual intervention needed.

Step 2 — Register the AWS Account in Britive

After the stack deploys, register the account in the Britive console.

Get the stack outputs

aws cloudformation describe-stacks \
  --stack-name britive-integration \
  --query 'Stacks[0].Outputs[?OutputKey==`IntegrationRoleARN`].OutputValue' \
  --output text

Add the AWS application

In the Britive console, go to Applications → Add Application → AWS.

Enter:

Field	Value
Account ID	Your 12-digit AWS account ID
Integration Role ARN	The `IntegrationRoleARN` from the stack output

Run the initial scan

After saving, Britive scans the account to enumerate IAM roles and policies. This takes 1–3 minutes.

Verify

Go to Applications → AWS → Environments and confirm your account appears with a green status indicator.

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>

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

After checking in (or session expiry):

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

Troubleshoot

Symptom	Cause	Fix
`SAML metadata is invalid` during stack deploy	XML contains newlines or unescaped quotes	Re-run `generate-parameters.sh` or use the `tr`/`sed` one-liner to flatten the XML
`ROLLBACK_COMPLETE` — role already exists	A previous stack created a role with the same name	Delete the old stack first: `aws cloudformation delete-stack --stack-name <name>`
Britive scan fails after registration	Integration role not trusted by the correct Britive SAML IdP	Confirm the `Principal.Federated` in the role trust policy matches the `SAMLProviderARN` output
StackSet instances stuck in `RUNNING`	Execution role missing in member accounts	Ensure `AWSCloudFormationStackSetExecutionRole` exists in each target account
Session not invalidated at checkin	`EnableInvalidation=false` or invalidation role missing	Redeploy with `EnableInvalidation=true`; the template adds the required STS permissions

Last updated on July 8, 2026

Getting Started