Retrieve secret values
Use the secret manager IPC service to retrieve secret values from secrets on the core device. You use the secret manager component to deploy encrypted secrets to core devices. Then, you can use an IPC operation to decrypt the secret and use its value in your custom components.
Minimum SDK versions
The following table lists the minimum versions of the AWS IoT Device SDK that you must use to retrieve secret values from secrets on the core device.
SDK | Minimum version |
---|---|
v1.2.10 |
|
v1.5.3 |
|
v1.17.0 |
|
v1.12.0 |
Authorization
To use secret manager in a custom component, you must define authorization policies that allow your component to get the value of secrets that you store on the core device. For information about defining authorization policies, see Authorize components to perform IPC operations.
Authorization policies for secret manager have the following properties.
IPC service identifier:
aws.greengrass.SecretManager
Operation | Description | Resources |
---|---|---|
|
Allows a component to get the value of secrets that are encrypted on the core device. |
A Secrets Manager secret ARN, or |
Authorization policy examples
You can reference the following authorization policy example to help you configure authorization policies for your components.
Example authorization policy
The following example authorization policy allows a component to get the value of any secret on the core device.
Note
We recommend that in a production environment, you reduce the scope of the authorization
policy, so that the component retrieves only the secrets that it uses. You can change the
*
wildcard to a list of secret ARNs when you deploy the component.
{ "accessControl": { "aws.greengrass.SecretManager": { "
com.example.MySecretComponent
:secrets:1": { "policyDescription": "Allows access to a secret.", "operations": [ "aws.greengrass#GetSecretValue" ], "resources": [ "*" ] } } } }
GetSecretValue
Gets the value of a secret that you store on the core device.
This operation is similar to the Secrets Manager operation that you can use to get the value of a secret in the AWS Cloud. For more information, see GetSecretValue in the AWS Secrets Manager API Reference.
Request
This operation's request has the following parameters:
refresh
(Python:refresh
)-
(optional): Whether to sync the requested secret with its latest value from AWS Secrets Manager service.
When set to true, secret manager will request the AWS Secrets Manager service for the latest value of the specified secret label and returns that value as a response. Otherwise, the secret value that was stored locally will be returned.
This parameter will not work in conjunction with
versionId
parameter in the request. This parameter works when used in conjunction with Nucleus 2.13.0 and above. secretId
(Python:secret_id
)-
The name of the secret to get. You can specify either the Amazon Resource Name (ARN) or the friendly name of the secret.
versionId
(Python:version_id
)-
(Optional) The ID of the version to get.
You can specify either
versionId
orversionStage
.If you don't specify
versionId
orversionStage
, this operation defaults to the version with theAWSCURRENT
label. versionStage
(Python:version_stage
)-
(Optional) The staging label of the version to get.
You can specify either
versionId
orversionStage
.If you don't specify
versionId
orversionStage
, this operation defaults to the version with theAWSCURRENT
label.
Response
This operation's response has the following information:
secretId
(Python:secret_id
)-
The ID of the secret.
versionId
(Python:version_id
)-
The ID of this version of the secret.
versionStage
(Python:version_stage
)-
The list of staging labels attached to this version of the secret.
secretValue
(Python:secret_value
)-
The value of this version of the secret. This object,
SecretValue
, contains the following information.secretString
(Python:secret_string
)-
The decrypted part of the protected secret information that you provided to Secrets Manager as a string.
secretBinary
(Python:secret_binary
)-
(Optional) The decrypted part of the protected secret information that you provided to Secrets Manager as binary data in the form of a byte array. This property contains the binary data as a base64-encoded string.
This property isn't used if you created the secret in the Secrets Manager console.
Examples
The following examples demonstrate how to call this operation in custom component code.
Examples
Use the following examples to learn how to use the secret manager IPC service in your components.
This example component prints the value of a secret that you deploy to the core device.
Important
This example component prints the value of a secret, so use it only with secrets that store test data. Don't use this component to print the value of a secret that stores important information.
Recipe
The following example recipe defines a secret ARN configuration parameter and allows the component to get the value of any secret on the core device.
Note
We recommend that in a production environment, you reduce the scope of the authorization
policy, so that the component retrieves only the secrets that it uses. You can change the
*
wildcard to a list of secret ARNs when you deploy the component.
Artifacts
The following example Python application demonstrates how to use the secret manager IPC service to get the value of a secret on the core device.
import concurrent.futures import json import sys import traceback import awsiot.greengrasscoreipc from awsiot.greengrasscoreipc.model import ( GetSecretValueRequest, GetSecretValueResponse, UnauthorizedError ) TIMEOUT = 10 if len(sys.argv) == 1: print('Provide SecretArn in the component configuration.', file=sys.stdout) exit(1) secret_id = sys.argv[1] try: ipc_client = awsiot.greengrasscoreipc.connect() request = GetSecretValueRequest() request.secret_id = secret_id operation = ipc_client.new_get_secret_value() operation.activate(request) future_response = operation.get_response() try: response = future_response.result(TIMEOUT) secret_json = json.loads(response.secret_value.secret_string) print('Successfully got secret: ' + secret_id) print('Secret value: ' + str(secret_json)) except concurrent.futures.TimeoutError: print('Timeout occurred while getting secret: ' + secret_id, file=sys.stderr) except UnauthorizedError as e: print('Unauthorized error while getting secret: ' + secret_id, file=sys.stderr) raise e except Exception as e: print('Exception while getting secret: ' + secret_id, file=sys.stderr) raise e except Exception: print('Exception occurred when using IPC.', file=sys.stderr) traceback.print_exc() exit(1)
Usage
You can use this example component with the secret manager component to deploy and print the value of a secret on your core device.
To create, deploy, and print a test secret
-
Create a Secrets Manager secret with test data.
Save the ARN of the secret to use in the following steps.
For more information, see Creating a secret in the AWS Secrets Manager User Guide.
-
Deploy the secret manager component (
aws.greengrass.SecretManager
) with the following configuration merge update. Specify the ARN of the secret that you created earlier.{ "cloudSecrets": [ { "arn": "
arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret-abcdef
" } ] }For more information, see Deploy AWS IoT Greengrass components to devices or the Greengrass CLI deployment command.
-
Create and deploy the example component in this section with the following configuration merge update. Specify the ARN of the secret that you created earlier.
{ "SecretArn": "
arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret
", "accessControl": { "aws.greengrass.SecretManager": { "com.example.PrintSecret:secrets:1": { "policyDescription": "Allows access to a secret.", "operations": [ "aws.greengrass#GetSecretValue" ], "resources": [ "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret-abcdef
" ] } } } }For more information, see Create AWS IoT Greengrass components
-
View the AWS IoT Greengrass Core software logs to verify that the deployments succeed, and view the
com.example.PrintSecret
component log to see the secret value printed. For more information, see Monitor AWS IoT Greengrass logs.