Provedores integrados no SDK provedor assumeRole Provedor de SSO Encadeamento de provedores Criação de um provedor personalizado provedor defaultProvider provedor ecsCredentials provedor env assumeRoleWithWebIdentityCredentialProvider provedor provedor ini provedor de processo provedor instanceProfile Memoização de credenciais

Usar um provedor de credenciais

Um provedor de credenciais é uma função que retorna uma GuzzleHttp\Promise\PromiseInterface que é cumprida com uma instância de Aws\Credentials\CredentialsInterface ou rejeitada com uma Aws\Exception\CredentialsException. Você pode usar provedores de credenciais para implementar sua própria lógica personalizada para criar credenciais ou para otimizar o carregamento de credenciais.

Os provedores de credenciais são passados para a opção do construtor de clientes credentials. Os provedores de credenciais são assíncronos, o que os força a serem avaliados lentamente a cada vez que uma operação de API é invocada. Como tal, a passagem de uma função de provedor de credenciais para um construtor de cliente do SDK não valida imediatamente as credenciais. Se o provedor de credenciais não retornar um objeto de credenciais, uma operação da API será rejeitada com uma 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
]);

Provedores integrados no SDK

O SDK fornece vários provedores integrados que podem ser combinados com todos os provedores personalizados. Para obter mais informações sobre como configurar os provedores padronizados e a cadeia de fornecedores de credenciais nos AWS SDKs, consulte Provedores de credenciais padronizados no Guia de referência de SDKs e ferramentas.AWS

Importante

Os provedores de credenciais são invocados sempre que uma operação da API é realizada. Se o carregamento de credenciais for uma tarefa cara (por exemplo, o carregamento do disco ou de um recurso de rede) ou se as credenciais não estiverem armazenadas em cache pelo provedor, considere dispor o provedor de credenciais em uma função Aws\Credentials\CredentialProvider::memoize. O provedor de credenciais padrão usado pelo SDK é automaticamente memoizado.

provedor assumeRole

Se você usar Aws\Credentials\AssumeRoleCredentialProvider para criar credenciais assumindo uma função, você precisa fornecer 'client' informações com um objeto StsClient e detalhes de 'assume_role_params', conforme mostrado.

nota

Para evitar a busca desnecessária de AWS STS credenciais em cada operação de API, você pode usar a memoize função para gerenciar a atualização automática das credenciais quando elas expirarem. Consulte o código a seguir para ver um exemplo.


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
]);

Para obter mais informações sobre'assume_role_params', consulte AssumeRole.

Provedor de SSO

Aws\Credentials\CredentialProvider::ssoé o provedor de credenciais de login único. Esse provedor também é conhecido como provedor de AWS IAM Identity Center credenciais.


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
]);

Se você usar um perfil nomeado, substitua o nome do seu perfil por “default” no exemplo anterior. Para saber mais sobre como configurar perfis nomeados, consulte Arquivos compartilhados config e credentials no Guia de referência de SDKs e ferramentas da AWS . Como alternativa, você pode usar a variável de ambiente AWS_PROFILE para especificar quais configurações do perfil usar.

Para entender mais como o provedor do Centro de Identidade do IAM funciona, consulte Compreender a autenticação do Centro de Identidade do IAM no Guia de referência de SDKs e ferramentas da AWS .

Encadeamento de provedores

Você pode encadear os provedores de credenciais usando a função Aws\Credentials\CredentialProvider::chain(). Essa função aceita um número de argumentos variadic, cada um dos quais são funções do provedor de credenciais. Essa função retorna uma nova função que é a composição das funções fornecidas, de forma que elas sejam invocadas uma depois da outra, até que um dos provedores retorne uma promessa que seja cumprida com êxito.

O defaultProvider usa essa composição para verificar vários provedores antes de falhar. A origem do defaultProvider demonstra o uso da função 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)
        )
    );
}

Criação de um provedor personalizado

Os provedores de credenciais são simplesmente funções que quando invocadas retornam uma promessa (GuzzleHttp\Promise\PromiseInterface) que é cumprida com um objeto Aws\Credentials\CredentialsInterface ou rejeitada com uma Aws\Exception\CredentialsException.

Uma prática recomendada para criar provedores é criar uma função que é invocada para criar o provedor de credenciais real. Como exemplo, veja a origem do provedor env (levemente modificada para fins de exemplo). Observe que é uma função que retorna a função do provedor real. Isso permite que você componha facilmente provedores de credenciais e distribua-os como valores.


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));
    };
}

provedor defaultProvider

