使用認證提供者 - AWS SDK for PHP
開發套件中的內建供應商assumeRole 供應商SSO 供應商鏈接提供者建立自訂提供者defaultProvider 供應商ecsCredentials 供應商env 供應商assumeRoleWithWebIdentityCredentialProvider 供應商ini 供應商程序供應商instanceProfile 供應商記憶憑證

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用認證提供者

登入資料供應商是一個函數，會傳回一個 GuzzleHttp\Promise\PromiseInterface，其中包含 Aws\Credentials\CredentialsInterface 執行個體，或被退回並包含 Aws\Exception\CredentialsException。您可以使用登入資料供應商實作您自己的自訂邏輯，以建立登入資料或最佳化登入資料載入。

登入資料供應商會傳送至 credentials 用戶端建構函式選項。登入資料供應商為非同步，會在每次叫用 API 操作時，強制其進行延遲評估。因此，將登入資料提供者函數傳遞到軟體開發套件用戶端建構函數，不會立即驗證登入資料。如果登入資料提供者未傳回登入資料物件，API 操作將會遭到拒絕，並且其回應為 Aws\Exception\CredentialsException。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

// Use the default credential provider
$provider = CredentialProvider::defaultProvider();

// Pass the provider to the client
$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

開發套件中的內建供應商

開發套件提供多個內建的供應商，您可結合使用任何自訂供應商。有關在 SDK 中配置標準化提供者和憑證提供者鏈的詳細資訊，請參閱 AWS AWS SDK 和工具參考指南中的標準化憑證提供者。

重要

每次執行 API 操作時，都會叫用登入資料供應商。如果載入登入資料是昂貴的任務 (例如，從磁碟或網路資源載入)，或如果登入資料並未由您的供應商快取，請考慮將登入資料供應商封裝在 Aws\Credentials\CredentialProvider::memoize 函數中。開發套件使用的預設登入資料供應商會自動記憶。

assumeRole 供應商

如果您使用 Aws\Credentials\AssumeRoleCredentialProvider 藉由採用角色來建立登入資料，您必須提供 'client' 資訊以及 StsClient 物件和 'assume_role_params' 詳細資訊，如下所示。

注意

若要避免在每個 API 作業中不必要地擷取 AWS STS 認證，您可以使用該memoize函數在認證到期時自動重新整理憑證。如需範例，請參閱下列程式碼。

use Aws\Credentials\CredentialProvider;
use Aws\Credentials\InstanceProfileProvider;
use Aws\Credentials\AssumeRoleCredentialProvider;
use Aws\S3\S3Client;
use Aws\Sts\StsClient;

// Passing Aws\Credentials\AssumeRoleCredentialProvider options directly
$profile = new InstanceProfileProvider();
$ARN = "arn:aws:iam::123456789012:role/xaccounts3access";
$sessionName = "s3-access-example";

$assumeRoleCredentials = new AssumeRoleCredentialProvider([
    'client' => new StsClient([
        'region' => 'us-east-2',
        'version' => '2011-06-15',
        'credentials' => $profile
    ]),
    'assume_role_params' => [
        'RoleArn' => $ARN,
        'RoleSessionName' => $sessionName,
    ],
]);

// To avoid unnecessarily fetching STS credentials on every API operation,
// the memoize function handles automatically refreshing the credentials when they expire
$provider = CredentialProvider::memoize($assumeRoleCredentials);

