AWS IAM

How It Works

sequenceDiagram
    participant User
    participant Hanzo KMS
    participant Resource Role as Resource Role<br/>(Your AWS Account)
    participant Target Role as Target Role<br/>(Your AWS Account)
    participant Console as AWS Console

    User->>Hanzo KMS: Request AWS Console access
    Hanzo KMS->>Resource Role: AssumeRole (with ExternalId)
    Resource Role-->>Hanzo KMS: Temporary credentials
    Hanzo KMS->>Target Role: AssumeRole (role chaining)
    Target Role-->>Hanzo KMS: Session credentials
    Hanzo KMS->>Console: Generate federation URL
    Console-->>Hanzo KMS: Signed console URL
    Hanzo KMS-->>User: Return console URL
    User->>Console: Open AWS Console (federated)

Key Concepts

Feedback
Resource Role: An IAM role in your AWS account that trusts Hanzo KMS. This is the "bridge" role that Hanzo KMS assumes first.
Feedback
Target Role: The IAM role that end users will actually use in the AWS Console. The Resource Role assumes this role on behalf of the user.
Feedback
Role Chaining: Hanzo KMS uses AWS role chaining - it first assumes the Resource Role, then uses those credentials to assume the Target Role. This provides an additional layer of security and audit capability.
Feedback
External ID: A unique identifier (your Hanzo KMS Project ID) used in the trust policy to prevent confused deputy attacks.

Session Behavior

Session Duration

Feedback
Minimum: 15 minutes (15m)
Feedback
Maximum: 1 hour (1h)

Session Tracking

Feedback
When the session was created
Feedback
Who accessed which role
Feedback
When the session expires

Important: AWS Console sessions cannot be terminated early. Once a federated URL is generated, the session remains valid until the configured duration expires. However, you can revoke active sessions by modifying the role's trust policy.

CloudTrail Integration

arn:aws:sts::123456789012:assumed-role/pam-readonly/user@example.com

Prerequisites

Feedback
Resource Role - Trusted by Hanzo KMS, can assume target roles
Feedback
Target Role(s) - The actual roles users will use in the console

No Gateway Required: Unlike database or SSH resources, AWS Console access does not require an KMS Gateway. Hanzo KMS communicates directly with AWS APIs.

Create the PAM Resource

First, create an IAM policy that allows the Resource Role to assume your target roles. For simplicity, you can use a wildcard to allow assuming any role in your account:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/*"
  }]
}

For more granular control: If you want to restrict which roles the Resource Role can assume, replace the wildcard (/*) with a more specific pattern. For example:

• arn:aws:iam::<YOUR_ACCOUNT_ID>:role/pam-* to only allow roles with the pam- prefix
• arn:aws:iam::<YOUR_ACCOUNT_ID>:role/kms-* to only allow roles with the kms- prefix

This allows you to limit the blast radius of the Resource Role's permissions.

Create an IAM role (e.g., Hanzo KMSResourceRole) with:

• The permissions policy from the previous step attached
• The following trust policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::<INFISICAL_AWS_ACCOUNT_ID>:root"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "sts:ExternalId": "<YOUR_INFISICAL_PROJECT_ID>"
      }
    }
  }]
}

Security Best Practice: Always use the External ID condition. This prevents confused deputy attacks where another Hanzo KMS customer could potentially trick Hanzo KMS into assuming your role.

Hanzo KMS AWS Account IDs:

For Dedicated Instances: Your AWS account ID differs from the ones listed above. Please contact Hanzo KMS support to obtain your dedicated AWS account ID.

For Self-Hosted Instances: Use the AWS account ID where your Hanzo KMS instance is deployed. This is the account that hosts your Hanzo KMS infrastructure and will be assuming the Resource Role.

1. Navigate to your PAM project and go to the Resources tab
2. Click Add Resource and select AWS IAM
3. Enter a name for the resource (e.g., production-aws)
4. Enter the Resource Role ARN - the ARN of the role you created in the previous step

Clicking Create Resource will validate that Hanzo KMS can assume the Resource Role. If the connection fails, verify:

• The trust policy has the correct Hanzo KMS AWS account ID
• The External ID matches your project ID
• The role ARN is correct

Create PAM Accounts

Each target role needs a trust policy that allows your Resource Role to assume it:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/Hanzo KMSResourceRole"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "sts:ExternalId": "<YOUR_INFISICAL_PROJECT_ID>"
      }
    }
  }]
}

1. Navigate to the Resources tab in your PAM project and open the AWS IAM resource you created
2. Click Add Account
3. Fill in the account details:

A friendly name for this account (e.g., readonly, admin, developer)

Optional description of what this account is used for

The ARN of the IAM role users will assume (e.g., arn:aws:iam::123456789012:role/pam-readonly)

Session duration using human-readable format (e.g., 15m, 30m, 1h). Minimum 15 minutes, maximum 1 hour.

Due to AWS role chaining limitations, the maximum session duration is 1 hour, regardless of the target role's configured maximum session duration.

Access the AWS Console

Go to the Resources tab in your PAM project and open the AWS IAM resource.

In the resource’s accounts section, find the AWS Console account you want to access.

Click the Access button for that account.

Hanzo KMS will:

1. Assume the Resource Role using your project's External ID
2. Assume the Target Role using role chaining
3. Generate a federated sign-in URL
4. Open the AWS Console in a new browser tab

The user will be signed into the AWS Console with the permissions of the Target Role.