Skip to content

Secrets

AWS Secrets Manager parameter retrieval and caching utility

CLASS DESCRIPTION
SecretsProvider

AWS Secrets Manager Parameter Provider
FUNCTION DESCRIPTION
get_secret

Retrieve a parameter value from AWS Secrets Manager
set_secret

Modify the details of a secret or create a new secret if it doesn't already exist.

SecretsProvider 

SecretsProvider(
    config: Config | None = None,
    boto_config: Config | None = None,
    boto3_session: boto3.session.Session | None = None,
    boto3_client: SecretsManagerClient | None = None,
)

Bases: BaseProvider

AWS Secrets Manager Parameter Provider

PARAMETER DESCRIPTION
config

Botocore configuration to pass during client initialization

TYPE: Config | None DEFAULT: None

boto3_session 
1
Boto3 session to create a boto3_client from

TYPE: Session DEFAULT: None

boto3_client 
1
Boto3 SecretsManager Client to use, boto3_session will be ignored if both are provided

TYPE: SecretsManagerClient | None DEFAULT: None

Example

Retrieves a parameter value from Secrets Manager

1
2
3
4
5
6
7
>>> from aws_lambda_powertools.utilities.parameters import SecretsProvider
>>> secrets_provider = SecretsProvider()
>>>
>>> value = secrets_provider.get("my-parameter")
>>>
>>> print(value)
My parameter value

Retrieves a parameter value from Secrets Manager in another AWS region

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
>>> from botocore.config import Config
>>> from aws_lambda_powertools.utilities.parameters import SecretsProvider
>>>
>>> config = Config(region_name="us-west-1")
>>> secrets_provider = SecretsProvider(config=config)
>>>
>>> value = secrets_provider.get("my-parameter")
>>>
>>> print(value)
My parameter value

Retrieves a parameter value from Secrets Manager passing options to the SDK call

1
2
3
4
5
6
7
>>> from aws_lambda_powertools.utilities.parameters import SecretsProvider
>>> secrets_provider = SecretsProvider()
>>>
>>> value = secrets_provider.get("my-parameter", VersionId="f658cac0-98a5-41d9-b993-8a76a7799194")
>>>
>>> print(value)
My parameter value
METHOD DESCRIPTION
set

Modify the details of a secret or create a new secret if it doesn't already exist.
Source code in aws_lambda_powertools/utilities/parameters/secrets.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def __init__(
    self,
    config: Config | None = None,
    boto_config: Config | None = None,
    boto3_session: boto3.session.Session | None = None,
    boto3_client: SecretsManagerClient | None = None,
):
    """
    Initialize the Secrets Manager client
    """
    if config:
        warnings.warn(
            message="The 'config' parameter is deprecated in V3 and will be removed in V4. "
            "Please use 'boto_config' instead.",
            category=PowertoolsDeprecationWarning,
            stacklevel=2,
        )

    if boto3_client is None:
        boto3_session = boto3_session or boto3.session.Session()
        boto3_client = boto3_session.client("secretsmanager", config=boto_config or config)
    self.client = boto3_client

    super().__init__(client=self.client)

set 

set(
    name: str,
    value: str | bytes | dict,
    *,
    client_request_token: str | None = None,
    **sdk_options
) -> CreateSecretResponseTypeDef

Modify the details of a secret or create a new secret if it doesn't already exist.

We aim to minimize API calls by assuming that the secret already exists and needs updating. If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:

1
2
3
4
5
6
              ┌────────────────────────┐      ┌─────────────────┐
    ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
    │         └────────────────────────┘      └─────────────────┘     │
    │                                                                 │
    │                                                                 │
    │                                                                 ▼

┌─────────────────┐ ┌─────────────────────┐ │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │ └─────────────────┘ └─────────────────────┘

PARAMETER DESCRIPTION
name

The ARN or name of the secret to add a new version to or create a new one.

TYPE: str

value

Specifies text data that you want to encrypt and store in this new version of the secret.

TYPE: str | bytes | dict

