本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用第 3 適用於 PHP 的 AWS SDK 版擔任 IAM 角色
## 針對 Amazon EC2 執行個體變數登入資料使用 IAM 角色
如果您在 Amazon EC2 執行個體上執行應用程式，提供憑證以呼叫 的偏好方法是 AWS 使用 [IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)來取得臨時安全憑證。
使用 IAM 角色時，您不需要擔心應用程式的登入資料管理。它們允許執行個體從 Amazon EC2 執行個體的中繼資料伺服器擷取臨時憑證，以「擔任」角色。
暫時登入資料通常稱為**執行個體設定檔登入**資料，允許存取角色政策允許的動作和資源。Amazon EC2 會處理安全向 IAM 服務驗證執行個體以擔任角色的所有工作，並定期重新整理擷取的角色登入資料。這讓您幾乎無需執行任何工作，即可確保應用程式安全。如需可接受臨時安全憑證的服務清單，請參閱《IAM 使用者指南》中的[可搭配 IAM 運作的AWS 服務](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)。**
**注意**
為避免每次都必須連接中繼資料服務，您可將 `Aws\CacheInterface` 執行個體做為 `'credentials'` 選項傳遞至用戶端建構函式。如此可讓開發套件改為使用快取的執行個體描述檔登入資料。如需詳細資訊，請參閱第 [3 版的 適用於 PHP 的 AWS SDK 組態](guide_configuration.md)。
如需使用 SDKs 開發 Amazon EC2 應用程式的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[為 Amazon EC2 執行個體使用 IAM 角色](https://docs.aws.amazon.com/sdkref/latest/guide/access-iam-roles-for-ec2.html)。
### 建立 IAM 角色並將其指派給 Amazon EC2 執行個體
1. 建立 IAM 用戶端。
**匯入**
```
require 'vendor/autoload.php';
use Aws\Iam\IamClient;
```
**範例程式碼**
```
$client = new IamClient([
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
```
1. 建立具有您將使用之動作和資源許可的 IAM 角色。
**範例程式碼**
```
$result = $client->createRole([
'AssumeRolePolicyDocument' => 'IAM JSON Policy', // REQUIRED
'Description' => 'Description of Role',
'RoleName' => 'RoleName', // REQUIRED
]);
```
1. 建立 IAM 執行個體描述檔，並從結果中存放 Amazon Resource Name (ARN)。
**注意**
如果您使用 IAM 主控台而非 適用於 PHP 的 AWS SDK，主控台會自動建立執行個體描述檔，並為其提供與其對應之角色相同的名稱。
**範例程式碼**
```
$IPN = 'InstanceProfileName';
$result = $client->createInstanceProfile([
'InstanceProfileName' => $IPN ,
]);
$ARN = $result['Arn'];
$InstanceID = $result['InstanceProfileId'];
```
1. 建立 Amazon EC2 用戶端。
**匯入**
```
require 'vendor/autoload.php';
use Aws\Ec2\Ec2Client;
```
**範例程式碼**
```
$ec2Client = new Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
]);
```
1. 將執行個體描述檔新增至執行中或已停止的 Amazon EC2 執行個體。使用 IAM 角色的執行個體描述檔名稱。
**範例程式碼**
```
$result = $ec2Client->associateIamInstanceProfile([
'IamInstanceProfile' => [
'Arn' => $ARN,
'Name' => $IPN,
],
'InstanceId' => $InstanceID
]);
```
如需更多詳細資訊，請參閱 *Amazon EC2 使用者指南*中的 [Amazon EC2 的 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)。
## 針對 Amazon ECS 任務使用 IAM 角色
Amazon Elastic Container Service (Amazon ECS) 中的任務可以擔任 IAM 角色來進行 AWS API 呼叫。這是管理應用程式要使用之登入資料的策略，類似於 Amazon EC2 執行個體描述檔如何提供登入資料給 Amazon EC2 執行個體。
您可以將使用臨時 AWS 憑證的 IAM 角色與 ECS 任務定義或 `RunTask` [API](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ecs-2014-11-13.html#runtask) 操作建立關聯，而不是建立和分發長期憑證至容器或使用 Amazon EC2 執行個體的 角色。
如需使用容器任務可擔任之 IAM 角色的詳細資訊，請參閱《*Amazon ECS 開發人員指南*》中的[任務 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)主題。如需在任務定義`taskRoleArn`中以 形式使用任務 IAM 角色的範例，請參閱《*Amazon ECS 開發人員指南*》中的[任務定義範例](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/firelens-example-taskdefs.html)。
## 在另一個 中擔任 IAM 角色 AWS 帳戶
當您使用 AWS 帳戶 （帳戶 A) 並想要在另一個帳戶 （帳戶 B) 中擔任角色時，您必須先在帳戶 B 中建立 IAM 角色。此角色允許帳戶 （帳戶 A) 中的實體在帳戶 B 中執行特定動作。如需跨帳戶存取的詳細資訊，請參閱[教學課程：使用 IAM 角色跨 AWS 帳戶委派存取權](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)。
在帳戶 B 中建立角色後，請記下角色 ARN。當您從帳戶 A 擔任角色時，您將使用此 ARN。您使用帳戶 A 中與您的實體相關聯的 AWS 登入資料來擔任角色。
使用 的登入資料建立 AWS STS 用戶端 AWS 帳戶。在下文中我們使用登入資料設定檔，但您可以使用任何方法。對於新建立的 AWS STS 用戶端，呼叫 assume-role 並提供自訂 sessionName。擷取結果中的新臨時登入資料。根據預設，登入資料會持續一小時。
**範例程式碼**
```
$stsClient = new Aws\Sts\StsClient([
'profile' => 'default',
'region' => 'us-east-2',
'version' => '2011-06-15'
]);
$ARN = "arn:aws:iam::123456789012:role/xaccounts3access";
$sessionName = "s3-access-example";
$result = $stsClient->AssumeRole([
'RoleArn' => $ARN,
'RoleSessionName' => $sessionName,
]);
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => 'us-west-2',
'credentials' => [
'key' => $result['Credentials']['AccessKeyId'],
'secret' => $result['Credentials']['SecretAccessKey'],
'token' => $result['Credentials']['SessionToken']
]
]);
```
如需詳細資訊，請參閱 適用於 PHP 的 AWS SDK API [參考中的使用 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)或 [AssumeRole](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerole)。
## 使用具有 Web 身分的 IAM 角色
Web Identity Federation 可讓客戶在存取 AWS 資源時使用第三方身分提供者進行身分驗證。您必須先建立 IAM 角色並設定 Web 身分提供者 (IdP)，然後才能擔任具有 Web 身分的角色。如需詳細資訊，請參閱[建立 Web 身分的角色或 OpenID Connect 聯合身分 (主控台)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)。
[建立身分提供者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)並[為您的 Web 身分建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html)之後，請使用 AWS STS 用戶端來驗證使用者。為您的身分提供 webIdentityToken 和 ProviderId，以及為使用者提供具有許可之 IAM 角色的角色 ARN。
**範例程式碼**
```
$stsClient = new Aws\Sts\StsClient([
'profile' => 'default',
'region' => 'us-east-2',
'version' => '2011-06-15'
]);
$ARN = "arn:aws:iam::123456789012:role/xaccounts3access";
$sessionName = "s3-access-example";
$duration = 3600;
$result = $stsClient->AssumeRoleWithWebIdentity([
'WebIdentityToken' => "FACEBOOK_ACCESS_TOKEN",
'ProviderId' => "graph.facebook.com",
'RoleArn' => $ARN,
'RoleSessionName' => $sessionName,
]);
$s3Client = new S3Client([
'version' => '2006-03-01',
'region' => 'us-west-2',
'credentials' => [
'key' => $result['Credentials']['AccessKeyId'],
'secret' => $result['Credentials']['SecretAccessKey'],
'token' => $result['Credentials']['SessionToken']
]
]);
```
如需詳細資訊，請參閱 適用於 PHP 的 AWS SDK API 參考中的 [AssumeRoleWithWebIdentity—透過 Web 型身分提供者的聯合](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerolewithwebidentity.html)或 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerolewithwebidentity)。
## 使用設定檔擔任角色
### 在 中定義設定檔 `~/.aws/credentials`
您可以透過在 中定義設定檔， 適用於 PHP 的 AWS SDK 將 設定為使用 IAM 角色`~/.aws/credentials`。
使用您要擔任之角色`role_arn`的設定建立新的設定檔。也包含另一個設定檔`source_profile`的設定，其登入資料具有擔任 IAM 角色的許可。如需這些組態設定的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[擔任角色登入](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html)資料。
例如，在下列 中`~/.aws/credentials`，`project1`設定檔會設定 `role_arn`，並將`default`設定檔指定為登入資料的來源，以確認與其相關聯的實體可以擔任該角色。
```
[project1]
role_arn = arn:aws:iam::123456789012:role/testing
source_profile = default
role_session_name = OPTIONAL_SESSION_NAME
[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY
aws_session_token= YOUR_AWS_SESSION_TOKEN
```
如果您設定`AWS_PROFILE`環境變數，或在執行個體化服務用戶端時使用 `profile` 參數，`project1`則會使用`default`設定檔做為來源登入資料，擔任 中指定的角色。
下列程式碼片段顯示 `S3Client`建構函數中使用 `profile` 參數。`S3Client` 將具有與`project1`設定檔相關聯之角色相關聯的許可。
```
$s3 = new Aws\S3\S3Client([
'region' => 'us-east-1',
'version' => '2006-03-01',
'profile' => 'project1'
]);
```
### 在 中定義設定檔 `~/.aws/config`
`~/.aws/config` 檔案也可以包含您要擔任的設定檔。如果您設定環境變數 `AWS_SDK_LOAD_NONDEFAULT_CONFIG`，適用於 PHP 的 SDK 會從 `config` 檔案載入設定檔。設定 `AWS_SDK_LOAD_NONDEFAULT_CONFIG` 時，軟體開發套件會從 `~/.aws/config`和 載入設定檔`~/.aws/credentials`。來自 的設定檔`~/.aws/credentials`最後載入，優先於`~/.aws/config`具有相同名稱的 設定檔。來自任一位置的設定檔都能做為 `source_profile` 或要擔任的設定檔。
下列範例使用 `config` 檔案中定義的 `project1` 設定檔和 `credentials` 檔案中的 `default`設定檔。`AWS_SDK_LOAD_NONDEFAULT_CONFIG` 也會設定 。
```
# Profile in ~/.aws/config.
[profile project1]
role_arn = arn:aws:iam::123456789012:role/testing
source_profile = default
role_session_name = OPTIONAL_SESSION_NAME
```
```
# Profile in ~/.aws/credentials.
[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY
aws_session_token= YOUR_AWS_SESSION_TOKEN
```
當`S3Client`建構函數執行並顯示下列程式碼片段時，將使用與`project1`設定檔相關聯的登入資料來擔任`default`設定檔中定義的 角色。
```
$s3 = new Aws\S3\S3Client([
'region' => 'us-east-1',
'version' => '2006-03-01',
'profile' => 'project1'
]);
```