Getting Started

Overview

This guide walks you through connecting an AWS account to Britive and granting your first just-in-time access session to an IAM role — no long-lived credentials, full audit trail on every checkout.

What you’ll accomplish:

Deploy a SAML Identity Provider and integration role into your AWS account
Register the account in the Britive console
Create an access profile and verify end-to-end JIT access

How It Works

Britive uses SAML 2.0 federation to assume IAM roles in your AWS account. No long-lived access keys are stored anywhere — at checkout, AWS STS issues a short-lived session token scoped to the role. At checkin (or on expiry), that token is invalidated.

User → Britive Console → SAML Assertion → AWS STS AssumeRoleWithSAML → Temporary credentials

Before You Begin

Britive tenant with administrator access
AWS account with permissions to create IAM roles and SAML identity providers (IAMFullAccess or equivalent)
AWS CLI installed and configured, or access to the AWS Management Console

Never hardcode credentials. Use environment variables, your secret manager, or the Britive Secrets Store.

Step 1 — Download the SAML Metadata

Britive acts as the SAML Identity Provider. You need to provide Britive’s metadata XML to AWS so it can trust SAML assertions from Britive.

In the Britive console, go to Settings → Identity Providers → AWS → Download SAML Metadata. Save the file — you’ll need it in the next step.

The metadata file contains Britive’s public signing certificate and entity ID. It does not contain any secrets.

Step 2 — Deploy Integration Resources into AWS

Choose the deployment method that fits your workflow. All three options create the same core resources: a SAML Identity Provider named britive-<tenant-name> and an integration IAM role with IAMReadOnlyAccess and AWSOrganizationsReadOnlyAccess.

CloudFormation

Three templates cover different deployment scopes. All are in the britive/onboarding repository.

Template	Use case
Single account	One AWS account, quickest setup
Full lab	Demo environment with EC2, RDS, sample JIT roles (~$52/month)
Organization StackSet	Entire AWS Organization, auto-deploys to new accounts

Single-account quick start:

First, format the SAML metadata as a single-line string:

SAML_METADATA=$(cat /path/to/britive-metadata.xml | tr -d '\n')

Then deploy:

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

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

For full details on all three templates — including the full lab and organization StackSet — see the CloudFormation Deployment guide.

Terraform

Terraform templates are in the britive/onboarding repository. They produce identical resources to the CloudFormation templates.

Three options are available: single-account/, full-lab/, and org-stackset/. The single-account setup is the most common starting point:

git clone https://github.com/britive/onboarding.git
cd onboarding/terraform/aws/single-account
cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars with your AWS account ID, Britive tenant name, and the path to your SAML metadata file:

terraform/aws/single-account/terraform.tfvars.example

britive_tenant_name = "your-tenant-name"
saml_metadata_file  = "/path/to/britive-metadata.xml"
enable_invalidation = true

Deploy:

terraform init
terraform apply

The IntegrationRoleARN output is what you’ll enter in the Britive console in the next step.

Python Automation

The setup_aws.py script automates each setup step independently using the Britive API and boto3. Run each flag once in order:

git clone https://github.com/britive/onboarding.git
cd onboarding
pip3 install -r requirements.txt

Set environment variables:

export AWS_ACCOUNT=123456789012
export AWS_PROFILE=your-aws-profile
export BRITIVE_TENANT=your-tenant
export BRITIVE_API_TOKEN=your-api-token

BRITIVE_TENANT takes just the subdomain — see Finding Your Tenant Name.

Run steps in sequence:

python python/aws/setup_aws.py -i   # Create the SAML IdP in AWS
python python/aws/setup_aws.py -r   # Create the integration IAM role
python python/aws/setup_aws.py -s   # Enable session invalidation
python python/aws/setup_aws.py -m   # Set up managed profiles and Access Builder

Each flag is idempotent — safe to re-run if a step fails partway through.

Step 3 — Register the Account in Britive

After deploying the integration resources, connect the AWS account to your Britive tenant.

Get the integration role ARN

If you used CloudFormation or Terraform, the ARN is in the stack outputs:

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

Add the application

In the Britive console, go to Applications → Add Application → AWS. Enter your 12-digit AWS account ID and the integration role ARN, then click Save.

Wait for the initial scan

Britive scans the account to import IAM roles and managed policies. This takes 1–3 minutes. The application status changes to Connected when the scan completes.

Create Your First Access Profile

An access profile defines which IAM roles or managed policies a group of users can check out, for how long, and under what conditions.

Using the Britive Console

Open the AWS application

Navigate to Applications → select your AWS application → Profiles → Add Profile.

Configure the profile

Field	Value
Name	A descriptive name (e.g., `DevOps-PowerUser`)
Environment	Select the AWS account
Expiration	Max session duration (e.g., `1h0m0s`)
Extendable	Enable if users may need more time

Add permissions

Under Permissions, add the IAM roles or managed policies users will receive on checkout.

Add a policy

Under Policies, click Add Policy. Assign members (users or tags) and set any approval or time-of-access conditions.

Save and activate

Click Save. The profile appears in My Access for assigned members.

Using Terraform

data "britive_application" "aws" {
  name = "AWS"
}

resource "britive_profile" "devops" {
  app_container_id    = data.britive_application.aws.id
  name                = "DevOps-PowerUser"
  expiration_duration = "1h0m0s"
  extendable          = true
  extension_duration  = "15m0s"

  associations {
    type  = "Environment"
    value = "Production Account"
  }
}

resource "britive_profile_permission" "power_user" {
  profile_id      = britive_profile.devops.id
  permission_name = "arn:aws:iam::aws:policy/PowerUserAccess"
  permission_type = "AWS Managed Policy"
}

resource "britive_profile_policy" "devops" {
  profile_id  = britive_profile.devops.id
  policy_name = "DevOps-Access-Policy"

  members = jsonencode({
    tags  = [{ name = "devops-team" }]
    users = []
  })

  access_type = "Allow"
  consumer    = "papservice"
  is_active   = true
  is_draft    = false
}

Verify

Check out the profile

Navigate to My Access → find your profile → click Check Out. Copy the temporary credentials from the checkout dialog.

Confirm identity in AWS

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 output — the assumed-role ARN confirms Britive issued valid credentials:

{
  "UserId": "AROAXXXXXXXXXXXX:britive-session",
  "Account": "123456789012",
  "Arn": "arn:aws:sts::123456789012:assumed-role/DevOps-PowerUser/britive-session"
}

Check in

Return to My Access → click Check In. Running aws sts get-caller-identity again should return ExpiredTokenException — the session is gone.

Troubleshoot

Symptom	Likely cause	Fix
Application shows “Disconnected”	Integration role ARN incorrect or trust policy missing	Verify the ARN and the trust relationship in IAM
`AccessDenied` on checkout	Role trust policy doesn’t allow `sts:AssumeRoleWithSAML`	Update the trust policy to allow the Britive SAML provider as federated principal
Roles not visible in profile permissions	Britive hasn’t scanned the account yet	Trigger a manual sync from the application page
Session expires immediately	`MaxSessionDuration` on the IAM role is too short	Increase max session duration on the IAM role (IAM → Roles → Edit)
SAML metadata invalid during CloudFormation deploy	XML contains newlines	Flatten with `tr -d '\n'` before passing as a parameter

Next Steps

CloudFormation Deployment — full lab setup, organization StackSets, and detailed CloudFormation reference
Britive documentation — complete onboarding reference
britive/onboarding on GitHub — all scripts and templates

Last updated on July 8, 2026

CloudFormation Deployment