Secrets Manager

Secrets Manager provides instance-wide centralization, allowing secrets to be reused across DSS features and objects within the same instance.

For many sensitive settings, DSS can store either:

  • an inline password-like value directly in the object configuration

  • a dku-secret:<identifier> reference to a secret managed in Secrets Manager

Instead of being stored within a parent object (for example, a connection or an administration setting), secrets can be managed in a single place with dedicated permissions.

Note

Secrets Manager is distinct from User secrets. User secrets are personal and cannot be shared. Secrets Manager stores reusable DSS-level secrets.

Secret types

Secrets Manager supports two kinds of secrets:

  • local secrets

  • vault-backed secrets

Secrets Manager supports string values only. Only vault-backed secrets support versions.

Local secrets

A local secret is stored by DSS itself.

The secret value is kept encrypted with the DSS configuration key. See Passwords security for more information.

The main advantage of a local secret over an inline password is not a different storage backend. Instead, the secret becomes a managed DSS object:

  • the same secret can be reused by several DSS objects

  • permissions are managed on the secret itself

  • the value can be updated in one place

  • the secret can be moved out of inline object settings

Vault-backed secrets

A vault-backed secret is a DSS object that points to a secret stored in an external secret manager or vault.

DSS supports AWS Secrets Manager, Azure Key Vault, and Google Cloud Secret Manager.

DSS stores the identifier of the remote secret and fetches the value from the external vault when the secret is resolved.

DSS only reads secret values from the external vault. It cannot list remote secrets, nor can it create or manage secrets directly on the external platform.

Inline passwords and secret references

When a DSS setting supports Secrets Manager, a sensitive field can usually remain inline or be replaced by a secret reference.

With an inline password:

  • the value is stored directly within the parent object, for example, a connection using an inline password

  • the value is duplicated if it is used in multiple parent objects

  • permissions are controlled only through the parent object

  • updating the value requires updating each object separately

With a secret reference:

  • the parent object stores a dku-secret:<identifier> pointer

  • the secret becomes a separate DSS object with its own permissions

  • the same secret can be reused in several places

  • access can fail at runtime if the current user is allowed to use the parent object but not the secret

Managing Vault-backed secrets

Vaults in DSS

Before DSS can use a vault-backed secret, an administrator must first create a vault in DSS.

A vault is a DSS-managed definition that describes how DSS should connect to the external vault. Depending on the provider, it can include:

  • the vault type

  • the region or endpoint

  • the authentication mode and credentials

  • cache settings

  • an allowed remote secret identifier regex

Only DSS administrators can create or modify these vault definitions.

Vault permissions

Creating a vault is an admin-only action, and administrators allow selected users or groups to use a vault.

Using a vault-backed secret requires two separate checks:

  • permission on the DSS secret

  • Use permission on the referenced vault

If one of these checks fails, the secret cannot be resolved.

Allowed remote secret identifier regex

Each vault can define an allowed remote secret identifier regex.

This regex restricts which remote secret identifiers DSS accepts for that vault, in addition to the vault permission model. In other words:

  • the user still needs permission to use the DSS vault

  • DSS then also checks that the remote secret identifier matches the allowed regex for that vault

This adds a DSS-side security layer on top of the access controls enforced by the remote vault.

For example, a vault could allow only remote secret identifiers matching a pattern such as ^dss-prod-.*. In that case, a DSS secret could use dss-prod-snowflake as its remote identifier, but not personal-test-secret.

This is especially useful when the same external vault contains many secrets but DSS should only use a controlled subset. Leave this field empty to allow referencing all remote secrets.

Cache behavior

Vault-backed secrets can use a DSS cache.

When caching is enabled for a vault, DSS may reuse a previously resolved value for the configured cache duration instead of calling the external vault on every access.

This reduces repeated remote calls, but it also means that a value updated in the external vault may not be visible immediately in DSS until the cache expires.

When caching is disabled (set to 0), DSS fetches the remote value each time it resolves the secret.

Secret versions

In addition to the remote secret identifier, vault-backed secrets can specify a version to target a specific secret value. This supports secret update workflows. By default, DSS uses the latest version, but users can specify a fixed version if needed.

AWS Secrets Manager authentication modes

For AWS Secrets Manager vaults, DSS supports several authentication modes:

  • environment-based credentials

  • explicit keypair credentials

  • IAM role assumption

Environment-based credentials use the AWS identity available to the DSS process or machine.

Explicit keypair credentials store an access key and secret key, with an optional session token, in the DSS vault definition.

IAM role mode uses the ambient AWS identity of DSS to assume another AWS role. Some environments also require an external ID as part of this trust configuration.

These modes are primarily administration settings, but they matter operationally because they define which external secrets DSS can resolve and under which AWS identity.

