AWS SDK for PHP
Developer Guide

Managing Secrets Using the Secrets Manager API and the AWS SDK for PHP Version 3

AWS Secrets Manager stores and manages shared secrets such as passwords, API keys, and database credentials. With the Secrets Manager service, developers can replace hard-coded credentials in deployed code with an embedded call to Secrets Manager.

Secrets Manager natively supports automatic scheduled credential rotation for Amazon Relational Database Service (Amazon RDS) databases, increasing application security. Secrets Manager can also seamlessly rotate secrets for other databases and third-party services using AWS Lambda to implement service-specific details.

The following examples show how to:

All the example code for the AWS SDK for PHP Version 3 is available here on GitHub.

Credentials

Before running the example code, configure your AWS credentials, as described in Credentials for the AWS SDK for PHP Version 3. Then import the AWS SDK for PHP, as described in Basic Usage Patterns of the AWS SDK for PHP Version 3.

Create a Secret in Secrets Manager

To create a secret in Secrets Manager, use the CreateSecret operation.

In this example, a user name and password are stored as a JSON string.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = '<<{{MySecretName}}>>'; $secret = '{"username":"<<USERNAME>>","password":"<<PASSWORD>>"}'; $description = '<<Description>>'; try { $result = $client->createSecret([ 'Description' => $description, 'Name' => $secretName, 'SecretString' => $secret, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }

Retrieve a Secret from Secrets Manager

To retrieve the value of a secret stored in Secrets Manager, use the GetSecretValue operation.

In this example, secret is a string that contains the stored value. If called on the secret we created earlier, this sample outputs [{\"username\":\"<<USERNAME>>\",\"password\":\"<<PASSWORD>>\"}]. Use json.loads to access indexed values.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => '<<{{MyRegionName}}>>', ]); $secretName = '<<{{MySecretName}}>>'; try { $result = $client->getSecretValue([ 'SecretId' => $secretName, ]); } catch (AwsException $e) { $error = $e->getAwsErrorCode(); if ($error == 'DecryptionFailureException') { // Secrets Manager can't decrypt the protected secret text using the provided AWS KMS key. // Handle the exception here, and/or rethrow as needed. throw $e; } if ($error == 'InternalServiceErrorException') { // An error occurred on the server side. // Handle the exception here, and/or rethrow as needed. throw $e; } if ($error == 'InvalidParameterException') { // You provided an invalid value for a parameter. // Handle the exception here, and/or rethrow as needed. throw $e; } if ($error == 'InvalidRequestException') { // You provided a parameter value that is not valid for the current state of the resource. // Handle the exception here, and/or rethrow as needed. throw $e; } if ($error == 'ResourceNotFoundException') { // We can't find the resource that you asked for. // Handle the exception here, and/or rethrow as needed. throw $e; } } // Decrypts secret using the associated KMS CMK. // Depending on whether the secret is a string or binary, one of these fields will be populated. if (isset($result['SecretString'])) { $secret = $result['SecretString']; } else { $secret = base64_decode($result['SecretBinary']); } // Your code goes here;

List Secrets Stored in Secrets Manager

Get a list of all the secrets that are stored by Secrets Manager using the ListSecrets operation.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); try { $result = $client->listSecrets([ ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }

Retrieve Details about a Secret

Stored secrets contain metadata about rotation rules, when it was last accessed or changed, user-created tags, and the Amazon Resource Name (ARN). To get the details of a specified secret stored in Secrets Manager, use the DescribeSecret operation.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = '<<{{MySecretName}}>>'; try { $result = $client->describeSecret([ 'SecretId' => $secretName, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }

Update the Secret Value

To store a new encrypted secret value in Secrets Manager, use the PutSecretValue operation.

This creates a new version of the secret. If a version of the secret already exists, add the VersionStages parameter with the value in AWSCURRENT to ensure that the new value is used when retrieving the value.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = '<<{{MySecretName}}>>'; $secret = '{"username":"<<USERNAME>>","password":"<<PASSWORD>>"}'; try { $result = $client->putSecretValue([ 'SecretId' => $secretName, 'SecretString' => $secret, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }

Rotate the Value to an Existing Secret in Secrets Manager

To rotate the value of an existing secret stored in Secrets Manager, use a Lambda rotation function and the RotateSecret operation.

Before you begin, create a Lambda function to rotate your secret. The AWS Code Sample Catalog currently contains several Lambda code examples for rotating Amazon RDS database credentials.

Note

For more information about rotating secrets, see Rotating Your AWS Secrets Manager Secrets in the AWS Secrets Manager User Guide.

After you set up your Lambda function, configure a new secret rotation.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = '<<{{MySecretName}}>>'; $lambda_ARN = 'arn:aws:lambda:us-west-2:123456789012:function:MyTestDatabaseRotationLambda'; $rules = ['AutomaticallyAfterDays' => 30]; try { $result = $client->rotateSecret([ 'RotationLambdaARN' => $lambda_ARN, 'RotationRules' => $rules, 'SecretId' => $secretName, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }

When a rotation is configured, you can implement a rotation using the RotateSecret operation.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = '<<{{MySecretName}}>>'; try { $result = $client->rotateSecret([ 'SecretId' => $secretName, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }

Delete a Secret from Secrets Manager

To remove a specified secret from Secrets Manager, use the DeleteSecret operation. To prevent deleting a secret accidentally, a DeletionDate stamp is automatically added to the secret that specifies a window of recovery time in which you can reverse the deletion. If the time isn't specified for the recovery window, the default amount of time is 30 days.

Imports

require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException;

Sample Code

$client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = '<<{{MySecretName}}>>'; try { $result = $client->deleteSecret([ 'SecretId' => $secretName, ]); var_dump($result); } catch (AwsException $e) { // output error message if fails echo $e->getMessage(); echo "\n"; }

The AWS SDK for PHP examples use the following REST operations from the AWS Secrets Manager API Reference:

For more information about using AWS Secrets Manager, see the AWS Secrets Manager User Guide.