AWS Identity and Access Management
Using IAM (API Version 2010-05-08)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

IAM Policy Variables Overview

Introduction

In IAM policies, you provide a name for the specific resources that you want to control access to. The following policy allows the user who gets these permissions to programmatically list, read, and write objects with a prefix David in the Amazon S3 bucket mybucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["s3:ListBucket"],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::mybucket"],
      "Condition": {"StringLike": {"s3:prefix": ["David/*"]}}
    },
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::mybucket/David/*"]
    }
  ]
}

In some cases, you might not know the exact name of the resource when you write the policy. For example, you might want to allow each user to have his or her own objects in an Amazon S3 bucket, as in the previous example. However, instead of creating a separate policy for each user that specifies the user's name as part of the resource, you want to create a single group policy that works for any user in that group.

You can do this by using policy variables, a feature that lets you specify placeholders in a policy. When the policy is evaluated, the policy variables are replaced with values that come from the request itself.

The following example shows a policy for an Amazon S3 bucket that uses a policy variable.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["s3:ListBucket"],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::mybucket"],
      "Condition": {"StringLike": {"s3:prefix": ["${aws:username}/*"]}}
    },
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::mybucket/${aws:username}/*"]
    }
  ]
}

When this policy is evaluated, IAM uses the friendly name of the authenticated user in place of the variable ${aws:username}. This means that a single policy applied to a group of users can be used to control access to a bucket by using the user name as part of the resource.

The variable is marked using a $ prefix followed by a pair of curly braces ({ }). Inside the ${ } characters, you can include the name of the value from the request that you want to use in the policy. The values you can use are discussed later in this page.

Note

In order to use policy variables, you must include the Version element in a statement, and the version must be set to the value 2012-10-17. Earlier versions of the policy language don't support policy variables. If you don't include the Version element and set it to this version date, variables like ${aws:username} are treated as literal strings in the policy.

You can use policy variables in a similar way to allow each user to manage his or her own access keys. A policy that allows a user to programmatically change the access key for user David looks like this:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Action": ["iam:*AccessKey*"],
    "Effect": "Allow",
    "Resource": ["arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/David"]
  }]
}

If this policy is attached to user David, that user can change his own access key. As with the policies for accessing user-specific Amazon S3 objects, you'd have to create a separate policy for each user that includes the user's name, and then attach each policy to the individual users.

By using a policy variable, you can create a policy like this:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Action": ["iam:*AccessKey*"],
    "Effect": "Allow",
    "Resource": ["arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/${aws:username}"]
  }]
}

When you use a policy variable for the user name like this, you don't have to have a separate policy for each individual user. Instead, you can attach this new policy to an IAM group that includes everyone who should be allowed to manage their own access keys. When a user makes a request to modify his or her access key, IAM substitutes the user name from the current request for the ${aws:username} variable and evaluates the policy.

Where You Can Use Policy Variables

You can use policy variables in the Resource element and in string comparisons in the Condition element.

Resource Element

A policy variable can appear as the last part of the ARN that identifies a resource. The following policy might be attached to a group. It gives each of the users in the group full programmatic access to a user-specific object (their own "home directory") in Amazon S3.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["s3:ListBucket"],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::mybucket"],
      "Condition": {"StringLike": {"s3:prefix": ["${aws:username}/*"]}}
    },
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::mybucket/${aws:username}/*"]
    }
  ]
}

Note

This example uses the aws:username key, which returns the user's friendly name (like "Adele" or "David"). Under some circumstances, you might want to use the aws:userid key instead, which is a globally unique value. For more information, see Unique IDs.

The following policy might be used for an IAM group. It gives users in that group the ability to create, use, and delete queues that have their names and that are in the us-west-2 region.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "sqs:*",
    "Resource": "arn:aws:sqs:us-west-2:*:${aws:username}-queue"
  }]
}

Condition Element

A policy variable can also be used for Condition values in any condition that involves the string operators (StringEquals, StringLike, StringNotLike, etc.). The following Amazon SNS topic policy gives users in AWS account 999999999999 the ability to manage (perform all actions for) the topic only if the URL matches their AWS user name.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Principal": {"AWS": "999999999999"},
    "Effect": "Allow",
    "Action": "sns:*",
    "Condition": {"StringLike": {"sns:endpoint": "https://example.com/${aws:username}/*"}}
  }]
}

Request Information That You Can Use for Policy Variables

The values that can be substituted for policy variables must come from the current request context.

Information Available in All Requests

Policies contain keys whose values you can use as policy variables. (Under some circumstances, the keys do not contain a value—see the information that follows this list.)

  • aws:CurrentTime (for date/time conditions)

  • aws:EpochTime (the date in epoch or UNIX time, for use with date/time conditions)

  • aws:TokenIssueTime (the date/time that temporary security credentials were issued, for use with date/time conditions)

    Note

    This key is only available in requests that are signed using temporary security credentials. For more information about temporary security credentials, see Using Temporary Security Credentials.

  • aws:principaltype (a value that indicates whether the principal is an account, user, federated, or assumed role—see the explanation that follows)

  • aws:SecureTransport (Boolean representing whether the request was sent using SSL)

  • aws:SourceIp (the requester's IP address, for use with IP address conditions)

  • aws:UserAgent (information about the requester's client application, for use with string conditions)

  • aws:userid (the unique ID for the current user—see the following chart)

  • aws:username (the friendly name of the current user—see the following chart)

Important

The names of condition keys are case sensitive.

The values for aws:username, aws:userid, and aws:principaltype depend on what type of principal initiated the request—whether the request was made using the credentials of an AWS account, an IAM user, an IAM role, and so on. The following table shows values for these keys for different types of principal.

Principalaws:usernameaws:useridaws:principaltype
AWS account(not present)AWS account IDAccount
IAM userIAM-user-nameunique IDUser
Federated user(not present)account:caller-specified-nameFederatedUser
Web federated user (Login with Amazon, Amazon Cognito, Facebook, Google)

For information about policy keys that are available when you use web identity federation, see Identifying Apps and Users with Web Identity Federation in the Using Temporary Security Credentials guide.

(not present)(not present)AssumedRole
SAML federated user

For information about policy keys that are available when you use SAML federation, see Identifying Users for SAML Federation in the Using Temporary Security Credentials guide.

(not present)(not present)AssumedRole
Assumed role(not present)role-id:caller-specified-role-nameAssumedRole
Anonymous caller (Amazon SQS, Amazon SNS, and Amazon S3 only)(not present)(not present)Anonymous

In this table:

  • not present means that the value is not in the current request information, and any attempt to match it causes the request to be denied.

  • caller-specified-name and caller-specified-role-name are names that are passed by the calling process (e.g. application or service) when it makes a call to get temporary credentials.

Information Available in Requests for Federated Users

Federated users are users who are authenticated using a system other than IAM. For example, a company might have an application for use in-house that makes calls to AWS. It might be impractical to give an IAM identity to every corporate user who uses the application. Instead, the company might use a proxy (middle-tier) application that has a single IAM identity, or the company might use a SAML identity provider (IdP). The proxy application or SAML IdP authenticates individual users using the corporate network. A proxy application can then use its IAM identity to get temporary security credentials for individual users; a SAML IdP can in effect exchange identity information for AWS temporary security credentials. The temporary credentials can then be used to access AWS resources.

Similarly, you might create an app for a mobile device in which the app needs to access AWS resources. In that case, you might use web identity federation, where the app authenticates the user using a well-known identity provider like Login with Amazon, Amazon Cognito, Facebook, or Google. The app can then use the user's authentication information from these providers to get temporary security credentials for accessing AWS resources.

The recommended way to use web identity federation is by taking advantage of Amazon Cognito and the AWS mobile SDKs. For more information, see the following:

Service-Specific Information

Requests can also include service-specific keys and values in its request context. Examples include the following:

  • s3:prefix

  • s3:max-keys

  • s3:x-amz-acl

  • sns:Endpoint

  • sns:Protocol

For information about service-specific keys that you can use to get values for policy variables, refer to the documentation for the individual services. For example, see the following topics: