Dynamic Secrets

Prerequisites

  • Familiarity with Doppler Projects.
  • Doppler Enterprise plan. If you're not on the Enterprise plan and are interested in Dynamic Secrets, reach out to our support team.

Overview

Dynamic secrets are one-off secret 'leases' that are valid for a defined period of time. They're required to have a time-to-live (TTL) and are automatically deleted upon expiration via their integration. They're intended to be used in a scoped manner - i.e. the same lease should not be used across services; each service should request a new lease.

Value Proposition

Dynamic secrets provide security benefits due to their ephemeral nature. They're only valid for a defined period of time, limiting their potential impact in the event of exposure. Dynamic secrets also provide increased auditability due to their only being made available once in the original context in which they're requested.

Key Concepts

Dynamic secret lease
A time-bound instance of a dynamic secret. Each time you request a dynamic secret, a new instance is leased. The lease will only be revealed once. If for some reason you do not capture it, request a new lease.

Dynamic secret integration
A connection between Doppler and a 3rd party (e.g., AWS, DataDog, etc.) that facilitates the provisioning and revocation of a dynamic secret lease. In some instances, a configuration is also supplied. For example, an IAM Policy is supplied when configuring an AWS IAM secret integration so Doppler knows what IAM Policy to attach to the AWS IAM user when provisioning the lease.

Default TTL
The default TTL is 30 minutes. You can optionally override the default in both the CLI and API. When the TTL expires, Doppler will revoke (delete) the lease. For example, when leasing an AWS IAM dynamic secret, the IAM User that was created in AWS will be deleted when the TTL expires.

Lease Revocation
When a dynamic secret is leased, the lease ID will also be returned. If you would like to revoke the lease before the TTL expires, you can use the lease ID to revoke the lease via the API.

Supported CLI and API Contexts
When the CLI is active in a config with dynamic secret configured, a dynamic secret will be leased when using doppler run and doppler secrets download. Dynamic secrets can also be requested via the API.

AWS IAM Logical Example

  1. Configure an AWS IAM secrets integration
  2. Utilize the CLI or API to lease an AWS IAM user
  3. Use the leased AWS IAM user to perform a set of actions
  4. Let the lease expire automatically or explicitly revoke it

CLI and API usage

CLI

Dynamic Secrets are supported in the following CLI commands:

  • doppler run - a dynamic secret lease (along with any static secrets) will be injected into the sub-process (i.e. your app)
  • doppler secrets download - a lease will be issued and included in the outputted contents
CLI flags

--dynamic-ttl can be used to override the default TTL of 30min. Time in s (seconds) or h (hours) are supported.

API

Dynamic Secrets are supported in the following API endpoints:

  • /config/secrets/
  • /config/secrets/download

Both endpoints require query param include_dynamic_secrets to be set to true. Dynamic secret TTL can additionally be set via dynamic_secrets_ttl_sec. See our API for more information.

Architectual Considerations

Dynamic secret leases are required to have a TTL. This means at some point, they will no longer be usable. Your applications should be cognizant of the state of the lease - for instance, by checking the leased secret's validity before attempting to use it; or, by requesting a new lease on an ongoing basis. Regardless of the approach you take, acknowledging the temporal nature of dynamic secrets is key to successfully adopting them.


Did this page help you?