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, policies 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 System Administration → Security → SAML Configurations → 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, but it identifies your tenant, so keep it out of version control.

Step 2 — Deploy Integration Resources into AWS

Choose the deployment method that fits your workflow. All three create the same core resources: a SAML Identity Provider named britive-<tenant> and an integration role named britive-<tenant>-integration-role with IAMReadOnlyAccess and AWSOrganizationsReadOnlyAccess, plus (on by default) the session-invalidation permissions on policy/britive/managed/*.

CloudFormation

One template, britive_integration_resources.yaml, deployed four ways from the britive/onboarding repository:

Option	Use case
Single account	One account: standalone, POC, or the management account of an organization
Member accounts (StackSet)	Every account under one or more OUs, auto-deployed to accounts that join later
Whole organization	Management account and member accounts from one stack
Full lab	Demo environment with Linux, Windows and MySQL targets and sample JIT roles (~USD 50/month)

Single-account quick start. The metadata must be JSON-escaped for the CLI; generate-parameters.sh writes a parameters file with it:

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

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

For the StackSet, organization and lab options see the CloudFormation Deployment guide.

Terraform

The Terraform stacks in britive/onboarding create the same resources, with the same names, through one shared module. Three stacks are available: single-account-stack/, organization-stackset/ and full-lab-setup/. Single account is the usual starting point:

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

Set your tenant subdomain in terraform.tfvars; the flags default to the values shown:

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

tenant_name                     = "your-tenant"
deploy_aws_invalidation_feature = true
deploy_access_builder           = false
deploy_sample_roles             = false

Pass the metadata file on the command line so it never lands in a tracked file:

terraform init
terraform apply -var="saml_metadata_document_xml_content=$(cat /path/to/britive-saml-metadata.xml)"

The outputs account_id, saml_provider_name, integration_role_name and backend_connection_duration_hours are what you enter in the Britive console in the next step.

Python Automation

setup_aws.py creates the provider and the role with boto3. It reads the SAML metadata from your tenant through the Britive API, so there is nothing to download.

git clone https://github.com/britive/onboarding.git
cd onboarding/python/aws
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Set the tenant and an API token in .env, and point the AWS CLI at the target account:

python/aws/.env

BRITIVE_TENANT=your-tenant
BRITIVE_API_TOKEN=your-api-token

export AWS_PROFILE=your-aws-profile

BRITIVE_TENANT takes just the subdomain — see Finding Your Tenant Name. The API token needs the security.saml.metadata permission.

Create both resources (session invalidation is on by default):

python3 setup_aws.py --idp --role                    # provider + integration role
python3 setup_aws.py --idp --role --access-builder   # also the Access Builder permissions

Both steps are idempotent — safe to re-run if one fails partway through. The script prints the values to enter in the Britive console.

Step 3 — Register the Account in Britive

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

Get the stack outputs

If you used CloudFormation or Terraform, the values are in the outputs:

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

Add the application

In the Britive console, go to System Administration → Tenant Applications → Create Application and choose AWS Standalone for a single account, or AWS when this is the management account of an organization. Enter:

Field	CloudFormation output	Terraform output
Account ID	`AccountId`	`account_id`
Identity Provider Name	`BritiveSamlProviderName`	`saml_provider_name`
Integration Role Name (the name, not the ARN)	`BritiveIntegrationRoleName`	`integration_role_name`
Duration of backend connection (hours)	`MaxSessionDurationSeconds` ÷ 3600	`backend_connection_duration_hours`

Save and test

Click Save and Test. 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

A complete, validated example — tags, profiles, permissions and policies on an AWS application — is in terraform/britive/ of the onboarding repository. The core of it:

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
Save and Test fails	Role name or provider name mistyped, or the role is not in the management account for an AWS (organization) application	Enter the names from the outputs, not ARNs; deploy the single-account stack in the management account
`AccessDenied` on checkout	Role trust policy doesn’t allow `sts:AssumeRoleWithSAML` from the Britive provider	Use the trust policy from the sample roles: `sts:AssumeRoleWithSAML`, `sts:SetSourceIdentity`, `sts:TagSession` with `SAML:aud` pinned
Roles not visible in profile permissions	Britive hasn’t scanned the account yet	Trigger a manual scan 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)
`Invalid SAML metadata` during CloudFormation deploy	Metadata not escaped correctly, or not the full XML	Use `generate-parameters.sh`; check the source with `xmllint --noout`
Session not invalidated at checkin	Invalidation permissions not deployed	Redeploy with `DeployAwsInvalidationFeature=true` (`deploy_aws_invalidation_feature` in Terraform); they grant `iam:Policy` on `policy/britive/managed/*`

Next Steps

CloudFormation Deployment — StackSets, whole-organization and lab options in detail
Britive documentation — complete onboarding reference
britive/onboarding on GitHub — all scripts and templates

Last updated on October 8, 2026

CloudFormation Deployment