client_request_token

This value helps ensure idempotency. It's recommended that you generate a UUID-type value to ensure uniqueness within the specified secret. This value becomes the VersionId of the new version. This field is auto-populated if not provided, but no idempotency will be enforced this way.

TYPE: str | None DEFAULT: None

sdk_options

Dictionary of options that will be passed to the Secrets Manager update_secret API call

DEFAULT: {}

RAISES DESCRIPTION
SetSecretError

When attempting to update or create a secret fails.
Example

Sets a secret*

1
2
3
>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

Sets a secret and includes an client_request_token

1
2
3
4
5
6
7
8
>>> from aws_lambda_powertools.utilities import parameters
>>> import uuid
>>>
>>> parameters.set_secret(
        name="my-secret",
        value='{"password": "supers3cr3tllam@passw0rd"}',
        client_request_token=str(uuid.uuid4())
    )

1
2
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
Source code in aws_lambda_powertools/utilities/parameters/secrets.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
def set(
    self,
    name: str,
    value: str | bytes | dict,
    *,  # force keyword arguments
    client_request_token: str | None = None,
    **sdk_options,
) -> CreateSecretResponseTypeDef:
    """
    Modify the details of a secret or create a new secret if it doesn't already exist.

    We aim to minimize API calls by assuming that the secret already exists and needs updating.
    If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:


                      ┌────────────────────────┐      ┌─────────────────┐
            ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
            │         └────────────────────────┘      └─────────────────┘     │
            │                                                                 │
            │                                                                 │
            │                                                                 ▼
    ┌─────────────────┐                                              ┌─────────────────────┐
    │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │
    └─────────────────┘                                              └─────────────────────┘

    Parameters
    ----------
    name: str
        The ARN or name of the secret to add a new version to or create a new one.
    value: str, dict or bytes
        Specifies text data that you want to encrypt and store in this new version of the secret.
    client_request_token: str, optional
        This value helps ensure idempotency. It's recommended that you generate
        a UUID-type value to ensure uniqueness within the specified secret.
        This value becomes the VersionId of the new version. This field is
        auto-populated if not provided, but no idempotency will be enforced this way.
    sdk_options: dict, optional
        Dictionary of options that will be passed to the Secrets Manager update_secret API call

    Raises
    ------
    SetSecretError
        When attempting to update or create a secret fails.

    Returns:
    -------
    SetSecretResponse:
        The dict returned by boto3.

    Example
    -------
    **Sets a secret***

        >>> from aws_lambda_powertools.utilities import parameters
        >>>
        >>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

    **Sets a secret and includes an client_request_token**

        >>> from aws_lambda_powertools.utilities import parameters
        >>> import uuid
        >>>
        >>> parameters.set_secret(
                name="my-secret",
                value='{"password": "supers3cr3tllam@passw0rd"}',
                client_request_token=str(uuid.uuid4())
            )

    URLs:
    -------
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
    """

    if isinstance(value, dict):
        value = json.dumps(value, cls=Encoder)

    if isinstance(value, bytes):
        sdk_options["SecretBinary"] = value
    else:
        sdk_options["SecretString"] = value

    if client_request_token:
        sdk_options["ClientRequestToken"] = client_request_token

    try:
        logger.debug(f"Attempting to update secret {name}")
        return self._update_secret(name=name, **sdk_options)
    except self.client.exceptions.ResourceNotFoundException:
        logger.debug(f"Secret {name} doesn't exist, creating a new one")
        return self._create_secret(name=name, **sdk_options)
    except Exception as exc:
        raise SetSecretError(f"Error setting secret - {str(exc)}") from exc

get_secret 

get_secret(
    name: str,
    transform: None = None,
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options
) -> str

get_secret(
    name: str,
    transform: Literal["json"],
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options
) -> dict

get_secret(
    name: str,
    transform: Literal["binary"],
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options
) -> str | bytes | dict

get_secret(
    name: str,
    transform: Literal["auto"],
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options
) -> bytes

