# Built-in credential providers in the AWS SDK for PHP Version 3
<a name="built-in-providers-in-the-sdk"></a>

The SDK provides several built-in credential providers that you can use individually or combine in a [custom credential provider chain](chaining-providers.md). 

When you specify a credential provider during service client creation, the SDK attempts to load credentials by using only the specified credential provider. It does not use the [default credential provider chain](guide_credentials_default_chain.md). If you know that you want a service client to use the `instanceProfile` provider, you can short-circuit the default chain by specifying the `instanceProfile` provider in the service client constructor:

```
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',
    'credentials' => $memoizedProvider  // The default credential provider chain is not used.
]);
```

**Important**  
Credential providers are invoked every time an API operation is performed. If loading credentials is an expensive task (e.g., loading from disk or a network resource), or if credentials are not cached by your provider, consider wrapping your credential provider in an `Aws\Credentials\CredentialProvider::memoize` function. The default credential provider used by the SDK is automatically memoized.

**Topics**
+ [`login` provider in the SDK for PHP](login-provider.md)
+ [`assumeRole` provider in the SDK for PHP](assumerole-provider.md)
+ [`sso` provider in the SDK for PHP](sso-provider.md)
+ [`defaultProvider` provider in the SDK for PHP](defaultprovider-provider.md)
+ [`ecsCredentials` provider in the SDK for PHP](ecscredentials-provider.md)
+ [`env` provider in the SDK for PHP](env-provider.md)
+ [`assumeRoleWithWebIdentityCredentialProvider` provider in the SDK for PHP](assume-role-with-web-identity-provider.md)
+ [`ini` provider in the SDK for PHP](ini-provider.md)
+ [`process` provider in the SDK for PHP](process-provider.md)
+ [`instanceProfile` provider in the SDK for PHP](instanceprofile-provider.md)

# `login` provider in the SDK for PHP
<a name="login-provider"></a>

`Aws\Credentials\CredentialProvider::login` attempts to load credentials configured by a browser-based login session facilitated by tools like the AWS CLI. After authentication, AWS generates temporary credentials that work across local AWS SDKs and tools.

With this process, you can authenticate using root credentials created during initial account set up, an IAM user, or a federated identity from your identity provider, and the AWS SDK for PHP automatically manage the temporary credentials for you. This approach enhances security by eliminating the need to store long-term credentials locally.

When you run the `aws login` command, you can select from your active console sessions, or sign in through the browser-based authentication flow and this will automatically generate temporary credentials. The AWS SDK for PHP will automatically refresh these credentials, using the Sign-In service, for up to 12 hours.

The login provider attempts to load the access token generated by the previously mentioned login session workflow, based on the profile provided. If no profile is provided when calling the provider, it will attempt to resolve a profile by first checking the `AWS_PROFILE` environment variable, before falling back to the profile `default`. In-code configuration can be passed to the provider, where it will look for a `region` value for the Sign-In service client used for refreshing credentials. If no region is provided in the configuration array, the provider will attempt to resolve a region by checking the `AWS_REGION` environment variable, then a region value set in the resolved profile. If no region can be found, the provider will return a rejected promise with instructions on how to configure a region.

The provider is called as a part of the default chain and can be called directly.

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

