Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances
Applications that run on an EC2 instance must include AWS credentials in their AWS API requests. You could have your developers store AWS credentials directly within the EC2 instance and allow applications in that instance to use those credentials. But developers would then have to manage the credentials and ensure that they securely pass the credentials to each instance and update each EC2 instance when it's time to rotate the credentials. That's a lot of additional work.
Instead, you can and should use an IAM role to manage temporary credentials for applications that run on an EC2 instance. When you use a role, you don't have to distribute long-term credentials (such as a user name and password or access keys) to an EC2 instance. Instead, the role supplies temporary permissions that applications can use when they make calls to other AWS resources. When you launch an EC2 instance, you specify an IAM role to associate with the instance. Applications that run on the instance can then use the role-supplied temporary credentials to sign API requests.
Using roles to grant permissions to applications that run on EC2 instances requires a bit of extra configuration. An application running on an EC2 instance is abstracted from AWS by the virtualized operating system. Because of this extra separation, an additional step is needed to assign an AWS role and its associated permissions to an EC2 instance and make them available to its applications. This extra step is the creation of an instance profile that is attached to the instance. The instance profile contains the role and can provide the role's temporary credentials to an application that runs on the instance. Those temporary credentials can then be used in the application's API calls to access resources and to limit access to only those resources that the role specifies. Note that only one role can be assigned to an EC2 instance at a time, and all applications on the instance share the same role and permissions.
Using roles in this way has several benefits. Because role credentials are temporary and rotated automatically, you don't have to manage credentials, and you don't have to worry about long-term security risks. In addition, if you use a single role for multiple instances, you can make a change to that one role and the change is propagated automatically to all the instances.
Although a role is usually assigned to an EC2 instance when you launch it, a role can also be attached to an EC2 instance that is already running. To learn how to attach a role to a running instance, see IAM Roles for Amazon EC2.
How Do Roles for EC2 Instances Work?
In the following figure, a developer runs an application on an EC2 instance that requires access to the S3 bucket named . An administrator creates the role. The role includes policies that grant read permissions for the bucket and that allow the developer to launch the role with an EC2 instance. When the application runs on the instance, it can use the role's temporary credentials to access the photos bucket. The administrator doesn't have to grant the developer permission to access the photos bucket, and the developer never has to share or manage credentials.
The administrator uses IAM to create the role. In the role's trust policy, the administrator specifies that only EC2 instances can assume the role. In the role's permission policy, the administrator specifies read-only permissions for the bucket.
A developer launches an EC2 instance and assigns the role to that instance.
If you use the IAM console, the instance profile is managed for you and is mostly transparent to you. However, if you use the AWS CLI or API to create and manage the role and EC2 instance, then you must create the instance profile and assign the role to it as separate steps. Then, when you launch the instance, you must specify the instance profile name instead of the role name.
When the application runs, it obtains temporary security credentials from Amazon EC2 instance metadata, as described in Retrieving Security Credentials from Instance Metadata. These are temporary security credentials that represent the role and are valid for a limited period of time.
With some AWS SDKs, the developer can use a provider that manages the temporary security credentials transparently. (The documentation for individual AWS SDKs describes the features supported by that SDK for managing credentials.)
Alternatively, the application can get the temporary credentials directly from the instance metadata of the EC2 instance. Credentials and related values are available from the category (in this case, ) of the metadata. If the application gets the credentials from the instance metadata, it can cache the credentials.
Using the retrieved temporary credentials, the application accesses the photo bucket. Because of the policy attached to the role, the application has read-only permissions.
The temporary security credentials that are available on the instance are automatically rotated before they expire so that a valid set is always available. The application just needs to make sure that it gets a new set of credentials from the instance metadata before the current ones expire. If the AWS SDK manages credentials, the application doesn't need to include additional logic to refresh the credentials. However, if the application gets temporary security credentials from the instance metadata and has cached them, it should get a refreshed set of credentials every hour, or at least 15 minutes before the current set expires. The expiration time is included in the information that is returned in the category.
Permissions Required for Using Roles with Amazon EC2
To launch an instance with a role, the developer must have permission to launch EC2 instances and permission to pass IAM roles.
The following sample policy allows users to use the AWS Management Console to launch an instance with a role. The policy includes wildcards () to allow a user to pass any role and to perform all Amazon EC2 actions. The action allows users to view all of the roles that are available in the AWS account.
Example policy that grants a user permission to use the Amazon EC2 console to launch an instance with any role
Restricting Which Roles Can Be Passed to EC2 Instances (Using PassRole)
You can use the permission to restrict which role a user can pass to an EC2 instance when the user launches the instance. This helps prevent the user from running applications that have more permissions than the user has been granted—that is, from being able to obtain elevated privileges. For example, imagine that user Alice has permissions only to launch EC2 instances and to work with Amazon S3 buckets, but the role she passes to an EC2 instance has permissions to work with IAM and Amazon DynamoDB. In that case, Alice might be able to launch the instance, log into it, get temporary security credentials, and then perform IAM or DynamoDB actions that she's not authorized for.
To restrict which roles a user can pass to an EC2 instance, you create a policy that allows the action. You then attach the policy to the user (or to an IAM group that the user belongs to) who will launch EC2 instances. In the element of the policy, you list the role or roles that the user is allowed to pass to EC2 instances. When the user launches an instance and associates a role with it, Amazon EC2 checks whether the user is allowed to pass that role. Of course, you should also ensure that the role that the user can pass does not include more permissions than the user is supposed to have.
is not an API action in the same way that or is. Instead, it's a permission that AWS checks whenever a role ARN is passed as a parameter to an API (or the console does this on the user's behalf). It helps an administrator to control which roles can be passed by which users. In this case, it ensures that the user is allowed to attach a specific role to an Amazon EC2 instance.
Example policy that grants a user permission to launch an EC2 instance with a specific role
The following sample policy allows users to use the Amazon EC2 API to launch an instance with a role. The element specifies the Amazon Resource Name (ARN) of a role. By specifying the ARN, the policy grants the user the permission to pass only the role. If the user tries to specify a different role when launching an instance, the action fails.
How Do I Get Started?
To understand how roles work with EC2 instances, you need to use the IAM console to create a role, launch an EC2 instance that uses that role, and then examine the running instance. You can examine the instance metadata to see how the role's temporary credentials are made available to an instance. You can also see how an application that runs on an instance can use the role. Use the following resources to learn more.
Getting Started with IAM Roles for EC2 Instances. The linked video shows how to use an IAM role with an EC2 instance to control what an application can do when it runs on the instance. The video shows how the application (written in the AWS SDK) can get temporary security credentials through the role.
SDK walkthroughs. The AWS SDK documentation includes walkthroughs that show an application running on an EC2 instance that uses temporary credentials for roles to read an Amazon S3 bucket. Each of the following walkthroughs presents similar steps with a different programming language:
For more information about creating roles or roles for EC2 instances, see the following information:
Except for KMS events that have event ID 12290, Windows logs all activation events to the Application event log with the event provider name Microsoft-Windows-Security-SPP. Windows logs KMS events to the Key Management Service log in the Applications and Services folder. IT pros can use Slui.exe to display a description of most activation-related error codes. The general syntax for this command is:
For example, if event ID 12293 contains error code 0x8007267C, a description of that error can be displayed by running the following command:
KMS Activation Troubleshooting Steps
Table 2 describes common issues that can occur during KMS activations as well as steps for resolving them.
Table 2. Troubleshooting Steps for Common KMS Activation Issues
|Is the KMS client computer activated?||Look for “Windows is activated” in the Control Panel System item. Alternatively, run Slmgr.vbs with the /dli command-line option.|
|The KMS client computer will not activate.||Verify that the KMS activation threshold is met. Run Slmgr.vbs with the /dli command-line option on the KMS host to determine the host’s current count. Until the KMS host has a count of 25, Windows 7 client computers cannot be activated. Windows Server 2008 R2 KMS clients require a KMS count of 5 for activation. For more information about KMS requirements, see the Volume Activation Planning Guide. On the KMS client, look in the Application event log for event ID 12289. Check this event for the following: |
On the KMS host, look in the KMS event log for event ID 12290. Check this event for the following:
|Error 0xC004F035||This error code equates to “The software Licensing Service reported that the computer could not be activated with a Volume license product key…” This error text can be incorrect. |
If the proper Windows edition is installed with a GVLK, this error my also indicate that the computer is missing a Windows marker in the BIOS, which is required for KMS client activation. The proper error text should read:
Error: Invalid Volume License KeyIn order to activate, you need to change your product key to a valid Multiple Activation Key (MAK) or Retail key. You must have a qualifying operating system license AND a Volume license Windows 7 upgrade license, or a full license for Windows 7 from a retail source.
ANY OTHER INSTALLATION OF THIS SOFTWARE IS IN VIOLATION OF YOUR AGREEMENT AND APPLICABLE COPYRIGHT LAW.
|What does this error code mean?||If Slmgr.vbs returns a hexadecimal error code or event ID 12288 contains a result code other than 0, determine the corresponding error message by running the following command:|
|Clients are not adding to the KMS count.||Run sysprep /generalize or slmgr /rearm to reset the client computer ID (CMID) and other product-activation information. Otherwise, each client computer looks identical, and the KMS host does not count them as separate KMS clients.|
|KMS hosts are unable to create SRV records.||Domain Name System (DNS) may restrict Write access or may not support dynamic DNS (DDNS). In this case, give the KMS host Write access to the DNS database, or create the service (SRV) resource record (RR) manually. For more information about this issue, see the Volume Activation Deployment Guide.|
|Only the first KMS host is able to create SRV records.||If the organization has more than one KMS host, the other hosts might not able to update the SRV RR unless the SRV default permissions are changed. For more information about this issue, see theVolume Activation Deployment Guide.|
|I installed a KMS key on the KMS client.||KMS keys should only be installed on KMS hosts, not on KMS clients. Run slmgr.vbs -ipk <SetupKey>. The Volume Activation Technical Reference Guide contains a table of setup keys that can be used to restore the computer to a KMS client. These keys are publicly known and are edition-specific. Remember to delete any unnecessary SRV RRs from DNS and restart the computers.|
MAK Activation Troubleshooting Steps
Table 3 presents common issues that can occur during MAK activations and steps for resolving them.
Table 3. Troubleshooting Steps for Common MAK Activation Issues
|How can I tell if my computer is activated?||Look for “Windows is activated” in the Control Panel System item. Alternatively, run Slmgr.vbs with the /dli command-line option.|
|The computer will not activate over the Internet.||Ensure the required ports are open in the firewall. For a list of ports, see the Volume Activation Deployment Guide.|
|Internet and telephone activation fail.||Contact a local Microsoft Activation Center. For phone numbers of Microsoft Activation Centers worldwide, go to http://go.microsoft.com/fwlink/?LinkID=107418. Be sure to provide the Volume License agreement information and proof of purchase when calling.|
|Slmgr.vbs /ato returns an error code.||If Slmgr.vbs returns a hexadecimal error code, determine the corresponding error message by running the following script: |
Slui.exe 0x2a 0x ErrorCode
KMS Host Failover
If a KMS host fails, a KMS host key must be installed on a new host and activated. Ensure that the new KMS host has an SRV RR in the DNS database. If installing the new KMS host with the same computer name and IP address as the failed KMS host, the new KMS host can use the DNS SRV record of the failed host. If the new host has a different computer name, organizations can manually remove the DNS SRV RR of the failed host or allow DNS to remove it automatically if scavenging is enabled in DNS. If the network is using DDNS, the new KMS host automatically creates a new SRV RR on the DNS server. The new KMS host then starts collecting client renewal requests and begins activating clients as soon as the KMS activation threshold is met.
If configuring KMS clients to use auto-discovery, they automatically choose another KMS host if the original KMS host does not respond to renewal requests. If not using auto-discovery, update the KMS client computers that were assigned to the failed KMS host by running Slmgr.vbs /skms. To avoid this scenario, configure KMS clients to use auto-discovery. For more information, see the Volume Activation Deployment Guide.
Disabling Windows Anytime Upgrade for Windows 7
The Windows Anytime Upgrade (WAU) program allows Windows 7 Professional users to purchase an upgrade directly from Microsoft by clicking the Windows Anytime Upgrade link in the Extras and Upgrades subfolder of the All Programs menu. This link and the program are only in Windows 7 Professional editions available through retail channels.
Administrators can disable WAU for users by adding the DWORD value Disabled to the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer\WAU registry subkey. Set this value to 1. If needed, create the Explorer and WAU keys.
Note This guide describes procedures that run scripts and make changes to the registry. These rights can be delegated to selected IT implementers. The rights to change product keys and perform activations can even be assigned to users, although Microsoft does not recommend doing so. Warning Serious problems might occur if you modify the registry incorrectly by using Registry Editor or by using another method. These problems might require that you reinstall the operating system. Microsoft cannot guarantee that these problems can be solved. Modify the registry at your own risk.
Backup is not required for KMS hosts. However, if the event log is used to track or document KMS activations, periodically export the Key Management Service event log from the Applications and Services Logs folder. If using a tool to perform routine cleanup of event logs, the activation history stored in the logs can be lost. If using System Center Operations Manager, the event log data is collected and stored in the System Center Data Warehouse database for reporting, so no backups of the event log are necessary.
Top of Page