IAM Policies

This document covers:

  • Elements of an IAM Policy
  • Breakdown of the tables for Actions, Resources, and Condition keys per service
  • Generally how policy_sentry uses these tables to generate IAM Policies

IAM Policy Elements

The following IAM JSON Policy elements are included in policy_sentry-generated IAM Policies:

  • Version: specifies policy language versions dictated by AWS. There are two options - 2012-10-17 and 2008-10-17. policy_sentry generates policies for the most recent policy language - 2012-10-17
  • Statement: There is one statement array per policy, with multiple statements/SIDs inside that statement. The elements of a single statement/SID are listed below.
    • SID: Statement ID. Optional identifier for the policy statement. SID values can be assigned to each statement in a statement array.
    • Effect: Allow or explicit Deny. If there is any overlap on an action or actions with Allow vs. Deny, the Deny effect overrides the Allow.
    • Action: This refers to the IAM action - i.e., s3:GetObject, or ec2:DescribeInstances. Action text in a statement can have wildcards included: for example, ec2:* covers all EC2 actions, and ec2:Describe* covers all EC2 actions prefixed with Describe - such as DescribeInstances, DescribeInstanceAttributes, etc.
    • Resource: This refers to an Amazon Resource Name (ARN) that the Action can be performed against. There are differences in ARN format per service. Those differences can be viewed in the AWS Docs on ARNs and Namespaces

The ones we don’t use in this tool:

Actions, Resources, and Condition Keys Per Service

If you ever write or review IAM Policies, you should bookmark the documentation page for AWS Actions, Resources, and Context Keys here

This documentation is the seed source for the database that we create in policy_sentry. It contains tables for (1) Actions, (2) Resources/ARNs, and (3) Condition Keys for each service. This documentation is of critical importance because every IAM action for every IAM service has different ARNs that it can apply to, and different Condition Keys that it can apply to.

Action Table

Consider the Action table snippet from KMS shown below (source documentation can be viewed on the KMS documentation here).

Actions Access Level Resource Types Condition Keys Dependent Actions
kms:CreateGrant Permissions management key*    
kms:CallerAccount  
kms:CreateCustomKeyStore Write
  cloudhsm:DescribeClusters

As you can see, the Actions Table contains these columns:

  • Actions: The name of the IAM Action
  • Access Level: how the action is classified. This is limited to List, Read, Write, Permissions management, or Tagging.
  • Condition Keys: The condition key available for that action. There are some service specific ones that will contain the service namespace (i.e., ec2, or in this case, kms. Sometimes, there are AWS-level condition keys that are available to only some actions within some services, such as aws:SourceAccount. If those are available to the action, they will be supplied in that column.
  • Dependent Actions: Some actions require that other actions can be executed by the IAM Principal. The example above indicates that in order to call kms:CreateCustomKeyStore, you must be able to also execute cloudhsm:DescribeClusters.

And most importantly to the context of this tool, there is the Resource Types column:

  • Resource Types: This indicates whether the action supports resource-level permissions - i.e., restricting IAM Actions by ARN. If there is a value here, it points to the ARN Table shown later in the documentation.
    • In the example above, you can see that kms:CreateCustomKeyStore’s Resource Types cell is blank; this indicates that kms:CreateCustomKeyStore can only have * as the resource type.
    • Conversely, for kms:CreateGrant, the action can have either (1) * as the resource type, or key* as the resource type. The ARN format is not actually key*, it just points to that ARN format in the ARN Table explained below.

ARN Table

Consider the KMS ARN Table shown below (the source documentation can be viewed on the AWS website here.

Resource Types ARN Condition Keys
alias arn:${Partition}:kms:${Region}:${Account}:alias/${Alias}  
key arn:${Partition}:kms:${Region}:${Account}:key/${KeyId}  

The ARN Table has three fields:

  • Resource Types: The name of the resource type. This corresponds to the “Resource Types” field in the Action table. In the example above, the types are:
  • alias
  • key
  • ARN: This shows the required ARN format that can be specified in IAM policies for the IAM Actions that allow this ARN format. In the example above the ARN types are:
  • arn:${Partition}:kms:${Region}:${Account}:alias/${Alias}
  • arn:${Partition}:kms:${Region}:${Account}:key/${KeyId}
  • Condition Keys: This specifies condition context keys that you can include in an IAM policy statement only when both (1) this resource and (2) a supporting action from the table above are included in the statement.

Condition Keys Table

There is also a Condition Keys table. An example is shown below.

Condition Keys Type Description
kms:BypassPolicyLockoutSafetyCheck Bool Controls access to the CreateKey and PutKeyPolicy operations based on the value of the BypassPolicyLockoutSafetyCheck parameter in the request.
kms:CallerAccount String Controls access to specified AWS KMS operations based on the AWS account ID of the caller. You can use this condition key to allow or deny access to all IAM users and roles in an AWS account in a single policy statement.

Note: While policy_sentry does import the Condition Keys table into the database, it does not currently provide functionality to insert these condition keys into the policies. This is due to the complexity of each condition key, and the dubious viability of mandating those condition keys for every IAM policy.

We might support the Global Condition keys for IAM policies in the future, perhaps to be supplied via a user config file, but that functionality is not on the roadmap at this time. For more information on Global Condition Keys, see this documentation.