Authenticate from AWS with Workload Federation

Overview

Every PyBritive command you have run so far authenticated as you, after pybritive login. Automation cannot log in interactively, and storing a BRITIVE_API_TOKEN on a server recreates the long-lived secret Britive exists to remove.

The --federation-provider aws flag solves this. PyBritive proves the workload’s AWS identity to Britive by signing an STS request with the instance’s own IAM role. Britive maps that identity to a service identity and issues a short-lived token for the call. Nothing is stored.

What you’ll learn:

How AWS workload federation works in PyBritive
How to configure Britive to trust an IAM role
How to run pybritive on an EC2 instance with no token
How the aws and aws-<profile> forms differ

Before You Begin

Britive tenant administrator access
An AWS account where you can launch an EC2 instance with an IAM role
PyBritive and boto3 installed on that instance — pip install pybritive boto3
Your tenant name — see Finding Your Tenant Name

How It Works

    sequenceDiagram
    autonumber
    participant W as Workload (EC2)
    participant P as pybritive
    participant B as Britive
    participant S as AWS STS
    W->>P: pybritive ls secrets -P aws
    P->>P: boto3 credentials from the instance role
    P->>P: SigV4-sign sts:GetCallerIdentity (tenant name bound in)
    P->>B: present the signed request as a workload token
    B->>S: validate signature
    S-->>B: arn:aws:sts::123456789012:assumed-role/my-role/i-0abc
    B->>B: AWS Workload Identity Provider maps ARN → service identity
    B-->>P: short-lived Britive token
    P->>B: ls secrets
    B-->>W: JSON

The signed request is only valid for a short validation window and only for your tenant, so it cannot be replayed elsewhere.

The same flag works for other platforms: -P github, -P gitlab, -P bitbucket, -P gcp, -P azuresmi, -P spacelift. Only the identity source changes; the Britive side is an OIDC identity provider instead of AWS.

Configure Britive

Create a custom identity attribute

Navigate to Admin → Identity Management → Identity Attributes → Add. Name it aws_role_arn, type String. Britive will compare the workload’s ARN against this attribute.

Add an AWS workload identity provider

Navigate to Admin → Identity Management → Workload → Identity Providers → Add. Choose type AWS, name it aws-prod. Under attribute mapping, map the token attribute arn to aws_role_arn. Keep the default validation window.

Create a service identity

Navigate to Admin → Identity Management → Service Identities → Add. Name it svc-ec2-app.

Federate the service identity

Open svc-ec2-app → Federation. Select aws-prod and set aws_role_arn to the assumed-role ARN of your instance role:

arn:aws:sts::123456789012:assumed-role/my-instance-role/*

Use the arn:aws:sts::…:assumed-role/… form, not arn:aws:iam::…:role/…. GetCallerIdentity returns the assumed-role ARN, and that is what Britive compares.

Grant access

Add svc-ec2-app as a member of the policy on whatever it should reach — a vault folder, an access profile, or both. Federation only proves who; policies still decide what.

Run PyBritive on the Instance

Set the tenant

The tenant name is part of the signed payload, so it must be set:

export BRITIVE_TENANT=your-tenant

Confirm the identity

pybritive user --federation-provider aws

Expected output names svc-ec2-app. If it does not, compare aws sts get-caller-identity with the ARN you entered in the federation mapping.

Use it like any other identity

pybritive ls secrets --federation-provider aws --format json
pybritive checkout "AWS Production/123456789012 (prod)/ReadOnly" --federation-provider aws --mode env

No pybritive login, no BRITIVE_API_TOKEN.

Choose between `aws` and `aws-<profile>`

Form	Credentials from	Use when
`-P aws`	the default boto3 chain — on EC2, the instance role	Plain EC2, ECS task role, Lambda execution role
`-P aws-instance`	the AWS profile named `instance` in `~/.aws/config`	You keep several profiles and want to be explicit

To make aws-instance resolve to the instance role:

~/.aws/config

[profile instance]
credential_source = Ec2InstanceMetadata

Verify

env | grep -c BRITIVE_API_TOKEN
pybritive user --federation-provider aws

Expected output:

0
Username: svc-ec2-app
Type: ServiceIdentity
...

The first line confirms no token is present. The second confirms Britive recognised the instance.

Troubleshoot

Symptom	Cause	Fix
`boto3 required - please install boto3 package`	pybritive’s Python interpreter lacks boto3	`pip install boto3` with the same `pip` that installed pybritive
`the aws federation provider requires the britive tenant`	`BRITIVE_TENANT` unset	Export it; the tenant name is part of the signature
`401` or `invalid token`	Federation mapping does not match the ARN	Run `aws sts get-caller-identity` and copy the `Arn`, replacing the session name with `*`
Works as root, fails as another user	That user’s boto3 chain finds different credentials	Check `~/.aws/` for that user; prefer `-P aws` with no local config
Works locally, fails in a container	IMDS hop limit blocks the container	Set `HttpPutResponseHopLimit` to 2, or use an ECS task role

Next Steps

Scripting PyBritive — JSON output, silent mode, and the api command for programs that call PyBritive
Puppet integration — secrets and profiles as facts, built on this flow
Zero-Secret Workloads — the model behind every federated integration

Last updated on September 24, 2026

Approval Workflows Scripting PyBritive