本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Secrets Manager API 和 第 3 適用於 PHP 的 AWS SDK 版管理秘密 AWS Secrets Manager 會存放和管理共用秘密，例如密碼、API 金鑰和資料庫登入資料。透過 Secrets Manager 服務，開發人員可以將已部署程式碼中的硬式編碼登入資料取代為對 Secrets Manager 的內嵌呼叫。 Secrets Manager 原生支援 Amazon Relational Database Service (Amazon RDS) 資料庫的自動排程登入資料輪換，以提高應用程式安全性。Secrets Manager 也可以使用 無縫輪換其他資料庫和第三方服務的秘密 AWS Lambda ，以實作服務特定的詳細資訊。 下列範例示範如何： + 使用 [CreateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#createsecret) 建立秘密。 + 使用 [GetSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#getsecretvalue) 擷取秘密。 + 使用 [ListSecrets](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#listsecrets) 列出 Secrets Manager 存放的所有秘密。 + 使用 [DescribeSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#describesecret) 取得特定秘密的詳細資訊。 + 使用 [PutSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#putsecretvalue) 更新指定的秘密。 + 使用 [RotateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#rotatesecret) 設定秘密輪換。 + 使用 [DeleteSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#deletesecret) 將秘密標為刪除。 您可以在 GitHub 上 適用於 PHP 的 AWS SDK 取得 的所有範例程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code) ## 登入資料 在執行範例程式碼之前，請先設定您的 AWS 登入資料，如中所述[AWS 使用第 3 適用於 PHP 的 AWS SDK 版向 驗證](credentials.md)。然後匯入 適用於 PHP 的 AWS SDK，如 中所述[安裝第 3 適用於 PHP 的 AWS SDK 版](getting-started_installation.md)。 ## 在 Secrets Manager 中建立秘密 若要在 Secrets Manager 中建立秘密，請使用 [CreateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#createsecret) 操作。 在這個範例中，使用者名稱和密碼的存放格式為 JSON 字串。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = 'MySecretName'; $secret = json_encode([ "username" => getenv("SMDEMO_USERNAME"), "password" => getenv("SMDEMO_PASSWORD"), ]); $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"; } ``` ## 從 Secrets Manager 擷取秘密 若要擷取存放在 Secrets Manager 中的秘密值，請使用 [GetSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#getsecretvalue) 操作。 在下列範例中， `secret` 是包含儲存值的字串。如果 的值`username`是 ，`<>`而 的值`password`是 `<>`，則 的輸出`secret`是： ``` {"username":"<>","password":"<>"} ``` 使用 `json_decode($secret, true)` 存取陣列值。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-east-1', ]); $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']); } print $secret; $secretArray = json_decode($secret, true); $username = $secretArray['username']; $password = $secretArray['password']; // Your code goes here; ``` ## 列出存放在 Secrets Manager 中的秘密 取得 Secrets Manager 使用 [ListSecrets](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#listsecrets) 操作存放的所有秘密清單。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $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"; } ``` ## 擷取秘密的詳細資訊 存放的秘密包含與輪換規則相關的中繼資料、前次遭存取或變更的時間、使用者建立的標籤，以及 Amazon Resource Name (ARN)。若要取得存放在 Secrets Manager 中指定秘密的詳細資訊，請使用 [DescribeSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#describesecret) 操作。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $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"; } ``` ## 更新機密值 若要在 Secrets Manager 中存放新的加密秘密值，請使用 [PutSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#putsecretvalue) 操作。 這會建立秘密的新版本。如果某個版本的秘密已存在，請在 `AWSCURRENT` 中新增含該值的 `VersionStages` 參數，以確保擷取該值時所用的是新的值。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $client = new SecretsManagerClient([ 'profile' => 'default', 'version' => '2017-10-17', 'region' => 'us-west-2' ]); $secretName = 'MySecretName'; $secret = json_encode([ "username" => getenv("SMDEMO_USERNAME"), "password" => getenv("SMDEMO_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"; } ``` ## 將值輪換到 Secrets Manager 中的現有秘密 若要輪換存放在 Secrets Manager 中現有秘密的值，請使用 Lambda 輪換函數和 [RotateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#rotatesecret) 操作。 開始之前，請建立 Lambda 函數來輪換秘密。Code [AWS Sample Catalog](https://docs.aws.amazon.com/code-samples/latest/catalog/code-catalog-lambda_functions-secretsmanager.html) 目前包含數個用於輪換 Amazon RDS 資料庫登入資料的 Lambda 程式碼範例。 **注意** 如需輪換秘密的詳細資訊，請參閱 AWS Secrets Manager 《 使用者指南》中的[輪換您的 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)。 設定 Lambda 函數之後，請設定新的秘密輪換。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $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"; } ``` 輪換設定好時，您可以使用 [RotateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#rotatesecret) 操作來實作輪換。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $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"; } ``` ## 從 Secrets Manager 刪除秘密 若要從 Secrets Manager 移除指定的秘密，請使用 [DeleteSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#deletesecret) 操作。為避免不小心刪除秘密，會自動將 DeletionDate 戳記新增到秘密，來指定您可以反轉刪除的復原時間時段。如果未指定復原時段的時間，則預設的時間為 30 天。 **匯入** ``` require 'vendor/autoload.php'; use Aws\SecretsManager\SecretsManagerClient; use Aws\Exception\AwsException; ``` **範例程式碼** ``` $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"; } ``` ## 相關資訊 這些 適用於 PHP 的 AWS SDK 範例使用 AWS Secrets Manager API 參考中的下列 REST 操作： + [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) + [GetSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html) + [ListSecrets](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ListSecrets.html) + [DescribeSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DescribeSecret.html) + [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html) + [RotateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_RotateSecret.html) + [DeleteSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DeleteSecret.html) 如需使用 的詳細資訊 AWS Secrets Manager，請參閱 [AWS Secrets Manager 使用者指南](https://docs.aws.amazon.com/secretsmanager/latest/userguide/)。