Menu
Amazon Elastic Compute Cloud
User Guide for Windows Instances

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 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 your credentials 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 permission to make API requests using IAM roles as follows:

  1. Create an IAM role.

  2. Define which accounts or AWS services can assume the role.

  3. Define which API actions and resources the application can use after assuming the role.

  4. Specify the role when you launch your instance, or attach the role to a running or stopped instance.

  5. Have the application retrieve a set of temporary credentials and use them.

For example, you can use IAM roles to grant permissions to applications running on your instances that needs to use 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.

You cannot attach multiple IAM roles to a single instance, but you can attach a single IAM role to multiple instances. For more information about creating and using IAM roles, see Roles in the IAM User Guide.

You can apply resource-level permissions to your IAM policies to control users' ability to attach, replace, or detach IAM roles for an instance. For more information, see Supported Resource-Level Permissions for Amazon EC2 API Actions and the following example: 9: Working with IAM Roles.

Instance Profiles

Amazon EC2 uses an instance profile as a container for an IAM role. When you create an IAM role using the IAM console, the console creates an instance profile automatically and gives it the same name as the role to which it corresponds. If you use the Amazon EC2 console to launch an instance with an IAM role or to attach an IAM role to an instance, you choose the instance based on a list of instance profile names.

If you use the AWS CLI, API, or an AWS SDK to create a role, you create the role and instance profile as separate actions, with potentially different names. If you then use the AWS CLI, API, or an AWS SDK to launch an instance with an IAM role or to attach an IAM role to an instance, specify the instance profile name.

An instance profile can contain only one IAM role. This limit cannot be increased.

For more information, see Instance Profiles in the IAM User Guide.

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 is granted the permissions for the actions and resources that you've defined for the role through the security credentials associated with 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 command retrieves the security credentials for an IAM role named s3access.

Copy
curl http://169.254.169.254/latest/meta-data/iam/security-credentials/s3access

The following is example output.

{
  "Code" : "Success",
  "LastUpdated" : "2012-04-26T16:39:16Z",
  "Type" : "AWS-HMAC",
  "AccessKeyId" : "AKIAIOSFODNN7EXAMPLE",
  "SecretAccessKey" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "Token" : "token",
  "Expiration" : "2012-04-27T22:39:16Z"
}

For applications, AWS CLI, and Tools for Windows PowerShell commands that run on the instance, you do not have to explicitly get the temporary security credentials — the AWS SDKs, AWS CLI, and Tools for Windows PowerShell automatically get the credentials from the EC2 instance metadata service and use them. To make a call outside of the instance using temporary security credentials (for example, to test IAM policies), you must provide the access key, secret key, and the session token. For more information, see Using Temporary Security Credentials to Request Access to AWS Resources in the IAM User Guide.

For more information about instance metadata, see Instance Metadata and User Data.

Granting an IAM User Permission to Pass an IAM Role to an Instance

To enable an IAM user to launch an instance with an IAM role or to attach or replace an IAM role for an existing instance, you must grant the user permission to pass the role to the instance.

The following IAM policy grants users permission to launch instances (ec2:RunInstances) with an IAM role, or to attach or replace an IAM role for an existing instance (ec2:AssociateIamInstanceProfile and ec2:ReplaceIamInstanceProfileAssociation).

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:RunInstances", "ec2:AssociateIamInstanceProfile", "ec2:ReplaceIamInstanceProfileAssociation" ], "Resource": "*" }, { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "*" } ] }

