認証情報プロバイダの使用 - AWS SDK for PHP

認証情報プロバイダの使用

認証情報プロバイダは、GuzzleHttp\Promise\PromiseInterface インスタンスで満たすかまたは Aws\Credentials\CredentialsInterface で拒否した Aws\Exception\CredentialsException を返す関数です。認証情報プロバイダを使用して、認証情報を作成するための独自のカスタムロジックを実装したり、認証情報のロードを最適化したりできます。

認証情報プロバイダは、クライアントコンストラクタの credentials オプションで渡されます。認証情報プロバイダは非同期であり、API オペレーションが呼び出されるたびに遅延して評価されるようになっています。そのため、認証情報プロバイダ関数を SDK のクライアントコンストラクタに渡しても、その認証情報はすぐには検証されません。認証情報プロバイダから認証情報オブジェクトが返されない場合、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 の組み込みプロバイダ

SDK には複数のプロバイダが組み込まれています。これらを任意のカスタムプロバイダと組み合わせて使用できます。

重要

認証情報プロバイダは、API 操作が実行されるたびに呼び出されます。認証情報をロードすることが負荷の高いタスク (たとえば、ディスクまたはネットワークリソースからのロード) である場合や、認証情報がプロバイダでキャッシュされない場合は、認証情報プロバイダを Aws\Credentials\CredentialProvider::memoize 関数内にラップすることを検討します。SDK で使用されるデフォルトの認証情報プロバイダは自動的にメモ化されます。

assumeRole プロバイダ

Aws\Credentials\AssumeRoleCredentialProvider を使用してロールを継承することによって認証情報を作成する場合は、次に示すように、'client' オブジェクトと StsClient の詳細を使用して 'assume_role_params' 情報を提供する必要があります。

注記

API オペレーションごとに AWS STS の認証情報が取得されることを回避するために、memoize 関数を使用して、認証情報の有効期限が切れたときの認証情報の更新を自動的に処理できます。次のコードを例として参照してください。

use Aws\Credentials\CredentialProvider; 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」を参照してください。

プロバイダーチェーンの作成

Aws\Credentials\CredentialProvider::chain() 関数を使用して、認証情報プロバイダーチェーンを作成できます。この関数は、それぞれが認証情報プロバイダ関数である可変個引数を受け入れます。次に、この関数は、複数の指定した関数を合成した 1 つの新しい関数を返します (各関数は、いずれかのプロバイダから正常に満たされた 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 で拒否した promise (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() ]);

assume role with web identity provider

Aws\Credentials\CredentialProvider::assumeRoleWithWebIdentityCredentialProvider は、ロールを引き受けることで認証情報のロードを試みます。環境変数 AWS_ROLE_ARN および AWS_WEB_IDENTITY_TOKEN_FILE が存在する場合、プロバイダーは、AWS_WEB_IDENTITY_TOKEN_FILE で指定されたフルパスのディスク上のトークンを使用して、AWS_ROLE_ARN で指定されたロールの引き受けを試みます。環境変数が使用された場合、プロバイダーは AWS_ROLE_SESSION_NAME 環境変数からセッションの設定を試みます。

環境変数が設定されていない場合、プロバイダーはデフォルトのプロファイル、または AWS_PROFILE として設定されているプロファイルを使用します。デフォルトでは、プロバイダーは ~/.aws/credentials および ~/.aws/config からプロファイルを読み取り、filename config オプションで指定されたプロファイルから読み取ることができます。プロバイダーはプロファイルの 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 を提供できます。認証情報は、指定された StsClient として false で設定する必要があります。

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 にあるファイルから「default」プロファイルのロードを試行します。

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 にあるファイルから「default」プロファイルのロードを試行します。SDK は指定どおりに 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 ]);

デフォルトでは、プロバイダーは最大 3 回まで認証情報の取得を試みます。再試行の数は retries オプションで設定でき、このオプションを 0 に設定することで完全に無効にできます。

use Aws\Credentials\CredentialProvider; $provider = CredentialProvider::instanceProfile([ 'retries' => 0 ]); $memoizedProvider = CredentialProvider::memoize($provider);
注記

AWS_EC2_METADATA_DISABLED 環境変数を true に設定することによって、Amazon EC2 インスタンスプロファイルからのロードの試行を無効にできます。

認証情報のメモ化

前回の戻り値を記憶している認証情報プロバイダの作成が必要になる場合があります。そのような認証情報プロバイダは、認証情報のロードが負荷の高いオペレーションである場合や、Aws\Sdk クラスを使用して複数のクライアントで 1 つの認証情報プロバイダを共有にする場合に、パフォーマンスを向上させるために便利であることがあります。認証情報プロバイダ関数を 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());

メモ化された認証情報の有効期限が切れると、memoize ラッパーはラップされたプロバイダを呼び出して認証情報の更新を試行します。