Authenticating

Rather than distributing static API keys or long-lived passwords that have to be stored and rotated, Bifrost uses role-based access control built on AWS IAM roles.

Every interaction with Bifrost is authenticated by assuming one of your business unit's IAM roles, following the owner, editor, and viewer model (see Permission Levels and Accounts). Once your CLI profile or SDK session is configured to assume that role, AWS handles temporary credentials automatically behind the scenes, whether you are consuming a telemetry stream or calling the HTTP APIs.

Assuming a role from an AWS account

The consumer AWS account you provided during Pre-flight is trusted by Bifrost. When your application or user runs inside that account, you can obtain temporary role credentials in one of two ways:

• Using an AWS config profile: Best for local development and CLI usage, where credentials are resolved from ~/.aws/config.
• At runtime in application code: Best for deployed services (such as ECS tasks, EKS pods, or Lambda functions) where no local config file exists.

info

The examples below target the production account (121573399545; see Accounts for other environments). Replace {businessUnitKey} with the key from Pre-flight.

Using an AWS config profile

In Carrier's AWS Control Tower environment, you authenticate to your consumer AWS account through AWS IAM Identity Center (SSO). Before configuring the Bifrost role, make sure your base profile (for example, default) is set up with Carrier SSO (aws configure sso) and has an active session (aws sso login).

Then configure a bifrost profile in ~/.aws/config that uses your SSO profile as its source_profile and targets the Bifrost role_arn:

# Assumes your "default" profile is connected to Carrier AWS Control Tower
# with SSO configured and logged in
aws configure set profile.bifrost.role_arn "arn:aws:iam::121573399545:role/bifrost-prod-viewer-{businessUnitKey}-role"
aws configure set profile.bifrost.source_profile default
aws configure set profile.bifrost.region eu-west-1

Once saved, you can pass --profile bifrost (or initialize an SDK session with that profile) to interact with any AWS service your role has access to, such as Kinesis. The examples below use STS (get-caller-identity) as a simple way to verify that the profile is assuming the role as expected:

AWS CLI

# Pass --profile bifrost to any AWS CLI command (e.g., aws kinesis, aws sts)
aws sts get-caller-identity --profile bifrost
# Expected Arn:
# "arn:aws:sts::121573399545:assumed-role/bifrost-prod-viewer-{businessUnitKey}-role/..."

Python

import boto3

session = boto3.Session(profile_name="bifrost", region_name="eu-west-1")
credentials = session.get_credentials()

# Use session.client("<service>") for any AWS service (e.g., "kinesis", "sts")
sts = session.client("sts")
print(sts.get_caller_identity()["Arn"])
# Expected Arn:
# "arn:aws:sts::121573399545:assumed-role/bifrost-prod-viewer-{businessUnitKey}-role/..."

TypeScript

import { GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
import { fromIni } from "@aws-sdk/credential-providers";

const credentials = fromIni({ profile: "bifrost" });

// Pass credentials to any AWS SDK client (e.g., KinesisClient, STSClient)
const sts = new STSClient({ region: "eu-west-1", credentials });
const identity = await sts.send(new GetCallerIdentityCommand({}));
console.log(identity.Arn);
// Expected Arn:
// "arn:aws:sts::121573399545:assumed-role/bifrost-prod-viewer-{businessUnitKey}-role/..."

At runtime in application code

For deployed services where you do not manage a local ~/.aws/config file, resolve and auto-refresh the assumed role's credentials at runtime by passing the Bifrost role ARN directly in code. Just like the profile approach, the resulting session or credentials object works with any AWS service client (shown below with sts to verify the active role):

AWS CLI

export $(printf "AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s" \
  $(aws sts assume-role \
    --role-arn "arn:aws:iam::121573399545:role/bifrost-prod-viewer-{businessUnitKey}-role" \
    --role-session-name "{businessUnitKey}-session" \
    --query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]" \
    --output text))

# Any subsequent AWS CLI command now runs as the assumed Bifrost role
aws sts get-caller-identity
# Expected Arn:
# "arn:aws:sts::121573399545:assumed-role/bifrost-prod-viewer-{businessUnitKey}-role/{businessUnitKey}-session"

Python

import boto3
from botocore.credentials import DeferredRefreshableCredentials, create_assume_role_refresher

session = boto3.Session(region_name="eu-west-1")
session._session._credentials = DeferredRefreshableCredentials(
    refresh_using=create_assume_role_refresher(
        session.client("sts"),
        {
            "RoleArn": "arn:aws:iam::121573399545:role/bifrost-prod-viewer-{businessUnitKey}-role",
            "RoleSessionName": "{businessUnitKey}-session",
        },
    ),
    method="sts-assume-role",
)
credentials = session.get_credentials()

# Use session.client("<service>") for any AWS service (e.g., "kinesis", "sts")
sts = session.client("sts")
print(sts.get_caller_identity()["Arn"])
# Expected Arn:
# "arn:aws:sts::121573399545:assumed-role/bifrost-prod-viewer-{businessUnitKey}-role/{businessUnitKey}-session"

TypeScript

import { GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers";

const credentials = fromTemporaryCredentials({
    clientConfig: { region: "eu-west-1" },
    params: {
        RoleArn: "arn:aws:iam::121573399545:role/bifrost-prod-viewer-{businessUnitKey}-role",
        RoleSessionName: "{businessUnitKey}-session",
    },
});

// Pass credentials to any AWS SDK client (e.g., KinesisClient, STSClient)
const sts = new STSClient({ region: "eu-west-1", credentials });
const identity = await sts.send(new GetCallerIdentityCommand({}));
console.log(identity.Arn);
// Expected Arn:
// "arn:aws:sts::121573399545:assumed-role/bifrost-prod-viewer-{businessUnitKey}-role/{businessUnitKey}-session"

Once verified, pass session or credentials to any AWS SDK client allowed by your permission level (such as consuming the telemetry stream), or pass credentials to your HTTP request signer (see Making API Requests).

Assuming a role without an AWS account

📝 This page is not complete yet. Important details are missing.

Common errors

When assuming a role fails, AWS returns an error code describing which check did not pass:

• AccessDenied (User is not authorized to perform: sts:AssumeRole on resource): This typically happens for one of two reasons:
  1. Your caller is running in an AWS account other than the consumer account registered during onboarding.
  2. The target role ARN contains a typo in the account ID, {businessUnitKey}, or the permission level.
• ExpiredTokenException: Exported temporary session credentials have passed their expiration time and need to be refreshed.

Further reading

• IAM Roles
• Assume an IAM role in the AWS CLI
• Switching to an IAM role (AWS API)
• Boto3 Credentials
• @aws-sdk/credential-providers