$provider = CredentialProvider::login(<profile_name>, ['region' => <region>]);
// 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',
    'credentials' => $provider
]);
```

By default, if no credentials configuration is provided on the service client you wish to use, this provider will be called as a part of the `defaultProvider()` credentials chain. In this scenario, the region of the service client is automatically passed to the `login()` provider. Also in this scenario, the profile value passed to the login provider will be resolved by checking the `AWS_PROFILE` environment variable, before falling back to the profile `default`.

# `assumeRole` provider in the SDK for PHP
<a name="assumerole-provider"></a>

If you use `Aws\Credentials\AssumeRoleCredentialProvider` to create credentials by assuming a role, you need to provide `'client'` information with an `StsClient` object and `'assume_role_params'` details, as shown.

**Note**  
To avoid unnecessarily fetching AWS STS credentials on every API operation, you can use the `memoize` function to handle automatically refreshing the credentials when they expire. See the following code for an example.

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

For more information regarding `'assume_role_params'`, see [AssumeRole](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerole).

# `sso` provider in the SDK for PHP
<a name="sso-provider"></a>

`Aws\Credentials\CredentialProvider::sso` is the single sign-on credential provider. This provider is also known as the AWS IAM Identity Center credential provider.

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

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

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

If you use a named profile, substitute the name of your profile for ‘`default`’ in the previous example. To learn more about setting up named profiles, see [Shared `config` and `credentials` files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) in the *AWS SDKs and Tools Reference Guide*. Alternatively, you can use the [https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile) environment variable to specify which profile's settings to use. 

To understand more how the IAM Identity Center provider works, see [Understand IAM Identity Center authentication](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) in the *AWS SDKs and Tools Reference Guide*.

# `defaultProvider` provider in the SDK for PHP
<a name="defaultprovider-provider"></a>

 `Aws\Credentials\CredentialProvider::defaultProvider` is the default credential provider and is also called the [default credential provider chain](guide_credentials_default_chain.md). This provider is used if you omit a `credentials` option when creating a client. For example, if you create an S3Client as shown in the following snippet, the SDK uses the default provider:

```
$client = new S3Client([
    'region' => 'us-west-2'
]);
```

You can also use the defaultProvider in code if you want to supply parameters to specific credential providers in the chain. For example the following example provides custom connection timeout and retry settings if the `ecsCredentials` provider function is used.

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

$provider = CredentialProvider::defaultProvider([
    'timeout' => '1.5',
    'retries' => 5
]);

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

# `ecsCredentials` provider in the SDK for PHP
<a name="ecscredentials-provider"></a>

 `Aws\Credentials\CredentialProvider::ecsCredentials` attempts to load credentials by a `GET` request, whose URI is specified by the environment variable `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` in the container.

```
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` provider in the SDK for PHP
<a name="env-provider"></a>

Using environment variables to contain your credentials prevents you from accidentally sharing your AWS secret access key. We recommend that you never add your AWS access keys directly to the client in any production files.

To authenticate to Amazon Web Services, the SDK first checks for credentials in your environment variables. The SDK uses the `getenv()` function to look for the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables. These credentials are referred to as environment credentials. For instructions on how to obtain these values, see [Authenticate using short-term credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access-temp-idc.html) in the *AWS SDKs and Tools Reference Guide*.

If you’re hosting your application on [AWS Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_PHP_eb.html), you can set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_KEY`, and `AWS_SESSION_TOKEN` environment variables [through the AWS Elastic Beanstalk console](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-cfg-softwaresettings.html#environments-cfg-softwaresettings-console) so that the SDK can use those credentials automatically.

For more information on how to set environment variables, see [Environment variables support](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) in the *AWS SDKs and Tools Reference Guide*. Also, for a list of all environment variables supported by most AWS SDKs, see [Environment variables list](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#EVarSettings).

You can also set the environment variables in the command line, as shown here.

 **Linux** 

```
$ export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
   # The access key for your AWS account.
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   # The secret access key for your AWS account.
$ export AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of security token>
   # The temporary session key for your AWS account. 
   # The AWS_SECURITY_TOKEN environment variable can also be used, but is only supported for backward compatibility purposes.
   # AWS_SESSION_TOKEN is supported by multiple AWS SDKs other than PHP.
```

 **Windows** 

```
C:\> SET  AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
   # The access key for your AWS account.
C:\> SET  AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   # The secret access key for your AWS account.
C:\> SET AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of security token>
   # The temporary session key for your AWS account. 
   # The AWS_SECURITY_TOKEN environment variable can also be used, but is only supported for backward compatibility purposes.
   # AWS_SESSION_TOKEN is supported by multiple AWS SDKs besides PHP.
```

 `Aws\Credentials\CredentialProvider::env` attempts to load credentials from environment variables.

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

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

# `assumeRoleWithWebIdentityCredentialProvider` provider in the SDK for PHP
<a name="assume-role-with-web-identity-provider"></a>

 `Aws\Credentials\CredentialProvider::assumeRoleWithWebIdentityCredentialProvider` attempts to load credentials by assuming a role. If the environment variables `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE` are present, the provider will attempt to assume the role specified at `AWS_ROLE_ARN` using the token on disk at the full path specified in `AWS_WEB_IDENTITY_TOKEN_FILE`. If environment variables are used, the provider will attempt to set the session from the `AWS_ROLE_SESSION_NAME` environment variable.

If environment variables are not set, the provider will use the default profile, or the one set as `AWS_PROFILE`. The provider reads profiles from `~/.aws/credentials` and `~/.aws/config` by default, and can read from profiles specified in the `filename` config option. The provider will assume the role in `role_arn` of the profile, reading a token from the full path set in `web_identity_token_file`. `role_session_name` will be used if set on the profile.

The provider is called as part of the default chain and can be called directly.

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

By default, this credential provider will inherit the configured region which will be used by the StsClient to assume the role. Optionally, a full StsClient can be provided. Credentials should be set as `false` on any provided 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` provider in the SDK for PHP
<a name="ini-provider"></a>

 `Aws\Credentials\CredentialProvider::ini` attempts to load credentials from the shared `config` and `credentials` files. By default, the SDK attempts to load the “default” profile from the shared AWS `credentials` file located at `~/.aws/credentials`. If the SDK finds the `AWS_SDK_LOAD_NONDEFAULT_CONFIG` environment variable, it also checks for a "default" profile in the shared AWS `config` file located at `~/.aws/config`.

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

You can use a custom profile or .ini file location by providing arguments to the function that creates the provider.

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

# `process` provider in the SDK for PHP
<a name="process-provider"></a>

 `Aws\Credentials\CredentialProvider::process` attempts to load credentials by executing `credential_process` value that is specified in a profile in a [shared AWS configuration file](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). 

By default, the SDK attempts to load the “default” profile first from the shared AWS `credentials` file located at `~/.aws/credentials`. If the "default" profile is not found in the shared `credentials` file, the SDK looks in the shared `config` file for the default profile. The following is an example of configuration for the shared `credentials` file.

```
[default]
credential_process = /path/to/file/credential_returning_executable.sh --custom-command custom_parameter
```

The SDK will call the `credential_process` command exactly as given by using PHP's `shell_exec` function and then read JSON data from stdout. The `credential_process` must write credentials to stdout in the following format:

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

 `SessionToken` and `Expiration` are optional. If present, the credentials will be treated as temporary.

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

You can use a custom profile or .ini file location by providing arguments to the function that creates the provider.

```
$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` provider in the SDK for PHP
<a name="instanceprofile-provider"></a>

 `Aws\Credentials\CredentialProvider::instanceProfile` attempts to load credentials for an IAM role specified in an Amazon EC2 instance profile.

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

By default, the provider retries fetching credentials up to three times. The number of retries can be set with the `retries` option, and disabled entirely by setting the option to `0` as shown in the following code.

```
use Aws\Credentials\CredentialProvider;

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

If the environment variable `AWS_METADATA_SERVICE_NUM_ATTEMPTS` is available, its value takes precedence over the 'retries' option shown previously. 

**Note**  
You can disable this attempt to load from Amazon EC2 instance profiles by setting the `AWS_EC2_METADATA_DISABLED` environment variable to `true`.