Aws\Credentials\CredentialProvider::defaultProvider é o provedor de credenciais padrão. Esse provedor é usado se você omitir uma opção credentials ao criar um cliente. Primeiro, ele tenta carregar as credenciais das variáveis de ambiente, em seguida, de um arquivo .ini (um arquivo .aws/credentials primeiro, seguido por um arquivo .aws/config) e, em seguida, de um perfil de instância (EcsCredentials primeiro, seguido por metadados do Ec2).

nota

O resultado do provedor padrão é automaticamente memoizado.

provedor ecsCredentials

Aws\Credentials\CredentialProvider::ecsCredentials tenta carregar credenciais por uma solicitação GET, cujo URI é especificado pela variável de ambiente AWS_CONTAINER_CREDENTIALS_RELATIVE_URI no contêiner.


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
]);

provedor env

Aws\Credentials\CredentialProvider::env tenta carregar credenciais a partir de variáveis de ambiente.


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

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

assumeRoleWithWebIdentityCredentialProvider provedor

Aws\Credentials\CredentialProvider::assumeRoleWithWebIdentityCredentialProvider tenta carregar credenciais assumindo uma função. Se as variáveis de ambiente AWS_ROLE_ARN e AWS_WEB_IDENTITY_TOKEN_FILE estiverem presentes, o provedor tentará assumir a função especificada no AWS_ROLE_ARN usando o token no disco no caminho completo especificado em AWS_WEB_IDENTITY_TOKEN_FILE. Se as variáveis de ambiente forem usadas, o provedor tentará definir a sessão na variável de ambiente AWS_ROLE_SESSION_NAME.

Se as variáveis de ambiente não estiverem definidas, o provedor usará o perfil padrão ou o definido como AWS_PROFILE. O provedor lê perfis de ~/.aws/credentials e ~/.aws/config por padrão, e pode ler de perfis especificados na opção de configuração filename. O provedor assumirá a função no role_arn do perfil lendo um token do caminho completo definido no web_identity_token_file. O role_session_name será usado se definido no perfil.

O provedor será chamado como parte da cadeia padrão e poderá ser chamado diretamente.


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
]);

Por padrão, esse provedor de credenciais herdará a região configurada que será usada pelo StsClient para assumir a função. Opcionalmente, um completo StsClient pode ser fornecido. As credenciais devem ser definidas conforme false as fornecidas 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
]);

provedor ini

Aws\Credentials\CredentialProvider::ini tenta carregar credenciais de um arquivo de credenciais ini. Por padrão, o SDK tenta carregar o perfil “padrão” do AWS credentials arquivo compartilhado localizado em~/.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
]);

Você pode usar um perfil personalizado ou o local de um arquivo .ini fornecendo argumentos à função que cria o provedor.


$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
]);

provedor de processo

Aws\Credentials\CredentialProvider::process tenta carregar credenciais de um credential_process especificado em um arquivo de credenciais ini. Por padrão, o SDK tenta carregar o perfil “padrão” do AWS credentials arquivo compartilhado localizado em~/.aws/credentials. O SDK chamará o comando credential_process exatamente como determinado e, em seguida, lerá dados JSON de stdout. O credential_process deve gravar as credenciais no stdout no seguinte formato:


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

SessionToken e Expiration são opcionais. Se presente, as credenciais serão tratadas como temporárias.


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
]);

Você pode usar um perfil personalizado ou o local de um arquivo .ini fornecendo argumentos à função que cria o provedor.


$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
]);

provedor instanceProfile

Aws\Credentials\CredentialProvider::instanceProfile tenta carregar credenciais a partir de perfis de instâncias do 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
]);

Por padrão, o provedor de credenciais tentará obter as credenciais três vezes. O número de novas tentativas pode ser definido com a opção retries e desabilitado inteiramente definindo a opção como 0.


use Aws\Credentials\CredentialProvider;

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

nota

Você pode desabilitar essa tentativa de carga em perfis de instâncias do Amazon EC2 definindo a variável de ambiente AWS_EC2_METADATA_DISABLED como true.

Memoização de credenciais

Às vezes, pode ser necessário criar um provedor de credenciais que lembre o valor de retorno anterior. Isso pode ser útil para o desempenho quando o carregamento de credenciais é uma operação cara ou ao usar a classe Aws\Sdk para compartilhar um provedor de credenciais entre vários clientes. Você pode adicionar memoização a um provedor de credenciais integrando a função de provedor de credenciais em uma função 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());

Quando as credenciais memoizadas expiram, o wrapper de memoização invoca o provedor encapsulado em uma tentativa de atualizar as credenciais.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Assuma uma IAM função

Use credenciais temporárias de AWS STS