AWS SDK for PHP
Developer Guide

Assuming IAM Roles

Using IAM Roles for Amazon EC2 Instance Variable Credentials

If you're running your application on an Amazon EC2 instance, the preferred way to provide credentials to make calls to AWS is to use an IAM role to get temporary security credentials.

When you use IAM roles, you don't need to worry about credential management from your application. They allow an instance to "assume" a role by retrieving temporary credentials from the Amazon EC2 instance's metadata server.

The temporary credentials, often referred to as instance profile credentials, allow access to the actions and resources that the role's policy allows. Amazon EC2 handles all the legwork of securely authenticating instances to the IAM service to assume the role, and periodically refreshing the retrieved role credentials. This keeps your application secure with almost no work on your part.

Note

Instance profile credentials and other temporary credentials generated by the AWS Security Token Service (AWS STS) are not supported by every service. To determine whether the service you're using supports temporary credentials, see AWS Services that Support AWS STS.

To avoid hitting the metadata service every time, you can pass an instance of Aws\CacheInterface in as the 'credentials' option to a client constructor. This lets the SDK use cached instance profile credentials instead. For details, see Configuration for the AWS SDK for PHP Version 3.

Create and assign IAM role to an Amazon EC2 Instance

  1. Create an IAM client.

    Imports

    require 'vendor/autoload.php'; use Aws\Iam\IamClient;

    Sample Code

    $client = new IamClient([ 'region' => 'us-west-2', 'version' => '2010-05-08' ]);
  2. Create an IAM role with the permissions for the actions and resources you'll use.

    Sample Code

    $result = $client->createRole([ 'AssumeRolePolicyDocument' => 'IAM JSON Policy', // REQUIRED 'Description' => 'Description of Role', 'RoleName' => 'RoleName', // REQUIRED ]);
  3. Create an IAM instance profile and store the Amazon Resource Name (ARN) from the result.

    Note

    If you use the IAM console instead of the AWS SDK for PHP, the console creates an instance profile automatically and gives it the same name as the role to which it corresponds.

    Sample Code

    $IPN = 'InstanceProfileName'; $result = $client->createInstanceProfile([ 'InstanceProfileName' => $IPN , ]); $ARN = $result['Arn']; $InstanceID = $result['InstanceProfileId'];
  4. Create an Amazon EC2 client.

    Imports

    require 'vendor/autoload.php'; use Aws\Ec2\Ec2Client;

    Sample Code

    $ec2Client = new Ec2Client([ 'region' => 'us-west-2', 'version' => '2016-11-15', ]);
  5. Add the instance profile to a running or stopped Amazon EC2 instance. Use the instance profile name of your IAM role.

    Sample Code

    $result = $ec2Client->associateIamInstanceProfile([ 'IamInstanceProfile' => [ 'Arn' => $ARN 'Name' => $IPN, ], 'InstanceId' => $InstanceID ]);

For more information, see IAM Roles for Amazon EC2.

Using IAM Roles for Amazon ECS Tasks

By using IAM roles for Amazon Elastic Container Service (Amazon ECS) tasks, you can specify an IAM role that the containers in a task can use. This is a strategy for managing credentials for your applications to use, similar to the way that Amazon EC2 instance profiles provide credentials to Amazon EC2 instances.

Instead of creating and distributing your AWS credentials to the containers or using the Amazon EC2 instance’s role, you can associate an IAM role with an ECS task definition or RunTask API operation.

Note

Instance profile credentials and other temporary credentials generated by AWS STS are not supported by every service. To determine whether the service you're using supports temporary credentials, see AWS Services that Support AWS STS.

For more information, see IAM Roles for Amazon EC2 Container Service Tasks.