AWS Documentation » Amazon EC2 » User Guide » Network and Security » Controlling Access to Amazon EC2 Resources	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Controlling Access to Amazon EC2 Resources

You use your AWS account credentials to access your Amazon EC2 resources. You can use features of Amazon EC2 and AWS Identity and Access Management (IAM) to allow other users to access your Amazon EC2 resources without giving them your AWS account credentials.

Topics

Amazon EC2 Permission Attributes

Amazon EC2 enables you to specify the AWS accounts that can access your Amazon Machine Images (AMIs) and Amazon EBS snapshots. These permissions work at the AWS account level only; you can't restrict access to specific users within the specified AWS account. All users in the AWS account that you've specified can use the AMI or snapshot.

Each AMI has a LaunchPermission attribute that controls which AWS accounts can access the AMI. For more information, see Sharing AMIs.

Each Amazon EBS snapshot has a VolumePermission attribute that controls which AWS accounts can access the snapshot. For more information, see Modifying Snapshot Permissions.

Introduction to IAM

Amazon EC2 integrates with AWS Identity and Access Management (IAM), a service that enables you to do the following:

Create users and groups under your AWS account
Easily share your AWS resources between the users in your AWS account
Assign unique security credentials to each user
Control each user's access to services and resources
Get a single bill for all users in your AWS account

With Amazon EC2, you can use IAM to control which users in your AWS account can create AMIs or launch instances.

Creating an IAM Group and Users

To create an IAM group and users

Open the IAM console at https://console.aws.amazon.com/iam/.
From the dashboard, click Create a New Group of Users.
On the GROUP NAME page, specify the name of the group under Group Name.
On the PERMISSIONS page, specify the policies for the group. You can select a policy template or create custom policies. For more information, see IAM Policies for Amazon EC2.
On the USERS page, specify one or more user names. If the users will use the CLI or API, select Generate an access key for each User. Click Continue.
If you had IAM generate access keys, click Download Credentials or Show User Security Credentials and save the access keys.
If the users will use the console, click Users in the navigation pane and do the following for each user:
1. Select the user.
2. Click the Security Credentials tab in the details pane.
3. Under Sign-In Credentials, click Manage Password.
4. In the Manage Password dialog box, select an option and click Apply.
5. Click Download Credentials or Show User Security Credentials and save the password.
Give each user his or her credentials (access keys and password); this enables them to access services based on the permissions you specified for the IAM group.

For more information about IAM, see the following:

IAM Policies for Amazon EC2

By default, IAM users don't have permission to use Amazon EC2 API actions. To allow users to use these API actions, you create an IAM policy that allows access to one or more API actions, and then attach the policy to the IAM user or group.

A policy consists of one or more statements, where each statement describes one set of permissions. You create a policy using JSON, as shown here:

{
  "Version":"yyyy-mm-dd",
  "Statement":[{
    "Effect":"effect",
    "Action":"action",
    "Resource":"arn"
    "Condition":{
      "condition":{
        "key":"value"
        }
      }
    }
  ]
}

The effect can be Allow or Deny. To learn about specifying action, see Amazon EC2 API Actions. To learn about specifying arn, see Amazon Resource Names (ARNs) for Amazon EC2. To learn about specifying conditions for Amazon EC2, see Amazon EC2 Policy Keys.

For more information about policies, see Permissions and Policies in the IAM documentation.

Amazon EC2 API Actions

In an IAM policy, you can specify any of the Amazon EC2 API actions. Each action name must be prefixed with the lowercase string ec2:. For example: ec2:RunInstances or ec2:CreateImage. To specify all Amazon EC2 API actions, use ec2:*.

For a list of Amazon EC2 actions, see Actions in the Amazon Elastic Compute Cloud API Reference.

Amazon Resource Names (ARNs) for Amazon EC2

Amazon EC2 has no Amazon Resource Names (ARNs) because you can't specify particular Amazon EC2 resources in an IAM policy. When you write a policy to control access to Amazon EC2 API actions, specify the * wildcard as the resource.

