This guide focuses on the AWS SDK for PHP client for AWS Security Token Service. This guide assumes that you have already downloaded and installed the AWS SDK for PHP. See Installation for more information on getting started.
First you need to create a client object using one of the following techniques.
The easiest way to get up and running quickly is to use the Aws\Sts\StsClient::factory()
method
and provide your credential profile (via the profile
option), which identifies the set of credentials you want to
use from your ~/.aws/credentials
file (see Using the AWS credentials file and credential profiles).
use Aws\Sts\StsClient;
$client = StsClient::factory(array(
'profile' => '<profile in your aws credentials file>'
));
You can provide your credential profile like in the preceding example, specify your access keys directly (via key
and secret
), or you can choose to omit any credential information if you are using AWS Identity and Access
Management (IAM) roles for EC2 instances
or credentials sourced from the AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
environment variables.
Note
The profile
option and AWS credential file support is only available for version 2.6.1 of the SDK and higher.
We recommend that all users update their copies of the SDK to take advantage of this feature, which is a safer way
to specify credentials than explicitly providing key
and secret
.
A more robust way to connect to AWS Security Token Service is through the service builder. This allows you to specify credentials and other configuration settings in a configuration file. These settings can then be shared across all clients so that you only have to specify your settings once.
use Aws\Common\Aws;
// Create a service builder using a configuration file
$aws = Aws::factory('/path/to/my_config.json');
// Get the client from the builder by namespace
$client = $aws->get('Sts');
For more information about configuration files, see Configuring the SDK.
Note
For information about why you might need to use temporary credentials in your application or project, see Scenarios for Granting Temporary Access in the AWS STS documentation.
AWS STS has five operations that return temporary credentials: AssumeRole
, AssumeRoleWithWebIdentity
,
AssumeRoleWithSAML
, GetFederationToken
, and GetSessionToken
. Using the GetSessionToken
operation is
trivial, so let's use that one as an example.
$result = $client->getSessionToken();
The result for GetSessionToken
and the other AWS STS operations always contains a 'Credentials'
value. If you
print the result (e.g., print_r($result)
), it looks like the following:
Array
(
...
[Credentials] => Array
(
[SessionToken] => '<base64 encoded session token value>'
[SecretAccessKey] => '<temporary secret access key value>'
[Expiration] => 2013-11-01T01:57:52Z
[AccessKeyId] => '<temporary access key value>'
)
...
)
You can use temporary credentials with another AWS client by instantiating the client and passing in the values received from AWS STS directly.
use Aws\S3\S3Client;
$result = $client->getSessionToken();
$s3 = S3Client::factory(array(
'credentials' => array(
'key' => $result['Credentials']['AccessKeyId'],
'secret' => $result['Credentials']['SecretAccessKey'],
'token' => $result['Credentials']['SessionToken'],
)
));
You can also construct a Credentials
object and use that when instantiating the client.
use Aws\Common\Credentials\Credentials;
use Aws\S3\S3Client;
$result = $client->getSessionToken();
$credentials = new Credentials(
$result['Credentials']['AccessKeyId'],
$result['Credentials']['SecretAccessKey'],
$result['Credentials']['SessionToken']
);
$s3 = S3Client::factory(array('credentials' => $credentials));
However, the best way to provide temporary credentials is to use the createCredentials()
helper method included
with StsClient
. This method extracts the data from an AWS STS result and creates the Credentials
object for you.
$result = $sts->getSessionToken();
$credentials = $sts->createCredentials($result);
$s3 = S3Client::factory(array('credentials' => $credentials));
You can also use the same technique when setting credentials on an existing client object.
$credentials = $sts->createCredentials($sts->getSessionToken());
$s3->setCredentials($credentials);
Starting in version 2.7.19 of the SDK you can use regional STS endpoints that you must first enable in the AWS Management Console. To use a regional endpoint for STS, you must set both the region and endpoint when you instantiate the client.
$sts = StsClient::factory(array(
// ...
'region' => 'us-west-2',
'endpoint' => 'https://sts.us-west-2.amazonaws.com',
// ...
));
Please see the AWS Security Token Service Client API reference for a details about all of the available methods, including descriptions of the inputs and outputs.
AssumeRole | AssumeRoleWithSAML |
AssumeRoleWithWebIdentity | DecodeAuthorizationMessage |
GetFederationToken | GetSessionToken |