$client = new S3Client([
    'region'      => 'us-east-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

如需有關的更多資訊'assume_role_params'，請參閱AssumeRole。

SSO 供應商

Aws\Credentials\CredentialProvider::sso是單一登入認證提供者。此提供者也稱為 AWS IAM Identity Center 認證提供者。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

$credentials = new Aws\CredentialProvider::sso('profile default');

$s3 = new Aws\S3\S3Client([
    'version'     => 'latest',
    'region'      => 'us-west-2',
    'credentials' => $credentials
]);

如果您使用具名的設定檔，請在上一個範例中將您的設定檔名稱替換為 default ''。若要深入瞭解如何設定命名設定檔，請參閱 AWS SDK config 和工具參考指南中的共用和檔credentials案。或者，您可以使用AWS_PROFILE環境變數來指定要使用的設定檔設定。

若要深入瞭解 IAM 身分中心提供者的運作方式，請參閱 AWS SDK 和工具參考指南中的了解 IAM 身分中心身分驗證。

鏈接提供者

您可使用 Aws\Credentials\CredentialProvider::chain() 函數來鏈結登入資料供應商。此函數接受 variadic 數量的引數，每個引數皆為登入資料供應商函數。此函數會傳回一個新的函數，這個新函數由提供的函數組成，並且會逐一呼叫，直到其中一個提供者傳回已成功履行的 promise。

defaultProvider 使用此結構在失敗之前檢查多個供應商。defaultProvider 的來源示範如何使用 chain 函數。

// This function returns a provider
public static function defaultProvider(array $config = [])
{
    // This function is the provider, which is actually the composition
    // of multiple providers. Notice that we are also memoizing the result by
    // default.
    return self::memoize(
        self::chain(
            self::env(),
            self::ini(),
            self::instanceProfile($config)
        )
    );
}

建立自訂提供者

登入資料供應商是簡單的函數，被叫用時會傳回承諾 (GuzzleHttp\Promise\PromiseInterface)，其中包含 Aws\Credentials\CredentialsInterface 物件，或被退回並包含 Aws\Exception\CredentialsException。

建立供應商的最佳實務是建立函數，此函數被叫用時間和建立實際的登入資料供應商。例如，以下是 env 提供者的來源 (為了示範用途而有稍做修改)。請注意，這是一個函數，會傳回實際的供應商函數。這可讓您輕鬆地撰寫登入資料供應商，並傳遞它們做為值。

use GuzzleHttp\Promise;
use GuzzleHttp\Promise\RejectedPromise;

// This function CREATES a credential provider
public static function env()
{
    // This function IS the credential provider
    return function () {
        // Use credentials from environment variables, if available
        $key = getenv(self::ENV_KEY);
        $secret = getenv(self::ENV_SECRET);
        if ($key && $secret) {
            return Promise\promise_for(
                new Credentials($key, $secret, getenv(self::ENV_SESSION))
            );
        }

        $msg = 'Could not find environment variable '
            . 'credentials in ' . self::ENV_KEY . '/' . self::ENV_SECRET;
        return new RejectedPromise(new CredentialsException($msg));
    };
}

defaultProvider 供應商

Aws\Credentials\CredentialProvider::defaultProvider 為預設的登入資料供應商。如果在建立用戶端時省略 credentials 選項，將會使用此供應商。它會先嘗試從環境變數載入登入資料，然後從 .ini 檔案 (首先是 .aws/credentials 檔案，接著是 .aws/config 檔案)，然後從執行個體描述檔 (首先是 EcsCredentials，接著是 Ec2 中繼資料)。

注意

預設供應商的結果會自動記憶。

ecsCredentials 供應商

Aws\Credentials\CredentialProvider::ecsCredentials 嘗試以 GET 請求載入登入資料，其 URI 由容器中的環境變數 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI 指定。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

$provider = CredentialProvider::ecsCredentials();
// Be sure to memoize the credentials
$memoizedProvider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $memoizedProvider
]);

env 供應商

Aws\Credentials\CredentialProvider::env 嘗試從環境變數載入登入資料。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => CredentialProvider::env()
]);

assumeRoleWithWebIdentityCredentialProvider 供應商

Aws\Credentials\CredentialProvider::assumeRoleWithWebIdentityCredentialProvider 嘗試透過擔任角色載入登入資料。如果環境變數 AWS_ROLE_ARN 和 AWS_WEB_IDENTITY_TOKEN_FILE 存在，供應商將嘗試使用磁碟上的字符擔任 AWS_ROLE_ARN 中指定的角色，而此字符位於 AWS_WEB_IDENTITY_TOKEN_FILE 中指定的完整路徑。如果使用環境變數，供應商將嘗試從 AWS_ROLE_SESSION_NAME 環境變數設定工作階段。

如果未設定環境變數，提供者將使用預設設定檔，或設定為 AWS_PROFILE 的設定檔。根據預設，供應商會從 ~/.aws/config 和 ~/.aws/credentials 讀取設定檔，而且可從 filename 組態選項中指定的設定檔讀取。供應商將擔任設定檔的 role_arn 中的角色，從 web_identity_token_file 中設定的完整路徑讀取字符。如果設定在設定檔上，將使用 role_session_name。

供應商會做為預設鏈的一部分進行呼叫，也可以直接呼叫。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

$provider = CredentialProvider::assumeRoleWithWebIdentityCredentialProvider();
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