For more information about ARNs, see Amazon Resource Names (ARN) and AWS Service Namespaces in the Amazon Web Services General Reference.

Amazon EC2 Policy Keys

In an IAM policy, you can specify conditions that control when a policy is in effect. Each condition contains one or more key-value pairs. AWS defines conditions and keys, and individual services can define additional service-specific keys.

Amazon EC2 implements the AWS-wide policy keys, but no service-specific policy keys.

For a list of AWS-wide policy keys, see Available Keys in Using IAM.

Example Policies for Amazon EC2

The following examples show simple policies for controlling user access to Amazon EC2. We specify the resource as "*", because you can't specify particular Amazon EC2 resources in an IAM policy.

Example 1: Allow a group to describe, launch, stop, start, and terminate instances

In this example, we create a policy that allows the group to use the specified API actions.

{
   "Statement":[{
      "Effect":"Allow",
      "Action":["ec2:DescribeInstances","ec2:RunInstances",
                "ec2:StopInstances","ec2:StartInstances",
                "ec2:TerminateInstances"],
      "Resource":"*"
      }
   ]
}

Example 2: Allow a group to list the Amazon EC2 resources that belong to the AWS account

In this example, we create a policy that allows the group to use all Amazon EC2 API actions whose names begin with Describe.

{
   "Statement":[{
      "Effect":"Allow",
      "Action":"ec2:Describe*",
      "Resource":"*"
      }
   ]
}

IAM Roles for Amazon EC2

Applications must sign their API requests with AWS credentials. Therefore, if you are an application developer, you need a strategy for managing credentials for your applications that run on Amazon EC2 instances. For example, you can securely distribute your AWS credentials to the instances, enabling the applications on those instances to use your credentials to sign requests, while protecting them from other users. However, it's challenging to securely distribute credentials to each instance, especially those that AWS creates on your behalf, such as Spot Instances or instances in Auto Scaling groups. You must also be able to update the credentials on each instance when you rotate your AWS credentials.

We designed IAM roles so that your applications can securely make API requests from your instances, without requiring you to manage the security credentials that the applications use. Instead of creating and distributing your AWS credentials, you can delegate API access using IAM roles as follows:

Create an IAM role.
Define which accounts or AWS services can assume the role.
Define which actions can be performed.
Specify the role when you launch your instances.

For example, you can use IAM roles to grant permissions to an application on an instance that needs to access a bucket in Amazon S3.

You can specify permissions for IAM roles by creating a policy in JSON format. These are similar to the policies that you create for IAM users. If you make a change to a role, the change is propagated to all instances, simplifying credential management. For more information about creating and using IAM roles, see Roles.

Retrieving Security Credentials from Instance Metadata

An application on the instance retrieves the security credentials provided by the role from the instance metadata item iam/security-credentials/role-name. The application uses the security credentials associated with the role to access resources using the permissions you've defined for the role. These security credentials are temporary and we rotate them automatically. We make new credentials available at least five minutes prior to the expiration of the old credentials.

Warning

If you use services that use instance metadata with IAM roles, ensure that you don't expose your credentials when the services make HTTP calls on your behalf. The types of services that could expose your credentials include HTTP proxies, HTML/CSS validator services, and XML processors that support XML inclusion.

The following example demonstrates how to retrieve the security credentials for an IAM role named s3access.

GET http://169.254.169.254/latest/meta-data/iam/security-credentials/s3access; echo {
    "Code" : "Success",
    "LastUpdated" : "2012-04-26T16:39:16Z",
    "Type" : "AWS-HMAC",
    "AccessKeyId" : "AKIAIOSFODNN7EXAMPLE",
    "SecretAccessKey" : "UtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "Token" : "...",
    "Expiration" : "2012-04-26T22:39:16Z"
  }

For more information about instance metadata, see Instance Metadata. For more information about temporary credentials, see Using Temporary Security Credentials.

Launching an Instance with an IAM Role using the Console

You must create an IAM role before you can launch an instance with that role.

Important

