kms/docs/documentation/platform/pam/getting-started/resources/aws-iam.mdx

---
title: "AWS IAM"
sidebarTitle: "AWS IAM"
description: "Learn how to configure AWS Management Console access through KMS PAM for secure, audited, and just-in-time access to AWS."
---

KMS PAM supports secure, just-in-time access to the **AWS Management Console** through federated sign-in. This allows your team to access AWS without sharing long-lived credentials, while maintaining a complete audit trail of who accessed what and when.

## How It Works

Unlike database or SSH resources that require a Gateway for network connectivity, AWS Console access works differently. KMS uses AWS STS (Security Token Service) to assume roles on your behalf and generates temporary federated sign-in URLs.

```mermaid
sequenceDiagram
    participant User
    participant 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->>KMS: Request AWS Console access
    KMS->>Resource Role: AssumeRole (with ExternalId)
    Resource Role-->>KMS: Temporary credentials
    KMS->>Target Role: AssumeRole (role chaining)
    Target Role-->>KMS: Session credentials
    KMS->>Console: Generate federation URL
    Console-->>KMS: Signed console URL
    KMS-->>User: Return console URL
    User->>Console: Open AWS Console (federated)
```

### Key Concepts

1. **Resource Role**: An IAM role in your AWS account that trusts KMS. This is the "bridge" role that KMS assumes first.

2. **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.

3. **Role Chaining**: 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.

4. **External ID**: A unique identifier (your KMS Project ID) used in the trust policy to prevent [confused deputy attacks](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).

## Session Behavior

### Session Duration

The session duration is set when creating the account and applies to all access requests. You can specify the duration using human-readable formats like `15m`, `30m`, or `1h`. Due to AWS role chaining limitations:

- **Minimum**: 15 minutes (`15m`)
- **Maximum**: 1 hour (`1h`)

### Session Tracking

KMS tracks:
- When the session was created
- Who accessed which role
- When the session expires

<Info>
  **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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html) by modifying the role's trust policy.
</Info>

### CloudTrail Integration

All actions performed in the AWS Console are logged in [AWS CloudTrail](https://console.aws.amazon.com/cloudtrail). The session is identified by the `RoleSessionName`, which includes the user's email address for attribution:

```
arn:aws:sts::123456789012:assumed-role/pam-readonly/[email protected]
```

This allows you to correlate KMS PAM sessions with CloudTrail logs for complete audit visibility.

## Prerequisites

Before configuring AWS Console access in KMS PAM, you need to set up two IAM roles in your AWS account:

1. **Resource Role** - Trusted by KMS, can assume target roles
2. **Target Role(s)** - The actual roles users will use in the console

<Info>
  **No Gateway Required**: Unlike database or SSH resources, AWS Console access does not require an KMS Gateway. KMS communicates directly with AWS APIs.
</Info>

## Create the PAM Resource

The PAM Resource represents the connection between KMS and your AWS account. It contains the Resource Role that KMS will assume.

<Steps>
  <Step title="Create the Resource Role Permissions Policy">
    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:

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

    ![Create AWS IAM Resource](/images/pam/resources/aws-iam/resource-role-policy.png)

    <Note>
      **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.
    </Note>
  </Step>

  <Step title="Create the Resource Role with Trust Policy">
    Create an IAM role (e.g., `KMSResourceRole`) with:
    - The permissions policy from the previous step attached
    - The following trust policy:

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

    ![Create AWS IAM Resource](/images/pam/resources/aws-iam/resource-role-trust-policy.png)

    ![Create AWS IAM Resource](/images/pam/resources/aws-iam/resource-role-attach-policy.png)

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

    **KMS AWS Account IDs:**
    | Region | Account ID |
    |--------|------------|
    | US | `381492033652` |
    | EU | `345594589636` |

    <Note>
      **For Dedicated Instances**: Your AWS account ID differs from the ones listed above. Please contact KMS support to obtain your dedicated AWS account ID.
    </Note>

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

  <Step title="Create the Resource in KMS">
    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

    ![Create AWS IAM Resource](/images/pam/resources/aws-iam/create-resource.png)

    Clicking **Create Resource** will validate that KMS can assume the Resource Role. If the connection fails, verify:
    - The trust policy has the correct KMS AWS account ID
    - The External ID matches your project ID
    - The role ARN is correct
  </Step>
</Steps>

## Create PAM Accounts

A PAM Account represents a specific Target Role that users can request access to. You can create multiple accounts per resource, each pointing to a different target role with different permission levels.

<Steps>
  <Step title="Create the Target Role Trust Policy">
    Each target role needs a trust policy that allows your Resource Role to assume it:

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

    ![Create AWS IAM Resource](/images/pam/resources/aws-iam/target-role-trust-policy.png)
  </Step>

  <Step title="Create the Account in KMS">
    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:

    ![Create AWS IAM Account](/images/pam/resources/aws-iam/create-account.png)

    <ParamField path="Name" type="string" required>
      A friendly name for this account (e.g., `readonly`, `admin`, `developer`)
    </ParamField>

    <ParamField path="Description" type="string">
      Optional description of what this account is used for
    </ParamField>

    <ParamField path="Target Role ARN" type="string" required>
      The ARN of the IAM role users will assume (e.g., `arn:aws:iam::123456789012:role/pam-readonly`)
    </ParamField>

    <ParamField path="Default Session Duration" type="string" required>
      Session duration using human-readable format (e.g., `15m`, `30m`, `1h`). Minimum 15 minutes, maximum 1 hour.
      
      <Warning>
        Due to AWS role chaining limitations, the maximum session duration is **1 hour**, regardless of the target role's configured maximum session duration.
      </Warning>
    </ParamField>
  </Step>
</Steps>

## Access the AWS Console

Once your resource and accounts are configured, users can request access through KMS:

![Create AWS IAM Resource](/images/pam/resources/aws-iam/access-account.png)

<Steps>
  <Step title="Navigate to the resource">
    Go to the **Resources** tab in your PAM project and open the AWS IAM resource.
  </Step>

  <Step title="Select the account">
    In the resource’s accounts section, find the AWS Console account you want to access.
  </Step>

  <Step title="Request Access">
    Click the **Access** button for that account.

    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.
  </Step>
</Steps>