根據預設，此認證提供者將繼承已設定的區域，該區域將用 StsClient 來擔任角色。或者， StsClient 可以提供一個完整的。憑據應按照提供false的任何設置 StsClient。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;
use Aws\Sts\StsClient;

$stsClient = new StsClient([
    'region'      => 'us-west-2',
    'version'     => 'latest',
    'credentials' => false
])

$provider = CredentialProvider::assumeRoleWithWebIdentityCredentialProvider([
    'stsClient' => $stsClient
]);
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

ini 供應商

Aws\Credentials\CredentialProvider::ini 會嘗試從 ini 登入資料檔案載入登入資料。依預設，SDK 會嘗試從位於的共用 AWS credentials檔案載入「預設」設定檔~/.aws/credentials。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

$provider = CredentialProvider::ini();
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

您可以將引數提供給建立供應商的函數，以使用自訂描述檔或 .ini 檔案位置。

$profile = 'production';
$path = '/full/path/to/credentials.ini';

$provider = CredentialProvider::ini($profile, $path);
$provider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

程序供應商

Aws\Credentials\CredentialProvider::process 嘗試從 ini 登入資料檔案中指定的 credential_process 載入登入資料。依預設，SDK 會嘗試從位於的共用 AWS credentials檔案載入「預設」設定檔~/.aws/credentials。軟體開發套件會完全符合指定呼叫 credential_process 命令，然後從 stdout 讀取 JSON 資料。credential_process 必須以下列格式將登入資料寫入 stdout：

{
    "Version": 1,
    "AccessKeyId": "",
    "SecretAccessKey": "",
    "SessionToken": "",
    "Expiration": ""
}

SessionToken 和 Expiration 為選用。如果存在，則該登入資料會被視為臨時。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

$provider = CredentialProvider::process();
// Cache the results in a memoize function to avoid loading and parsing
// the ini file on every API operation
$provider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

您可以將引數提供給建立供應商的函數，以使用自訂描述檔或 .ini 檔案位置。

$profile = 'production';
$path = '/full/path/to/credentials.ini';

$provider = CredentialProvider::process($profile, $path);
$provider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $provider
]);

instanceProfile 供應商

Aws\Credentials\CredentialProvider::instanceProfile嘗試從 Amazon EC2 執行個體設定檔載入登入資料。

use Aws\Credentials\CredentialProvider;
use Aws\S3\S3Client;

$provider = CredentialProvider::instanceProfile();
// Be sure to memoize the credentials
$memoizedProvider = CredentialProvider::memoize($provider);

$client = new S3Client([
    'region'      => 'us-west-2',
    'version'     => '2006-03-01',
    'credentials' => $memoizedProvider
]);

根據預設，供應商會重試擷取登入資料，最多三次。您可以使用 retries 選項，來設定重試次數，以及將此選項設定為 0 以完整停用。

use Aws\Credentials\CredentialProvider;

$provider = CredentialProvider::instanceProfile([
    'retries' => 0
]);
$memoizedProvider = CredentialProvider::memoize($provider);
注意

您可以將AWS_EC2_METADATA_DISABLED環境變數設定為，停用從 Amazon EC2 執行個體設定檔載入的嘗試true。

記憶憑證

有時您可能需要建立能記憶先前傳回值的登入資料供應商。如果載入登入資料是昂貴的操作，或使用 Aws\Sdk 類別跨多個用戶端共用登入資料供應商時，這將會很有用。您可以藉由將登入資料供應商函數包裝在 memoize 函數中，將記憶功能新增至登入資料供應商。

use Aws\Credentials\CredentialProvider;

$provider = CredentialProvider::instanceProfile();
// Wrap the actual provider in a memoize function
$provider = CredentialProvider::memoize($provider);

// Pass the provider into the Sdk class and share the provider
// across multiple clients. Each time a new client is constructed,
// it will use the previously returned credentials as long as
// they haven't yet expired.
$sdk = new Aws\Sdk(['credentials' => $provider]);

$s3 = $sdk->getS3(['region' => 'us-west-2', 'version' => 'latest']);
$ec2 = $sdk->getEc2(['region' => 'us-west-2', 'version' => 'latest']);

assert($s3->getCredentials() === $ec2->getCredentials());

當記憶的登入資料過期時，記憶包裝函式會叫用包裝的供應商，以嘗試重新整理登入資料。