AWS Identity Federation Token Generation and Resource Retrieval

Guide to generating temporary security credentials and configuring the Cloud Builder role for AWS, GCP, and Azure.

AWS Identity Federation Token Generation and Resource Retrieval

This document outlines the process of generating temporary security credentials using AWS CLI to assume an IAM role in a specified AWS account, using the credentials to retrieve EC2 instances, and configuring the Cloud Builder role for organization-wide scanning in AWS, GCP, and Azure. The process was completed on June 23, 2025, at 07:42 PM IST, with updates for the Cloud Builder role and simplified credential generation added on July 1, 2025.

Purpose

To enable secure access to AWS resources using IAM role assumption and to configure the Cloud Builder role to collect audit logs, cost data, and resource information across AWS, GCP, and Azure at the account, organization, or resource level.

Scope

This document covers:

• Generating temporary security credentials in AWS using IAM role assumption to access EC2 instances.
• Creating and assigning the Cloud Builder role in AWS, GCP, and Azure for Steampipe scanning, with options to scope permissions to account, organization, or resource levels.
• Applicable to users managing cloud resources in a single AWS account or across an AWS organization.

Assumptions

• The user has administrative access to the AWS account, Google Cloud project, and Azure subscription.
• The aws, gcloud, and az CLIs are installed and authenticated with sufficient permissions.
• The user has basic knowledge of IAM roles and cloud resource management.
• An IAM role with appropriate permissions is available for assumption.

Best Practices for Identity Federation

• Use Short-Lived Credentials: Generate temporary credentials with a short duration (e.g., 1 hour) to minimize security risks.
• Least Privilege: Assign only the necessary permissions to the IAM role to reduce the attack surface.
• Secure Role Access: Restrict access to IAM roles used for assumption.
• Audit and Monitor: Regularly audit IAM policies and monitor credential usage to detect unauthorized access.
• Scope Permissions Appropriately: Assign the Cloud Builder role at the organization level for broad scanning, or at the account/resource level for granular control.
• Use Managed Authentication: Prefer aws sts commands for credential generation to simplify the process and reduce manual key management.

Prerequisites

• AWS CLI installed and authenticated with a user or role with sufficient permissions (e.g., IAMFullAccess, EC2FullAccess).
• gcloud CLI installed and authenticated for GCP operations.
• az CLI installed and authenticated for Azure operations.
• AWS Account: your-aws-account-id.
• Google Cloud Project: your-project-name (Project Number: your-project-number).
• Azure Subscription: your-azure-subscription-id.
• IAM Role: your-iam-role.

Step-by-Step Guide to Temporary Credential Creation

The following steps outline the process to generate temporary security credentials via IAM role assumption, use them to access AWS resources, and configure the Cloud Builder role.

Step 1: Create an IAM Role for Assumption

Create a new IAM role (your-iam-role) that can be assumed by an authenticated user or role.

1.1 Create the IAM Role

aws iam create-role --role-name your-iam-role \
  --assume-role-policy-document file://assume-role-trust-policy.json \
  --region your-region

assume-role-trust-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::your-aws-account-id:user/your-iam-user"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

1.2 Attach a Policy for EC2 Access

aws iam attach-role-policy --role-name your-iam-role \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess \
  --region your-region

Outcome:

• IAM role created and granted read-only access to EC2.

Step 2: Create and Assign Cloud Builder Roles

The Cloud Builder role provides read-only access to collect cost, audit, and resource data. Below are instructions for creating and assigning this role in AWS, GCP, and Azure, with options to scope permissions to account, organization, or resource levels.

2.1 AWS: Create and Assign the Cloud Builder Role

Create the IAM Role

aws iam create-role --role-name CloudBuilder \
  --assume-role-policy-document file://cloud-builder-trust-policy.json \
  --region your-region

cloud-builder-trust-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::your-aws-account-id:user/your-iam-user"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Create and Attach the Policy

aws iam create-policy --policy-name CloudBuilderPolicy \
  --policy-document file://cloud-builder-policy.json \
  --region your-region
aws iam attach-role-policy --role-name CloudBuilder \
  --policy-arn "arn:aws:iam::your-aws-account-id:policy/CloudBuilderPolicy" \
  --region your-region

cloud-builder-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "iam:ListRoles",
        "iam:ListPolicies",
        "ce:GetCostAndUsage",
        "ce:GetCostForecast",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetEventSelectors",
        "compute-optimizer:GetEC2InstanceRecommendations",
        "compute-optimizer:GetEBSVolumeRecommendations"
      ],
      "Resource": "*"
    }
  ]
}

Assign the Role to a Service

• The Cloud Builder role can be assumed by the Steampipe service or user for scanning:
  aws sts assume-role --role-arn "arn:aws:iam::your-aws-account-id:role/CloudBuilder" \
    --role-session-name "SteampipeSession" \
    --region your-region
  

Outcome:

