Using Credentials from AWS Security Token Service

A recent post on the AWS PHP Development forum inspired me to write a quick post about how to use credentials vended by AWS Security Token Service with the AWS SDK for PHP.

What is AWS Security Token Service?

AWS Security Token Service (AWS STS) is a web service that enables you to request temporary, limited-privilege AWS credentials for AWS Identity and Access Management (AWS IAM) users or for users that you authenticate via identity federation. One common use case for using temporary credentials is to grant mobile or client-side applications access to AWS resources by authenticating users through third-party identity providers (read more about Web Identity Federation).

Getting Temporary Credentials

AWS STS has five operations that return temporary credentials: AssumeRole, AssumeRoleWithWebIdentity, AssumeRoleWithSAML (recently added), GetFederationToken, and GetSessionToken. Using the GetSessionToken operation is easy, so let’s use that one as an example. Assuming you have an instance of AwsStsStsClient stored in the $sts variable, this is how you call the method:

$result = $sts->getSessionToken();

See? I told you it was easy. 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>'
    )
    ...
)

Using Temporary Credentials

You can use temporary credentials with another AWS client by instantiating the client and passing in the values received from AWS STS directly.

use AwsS3S3Client;

$result = $sts->getSessionToken();

$s3 = S3Client::factory(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 AwsCommonCredentialsCredentials;
use AwsS3S3Client;

$result = $sts->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);

Closing Notes

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.

If you would like to read more about providing credentials to the SDK, check out one of our other blog posts: Providing Credentials to the AWS SDK for PHP.