get_secret(
    name: str,
    transform: TransformOptions = None,
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options
) -> str | bytes | dict

Retrieve a parameter value from AWS Secrets Manager

PARAMETER DESCRIPTION
name

Name of the parameter

TYPE: str

transform

Transforms the content from a JSON object ('json') or base64 binary string ('binary')

TYPE: TransformOptions DEFAULT: None

force_fetch

Force update even before a cached item has expired, defaults to False

TYPE: bool DEFAULT: False

max_age

Maximum age of the cached value

TYPE: int | None DEFAULT: None

sdk_options

Dictionary of options that will be passed to the get_secret_value call

DEFAULT: {}

RAISES DESCRIPTION
GetParameterError

When the parameter provider fails to retrieve a parameter value for a given name.
TransformParameterError

When the parameter provider fails to transform a parameter value.
Example

Retrieves a secret*

1
2
3
>>> from aws_lambda_powertools.utilities.parameters import get_secret
>>>
>>> get_secret("my-secret")

Retrieves a secret and transforms using a JSON deserializer*

1
2
3
>>> from aws_lambda_powertools.utilities.parameters import get_secret
>>>
>>> get_secret("my-secret", transform="json")

Retrieves a secret and passes custom arguments to the SDK

1
2
3
>>> from aws_lambda_powertools.utilities.parameters import get_secret
>>>
>>> get_secret("my-secret", VersionId="f658cac0-98a5-41d9-b993-8a76a7799194")
Source code in aws_lambda_powertools/utilities/parameters/secrets.py 
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
def get_secret(
    name: str,
    transform: TransformOptions = None,
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options,
) -> str | bytes | dict:
    """
    Retrieve a parameter value from AWS Secrets Manager

    Parameters
    ----------
    name: str
        Name of the parameter
    transform: str, optional
        Transforms the content from a JSON object ('json') or base64 binary string ('binary')
    force_fetch: bool, optional
        Force update even before a cached item has expired, defaults to False
    max_age: int, optional
        Maximum age of the cached value
    sdk_options: dict, optional
        Dictionary of options that will be passed to the get_secret_value call

    Raises
    ------
    GetParameterError
        When the parameter provider fails to retrieve a parameter value for
        a given name.
    TransformParameterError
        When the parameter provider fails to transform a parameter value.

    Example
    -------
    **Retrieves a secret***

        >>> from aws_lambda_powertools.utilities.parameters import get_secret
        >>>
        >>> get_secret("my-secret")

    **Retrieves a secret and transforms using a JSON deserializer***

        >>> from aws_lambda_powertools.utilities.parameters import get_secret
        >>>
        >>> get_secret("my-secret", transform="json")

    **Retrieves a secret and passes custom arguments to the SDK**

        >>> from aws_lambda_powertools.utilities.parameters import get_secret
        >>>
        >>> get_secret("my-secret", VersionId="f658cac0-98a5-41d9-b993-8a76a7799194")
    """

    # If max_age is not set, resolve it from the environment variable, defaulting to DEFAULT_MAX_AGE_SECS
    max_age = resolve_max_age(env=os.getenv(constants.PARAMETERS_MAX_AGE_ENV, DEFAULT_MAX_AGE_SECS), choice=max_age)

    # Only create the provider if this function is called at least once
    if "secrets" not in DEFAULT_PROVIDERS:
        DEFAULT_PROVIDERS["secrets"] = SecretsProvider()

    return DEFAULT_PROVIDERS["secrets"].get(
        name,
        max_age=max_age,
        transform=transform,
        force_fetch=force_fetch,
        **sdk_options,
    )

set_secret 

set_secret(
    name: str,
    value: str | bytes,
    *,
    client_request_token: str | None = None,
    **sdk_options
) -> CreateSecretResponseTypeDef

Modify the details of a secret or create a new secret if it doesn't already exist.

We aim to minimize API calls by assuming that the secret already exists and needs updating. If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:

1
2
3
4
5
6
              ┌────────────────────────┐      ┌─────────────────┐
    ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
    │         └────────────────────────┘      └─────────────────┘     │
    │                                                                 │
    │                                                                 │
    │                                                                 ▼

┌─────────────────┐ ┌─────────────────────┐ │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │ └─────────────────┘ └─────────────────────┘

PARAMETER DESCRIPTION
name

The ARN or name of the secret to add a new version to or create a new one.

TYPE: str

value

Specifies text data that you want to encrypt and store in this new version of the secret.

TYPE: str | bytes

client_request_token

This value helps ensure idempotency. It's recommended that you generate a UUID-type value to ensure uniqueness within the specified secret. This value becomes the VersionId of the new version. This field is auto-populated if not provided, but no idempotency will be enforced this way.

TYPE: str | None DEFAULT: None

sdk_options

Dictionary of options that will be passed to the Secrets Manager update_secret API call

DEFAULT: {}

RAISES DESCRIPTION
SetSecretError

When attempting to update or create a secret fails.
Example

Sets a secret*

1
2
3
>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

Sets a secret and includes an client_request_token

1
2
3
4
5
6
7
>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> parameters.set_secret(
        name="my-secret",
        value='{"password": "supers3cr3tllam@passw0rd"}',
        client_request_token="YOUR_TOKEN_HERE"
    )

1
2
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
Source code in aws_lambda_powertools/utilities/parameters/secrets.py 
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
def set_secret(
    name: str,
    value: str | bytes,
    *,  # force keyword arguments
    client_request_token: str | None = None,
    **sdk_options,
) -> CreateSecretResponseTypeDef:
    """
    Modify the details of a secret or create a new secret if it doesn't already exist.

    We aim to minimize API calls by assuming that the secret already exists and needs updating.
    If it doesn't exist, we attempt to create a new one. Refer to the following workflow for a better understanding:


                      ┌────────────────────────┐      ┌─────────────────┐
            ┌───────▶│Resource NotFound error?│────▶│Create Secret API│─────┐
            │         └────────────────────────┘      └─────────────────┘     │
            │                                                                 │
            │                                                                 │
            │                                                                 ▼
    ┌─────────────────┐                                              ┌─────────────────────┐
    │Update Secret API│────────────────────────────────────────────▶│ Return or Exception │
    └─────────────────┘                                              └─────────────────────┘

    Parameters
    ----------
    name: str
        The ARN or name of the secret to add a new version to or create a new one.
    value: str, dict or bytes
        Specifies text data that you want to encrypt and store in this new version of the secret.
    client_request_token: str, optional
        This value helps ensure idempotency. It's recommended that you generate
        a UUID-type value to ensure uniqueness within the specified secret.
        This value becomes the VersionId of the new version. This field is
        auto-populated if not provided, but no idempotency will be enforced this way.
    sdk_options: dict, optional
        Dictionary of options that will be passed to the Secrets Manager update_secret API call

    Raises
    ------
    SetSecretError
        When attempting to update or create a secret fails.

    Returns:
    -------
    SetSecretResponse:
        The dict returned by boto3.

    Example
    -------
    **Sets a secret***

        >>> from aws_lambda_powertools.utilities import parameters
        >>>
        >>> parameters.set_secret(name="llamas-are-awesome", value="supers3cr3tllam@passw0rd")

    **Sets a secret and includes an client_request_token**

        >>> from aws_lambda_powertools.utilities import parameters
        >>>
        >>> parameters.set_secret(
                name="my-secret",
                value='{"password": "supers3cr3tllam@passw0rd"}',
                client_request_token="YOUR_TOKEN_HERE"
            )

    URLs:
    -------
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/put_secret_value.html
        https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager/client/create_secret.html
    """

    # Only create the provider if this function is called at least once
    if "secrets" not in DEFAULT_PROVIDERS:
        DEFAULT_PROVIDERS["secrets"] = SecretsProvider()

    return DEFAULT_PROVIDERS["secrets"].set(
        name=name,
        value=value,
        client_request_token=client_request_token,
        **sdk_options,
    )