After you create an IAM role, it may take several seconds for the permissions to propagate. If your first attempt to launch an instance with a role fails, wait a few seconds before trying again. For more information, see Troubleshooting Working with Roles.

To launch an instance with an IAM role using the AWS Management Console

Create an IAM role.
1. Open the IAM console at https://console.aws.amazon.com/iam/.
2. In the navigation pane, click Roles, and then click Create New Role.
3. On the first CONFIGURE ROLE page, enter a name for the role and click Continue.
4. On the second CONFIGURE ROLE page, click the Select button for Amazon EC2.
5. On the SET PERMISSIONS page, specify the policies for the role. You can select a policy template or create custom policies. For more information, see Creating a Role and IAM Policies for Amazon EC2.
6. Review the role information, edit the role as needed, and then click Create Role.
Launch an instance with the IAM role.
1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
2. On the dashboard, click Launch Instance.
3. If you're using the Quick Launch Wizard, do the following:
  1. Provide the requested information on the first page, and then click Continue.
  2. Click Edit details.
  3. Select Advanced Details and select the IAM role you created from the IAM Role list.
  4. Click Save details and then click Launch.
4. If you're using the Classic Wizard, do the following:
  1. Click the Select button for the AMI to use.
  2. Provide the requested information on the first INSTANCE DETAILS page and click Continue.
  3. On the second INSTANCE DETAILS page, select the IAM role you created from the IAM Role list and click Continue.
  4. Finish the wizard, clicking Launch on the final page.
If you are using the Amazon EC2 API Actions in your application, retrieve the AWS security credentials made available on the instance and use them to sign the requests. Note that the AWS SDK does this for you.
```
GET http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name
```

Launching an Instance with an IAM Role using the CLI

You must create an IAM role before you can launch an instance with that role.

Important

To launch an instance with an IAM role using the IAM and Amazon EC2 CLIs

The following example creates an IAM role named s3access with a policy that allows the role to access an S3 bucket, and an instance profile named s3access.

$ iam-rolecreate -r s3access -s ec2.amazonaws.com

$ iam-roleaddpolicy -r s3access -e Allow -a s3:\* -c \* -p s3star -o
{"Version":"2008-10-17","Statement":[{"Effect":"Allow","Action":["s3:*"],"Resource":["*"]}]}

$ iam-instanceprofilecreate -s s3access -r s3access arn:aws:iam::111111111111:instance-profile/s3access

For more information, see iam-rolecreate, iam-roleaddpolicy, and iam-instanceprofilecreate in the AWS Identity and Access Management Command Line Reference.

Launch an instance using the instance profile. The following example shows a t1.micro instance being launched with the instance profile created in step 1.

$ ec2-run-instances -t t1.micro -p arn:aws:iam::111111111111:instance-profile/s3access -k key-pair -g 'Web Server' ami-e565ba8c
    RESERVATION     r-11c62773      111111111111    sg-e7ddc68e
    INSTANCE        i-9a6843fd      ami-e565ba8c                    pending key-pair      0       us-east-1e          aki-88aa75e1            disabled

$ ec2-describe-instances
    RESERVATION     r-11c62773      111111111111    sg-e7ddc68e
    INSTANCE        i-9a6843fd      ami-e565ba8c   
    ec2-50-19-200-155.compute-1.amazonaws.com       ip-10-28-28-186.ec2.internal       
    running key-pair      0       t1.micro        2012-04-26T16:29:25.000Z    us-east-1e
    aki-88aa75e1            disabled                                  
    AIPAJ6OQOSP4IRHXCI6E4

For more information, see ec2-run-instances and ec2-describe-instances in the Amazon Elastic Compute Cloud Command Line Reference.

If you are using the Amazon EC2 API Actions in your application, retrieve the AWS security credentials made available on the instance and use them to sign the requests. Note that the AWS SDK does this for you.
```
GET http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name
```

Launching an Instance with an IAM Role using the AWS SDK

The AWS SDK documentation includes walkthroughs that show an application that uses security credentials from a IAM role to read an Amazon S3 bucket. For more information, see the following topics:

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...