• The Cloud Builder role is created in AWS with permissions equivalent to those in GCP and Azure, assigned to the Steampipe service via role assumption.

2.2 GCP: Create and Assign the Cloud Builder Role

Create the Custom Role

gcloud iam roles create CloudBuilder \
  --project=your-project-name \
  --title "Cloud Builder" \
  --description "Precise permissions for Cloud Builder to collect audit logs, cost data, and project information" \
  --stage GA \
  --permissions resourcemanager.projects.list,resourcemanager.projects.get,resourcemanager.organizations.get,logging.logEntries.list,logging.logs.list,billing.accounts.get,billing.accounts.list,recommender.computeInstanceGroupManagerMachineTypeRecommendations.list,recommender.computeInstanceMachineTypeRecommendations.list,recommender.computeDiskIdleResourceRecommendations.list

Assign the Role

• Organization Level:
  gcloud organizations add-iam-policy-binding your-organization-id \
    --member "serviceAccount:[e-mail]" \
    --role "projects/your-project-name/roles/CloudBuilder"
  
• Folder Level:
  gcloud resource-manager folders add-iam-policy-binding your-folder-id \
    --member "serviceAccount:[e-mail]" \
    --role "projects/your-project-name/roles/CloudBuilder"
  
• Project Level:
  gcloud projects add-iam-policy-binding your-project-name \
    --member "serviceAccount:[e-mail]" \
    --role "projects/your-project-name/roles/CloudBuilder"
  

Outcome:

• The Cloud Builder role is created in GCP and assigned to the service account [e-mail] at the desired scope.

2.3 Azure: Create and Assign the Cloud Builder Role

Create the Custom Role

az role definition create --role-definition cloud-builder-role.json

cloud-builder-role.json:

{
  "Name": "CloudBuilder",
  "Description": "Precise permissions for Cloud Builder to collect audit logs, cost data, and resource information",
  "IsCustom": true,
  "Actions": [
    "Microsoft.Compute/virtualMachines/read",
    "Microsoft.Resources/subscriptions/read",
    "Microsoft.Authorization/roleAssignments/read",
    "Microsoft.Authorization/roleDefinitions/read",
    "Microsoft.CostManagement/query/read",
    "Microsoft.CostManagement/forecast/read",
    "Microsoft.Security/auditLogs/read",
    "Microsoft.Insights/activityLogs/read",
    "Microsoft.Compute/recommendations/read"
  ],
  "AssignableScopes": [
    "/subscriptions/your-azure-subscription-id",
    "/providers/Microsoft.Management/managementGroups/your-management-group-id"
  ]
}

Assign the Role

• Subscription Level:
  az role assignment create --assignee "[e-mail]" \
    --role "CloudBuilder" \
    --scope "/subscriptions/your-azure-subscription-id"
  
• Management Group Level:
  az role assignment create --assignee "[e-mail]" \
    --role "CloudBuilder" \
    --scope "/providers/Microsoft.Management/managementGroups/your-management-group-id"
  
• Resource Group Level:
  az role assignment create --assignee "[e-mail]" \
    --role "CloudBuilder" \
    --scope "/subscriptions/your-azure-subscription-id/resourceGroups/your-resource-group"
  

Outcome:

• The Cloud Builder role is created in Azure and assigned to the service principal [e-mail] at the desired scope.

Step 3: Generate Temporary Security Credentials

Use aws sts assume-role to generate temporary credentials by assuming the IAM role.

3.1 Authenticate with AWS CLI

Ensure the AWS CLI is configured with a user or role that has permission to assume your-iam-role:

aws configure

3.2 Assume the IAM Role

aws sts assume-role --role-arn "arn:aws:iam::your-aws-account-id:role/your-iam-role" \
  --role-session-name "YourSessionName" \
  --region your-region

Outcome:

• Received temporary credentials, e.g.:
  {
    "Credentials": {
      "AccessKeyId": "ASIAEXAMPLE",
      "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "SessionToken": "IQoJb3JpZ2luX2...",
      "Expiration": "2025-07-01T23:00:00Z"
    }
  }
  
• Extract the AccessKeyId, SecretAccessKey, and SessionToken for use as YOUR_ACCESS_KEY_ID, YOUR_SECRET_ACCESS_KEY, and YOUR_SESSION_TOKEN.

Summary

• IAM Role: your-iam-role
• Cloud Builder Role: CloudBuilder
• Temporary Credentials: ASIAEXAMPLE, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, IQoJb3JpZ2luX2...
• Resource Retrieved: EC2 instances in your-region.
• Cloud Builder Role: Created and assigned in AWS, GCP, and Azure for Steampipe scanning, with permissions scoped to organization, account/project, or resource group levels as needed.

This process demonstrates how to generate temporary security credentials via IAM role assumption, access AWS resources, and configure the Cloud Builder role across AWS, GCP, and Azure for comprehensive cloud scanning.