The AWS identity used by DSS requires the secretsmanager:GetSecretValue permission for each secret that DSS resolves. It does not require permission to list secrets. If a secret is encrypted with a customer-managed AWS KMS key, the identity also requires the kms:Decrypt permission for that key. See AWS Secrets Manager identity-based policy examples for more information.

Azure Key Vault authentication modes

For Azure Key Vault, DSS supports environment-based credentials, managed identities, client secrets, and client certificates.

Environment-based credentials use the Azure identity available to the DSS process or machine. Managed identity mode uses an Azure managed identity, which can optionally be selected by resource identifier. Client secret and client certificate modes use an Azure application identity. Azure authentication can also use a custom authority host when required.

Google Cloud Secret Manager authentication modes

For Google Cloud Secret Manager, DSS supports Google Application Default Credentials and explicit service account credentials.

Service account credentials can be provided as JSON content or as a path to a JSON or P12 key file on the DSS host. Advanced configurations can also use service account impersonation or Workload Identity Federation.

Permissions and runtime access

Secret privileges

Secrets Manager defines four secret privilege levels:

  • Use allows use of the secret without revealing its actual value

  • Reveal allows viewing the actual secret value; this is required when code reads the secret and passes it to external APIs

  • Edit allows updating the secret value or settings; for vault-backed secrets, this updates the remote secret identifier rather than the secret value itself

  • Admin allows managing permissions and metadata

Permissions can be granted to users or groups.

Select All users from the group selector to grant permission to all registered users.

Creating a secret, including through Save as secret, requires the Create secrets global permission. The creator is automatically granted the Admin privilege on the new secret.

To prevent accidental loss of access, DSS asks for confirmation when an update would remove the current user’s effective Admin privilege on a secret. In the Python API, this must be explicitly allowed by passing confirm_losing_admin_access=True when saving the secret or changing its sharing settings.

Use vs Reveal

The difference between Use and Reveal is important.

  • Use means the secret value remains within DSS. DSS consumes it on behalf of the user, but the secret value is never exposed to the user or through the feature itself.

  • Reveal means the secret value can become accessible to the user, for example through an API or a code recipe, and is therefore treated as readable.

When selecting a secret, DSS warns users if the secret’s permissions are incompatible with the parent object’s permissions. Permission checks for accessing secrets are always performed at runtime.

Compatibility checks and runtime failures

These checks are useful, but they are not a guarantee that all executions will succeed later. For example, a connection can be visible to a broad user population while the referenced secret is restricted to a subgroup. A user outside that subgroup may still open or select the connection, but the operation fails with a secret access error when DSS tries to use the secret at runtime.

Current usage scope

Secrets Manager is not a general replacement for every credential in DSS.

Secrets Manager is used in selected DSS administration settings and connection settings.

This means that some sensitive values can already be externalized into Secrets Manager, while other product areas still use their previous credential model.

Secrets can also be managed programmatically through the Python API.

Converting inline credentials to secrets

When a field supports both inline values and secret references, DSS allows you to convert an inline password-like value into a managed secret.

This is powered by the Save as secret feature, which automatically creates the new secret and updates the parent object to reference it. Converting credentials centralizes sensitive data and avoids duplicating the same value across multiple objects.

During this conversion, DSS automatically applies permissions compatible with the parent object. These default permissions are a starting point and should be reviewed and refined by a secret administrator as needed.

Audit

Secret and vault operations are covered by the DSS audit framework.

Audit events cover both management operations and secret usage.

Depending on the operation, audit entries can include the secret identifier, the vault identifier and details, the remote secret identifier and version, the user, the usage context, and failure details.

Note

For more information about audit trail storage and access, see Audit trail.

Current limitations

Reference tracking

DSS does not currently provide full usage tracking to show every DSS object referencing a given secret.

As a result, deleting a secret does not trigger a full dependency check across connections, plugins, or other DSS objects. A deleted secret can therefore leave dangling references behind.

Vault deletion and secret deletion do not behave the same way:

  • DSS prevents deleting a vault while DSS secrets still reference it

  • DSS does not prevent deleting a secret that is still referenced by other DSS objects

This difference is intentional in the current implementation and should be taken into account during cleanup and update workflows.

No automatic synchronization across DSS nodes

Secrets are not automatically synchronized between DSS nodes.

If several nodes need the same secret references, the secrets must be created on each node. The Python API can help automate this process.

The same secret reference can still be used differently on different nodes. For example:

  • a Design node can use a secret reference that resolves to development credentials through a development vault

  • a Deployer or Automation node can use the same secret reference, but resolve it through a production vault to production credentials

This allows the same DSS objects to keep stable secret references across nodes while mapping those references to environment-specific values.

Not supported on API node

Secrets Manager is not compatible with API nodes.