This policy grants IAM users access to all your roles by specifying the resource as "*" in the policy. However, consider whether users who launch instances with your roles (ones that exist or that you'll create later on) might be granted permissions that they don't need or shouldn't have.

Working with IAM Roles

You can create an IAM role and attach it to an instance during or after launch. You can also replace or detach an IAM role for an instance.

Creating an IAM Role

You must create an IAM role before you can launch an instance with that role or attach it to an instance.

To create an IAM role using the IAM console

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, Create new role.

  3. On the Select role type page, choose Select next to Amazon EC2.

  4. On the Attach Policy page, select an AWS managed policy that grants your instances access to the resources that they need.

  5. On the Set role name and review page, type a name for the role and choose Create role.

Alternatively, you can use the AWS CLI to create an IAM role.

To create an IAM role and instance profile using the AWS CLI

  • Create an IAM role with a policy that allows the role to use an Amazon S3 bucket.

    1. Create the following trust policy and save it in a text file named ec2-role-trust-policy.json.

      Copy
      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com"}, "Action": "sts:AssumeRole" } ] }
    2. Create the s3access role and specify the trust policy that you created.

      Copy
      aws iam create-role --role-name s3access --assume-role-policy-document file://ec2-role-trust-policy.json { "Role": { "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" } } ] }, "RoleId": "AROAIIZKPBKS2LEXAMPLE", "CreateDate": "2013-12-12T23:46:37.247Z", "RoleName": "s3access", "Path": "/", "Arn": "arn:aws:iam::123456789012:role/s3access" } }
    3. Create an access policy and save it in a text file named ec2-role-access-policy.json. For example, this policy grants administrative permissions for Amazon S3 to applications running on the instance.

      Copy
      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:*"], "Resource": ["*"] } ] }
    4. Attach the access policy to the role.

      Copy
      aws iam put-role-policy --role-name s3access --policy-name S3-Permissions --policy-document file://ec2-role-access-policy.json
    5. Create an instance profile named s3access-profile.

      Copy
      aws iam create-instance-profile --instance-profile-name s3access-profile { "InstanceProfile": { "InstanceProfileId": "AIPAJTLBPJLEGREXAMPLE", "Roles": [], "CreateDate": "2013-12-12T23:53:34.093Z", "InstanceProfileName": "s3access-profile", "Path": "/", "Arn": "arn:aws:iam::123456789012:instance-profile/s3access-profile" } }
    6. Add the s3access role to the s3access-profile instance profile.

      Copy
      aws iam add-role-to-instance-profile --instance-profile-name s3access-profile --role-name s3access

    For more information about these commands, see create-role, put-role-policy, and create-instance-profile in the AWS Command Line Interface Reference.

    Alternatively, you can use the following AWS Tools for Windows PowerShell commands:

Launching an Instance with an IAM Role

After you've created an IAM role, you can launch an instance, and associate that role with the instance during launch.

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 in the IAM User Guide.

To launch an instance with an IAM role using the console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the dashboard, choose Launch Instance.

  3. Select an AMI and instance type and then choose Next: Configure Instance Details.

  4. On the Configure Instance Details page, for IAM role, select the IAM role that you created.

    Note

    The IAM role list displays the name of the instance profile that you created when you created your IAM role. If you created your IAM role using the console, the instance profile was created for you and given the same name as the role. If you created your IAM role using the AWS CLI, API, or an AWS SDK, you may have named your instance profile differently.

  5. Configure any other details, then follow the instructions through the rest of the wizard, or choose Review and Launch to accept default settings and go directly to the Review Instance Launch page.

  6. Review your settings, then choose Launch to choose a key pair and launch your instance.

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

    Copy
    curl http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name

Alternatively, you can use the AWS CLI to associate a role with an instance during launch. You must specify the instance profile in the command.

To launch an instance with an IAM role using the AWS CLI

  1. Use the run-instances command to launch an instance using the instance profile. The following example shows how to launch an instance with the instance profile.

    Copy
    aws ec2 run-instances --image-id ami-11aa22bb --iam-instance-profile Name="s3access-profile" --key-name my-key-pair --security-groups my-security-group --subnet-id subnet-1a2b3c4d

    Alternatively, use the New-EC2Instance Tools for Windows PowerShell command.

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

    Copy
    curl http://169.254.169.254/latest/meta-data/iam/security-credentials/role_name

Attaching an IAM Role to an Instance

After you've created an IAM role, you can attach it to a running or stopped instance.

To attach an IAM role to an instance using the console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance, choose Actions, Instance Settings, Attach/Replace IAM role.

  4. Select the IAM role to attach to your instance, and choose Apply.

To attach an IAM role to an instance using the AWS CLI

  1. If required, describe your instances to get the ID of the instance to which to attach the role.

    Copy
    aws ec2 describe-instances
  2. Use the associate-iam-instance-profile command to attach the IAM role to the instance by specifying the instance profile. You can use the Amazon Resource Name (ARN) of the instance profile, or you can use its name.

    Copy
    aws ec2 associate-iam-instance-profile --instance-id i-1234567890abcdef0 --iam-instance-profile Name="TestRole-1" { "IamInstanceProfileAssociation": { "InstanceId": "i-1234567890abcdef0", "State": "associating", "AssociationId": "iip-assoc-0dbd8529a48294120", "IamInstanceProfile": { "Id": "AIPAJLNLDX3AMYZNWYYAY", "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-1" } } }

Alternatively, use the following Tools for Windows PowerShell commands:

Detaching an IAM Role

You can detach an IAM role from a running or stopped instance.

To detach an IAM role from an instance using the console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance, choose Actions, Instance Settings, Attach/Replace IAM role.

  4. For IAM role, choose No Role. Choose Apply.

  5. In the confirmation dialog box, choose Yes, Detach.

To detach an IAM role from an instance using the AWS CLI

  1. If required, use describe-iam-instance-profile-associations to describe your IAM instance profile associations and get the association ID for the IAM instance profile to detach.

    Copy
    aws ec2 describe-iam-instance-profile-associations { "IamInstanceProfileAssociations": [ { "InstanceId": "i-088ce778fbfeb4361", "State": "associated", "AssociationId": "iip-assoc-0044d817db6c0a4ba", "IamInstanceProfile": { "Id": "AIPAJEDNCAA64SSD265D6", "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2" } } ] }
  2. Use the disassociate-iam-instance-profile command to detach the IAM instance profile using its association ID.

    Copy
    aws ec2 disassociate-iam-instance-profile --association-id iip-assoc-0044d817db6c0a4ba { "IamInstanceProfileAssociation": { "InstanceId": "i-087711ddaf98f9489", "State": "disassociating", "AssociationId": "iip-assoc-0044d817db6c0a4ba", "IamInstanceProfile": { "Id": "AIPAJEDNCAA64SSD265D6", "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2" } } }

Alternatively, use the following Tools for Windows PowerShell commands:

Replacing an IAM Role

You can replace an IAM role for a running instance. You can do this if you want to change the IAM role for an instance without detaching the existing one first; for example, to ensure that API actions performed by applications running on the instance are not interrupted.

Te replace an IAM role for an instance using the console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance, choose Actions, Instance Settings, Attach/Replace IAM role.

  4. Select the IAM role to attach to your instance, and choose Apply.

To replace an IAM role for an instance using the AWS CLI

  1. If required, describe your IAM instance profile associations to get the association ID for the IAM instance profile to replace.

    Copy
    aws ec2 describe-iam-instance-profile-associations
  2. Use the replace-iam-instance-profile-association command to replace the IAM instance profile by specifying the association ID for the existing instance profile and the ARN or name of the instance profile that should replace it.

    Copy
    aws ec2 replace-iam-instance-profile-association --association-id iip-assoc-0044d817db6c0a4ba --iam-instance-profile Name="TestRole-2" { "IamInstanceProfileAssociation": { "InstanceId": "i-087711ddaf98f9489", "State": "associating", "AssociationId": "iip-assoc-09654be48e33b91e0", "IamInstanceProfile": { "Id": "AIPAJCJEDKX7QYHWYK7GS", "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2" } } }

Alternatively, use the following Tools for Windows PowerShell commands: