Testfully Vault, Securely Manage Sensitive Data

Testfully Vault is a secure solution for managing and using sensitive data—such as API keys, passwords, and tokens—in your API requests. With integrations like AWS Secrets Manager and a strong focus on privacy, Testfully Vault helps you keep secrets safe and organized across all your projects and environments. Available for both Testfully Cloud and Offline users, Testfully Vault is a great way to work with secrets.

Key Principles: Privacy and Security

Testfully Vault is designed with privacy and security at its core:

• Sensitive data never leaves your device. Secrets are fetched directly from external providers (like AWS Secrets Manager) on your device and are never stored in the Cloud or any other storage medium (e.g. your hard disk, browser storage, etc.).
• Secrets are always masked in the GUI to prevent accidental exposure.
• Domain whitelisting ensures secrets are only used on approved domains or subdomains.

Supported Providers

Testfully Vault integrates with both native OS vaults and external secret management solutions. This allows you to choose the best provider for your needs, whether you prefer a cloud-based solution or a local vault on your device. Below is a list of supported providers, their status, and availability in different Testfully plans.

How Testfully Vault Works

A workspace in Testfully (Cloud or Offline) can have one or more vaults, each of which can connect to a different provider. A vault carries a set of settings and contains multiple secrets. Vault settings define how a vault should be used.

Adding a New Vault

Start by creating a new vault for your workspace. This is done in the Vaults section of Testfully. Here's how:

1. Go to the Vaults section in Testfully.
2. Click "Add Vault" and fill out the required fields in the Settings tab.
3. Configure domain whitelisting to restrict where secrets can be used. (optional)
4. Select your provider (Required).
5. Decide whether to pull all secrets or select specific ones in the Secrets tab.
6. Enable or disable the vault as needed.
7. Click "Save" to create the vault.

Vault Settings

You can change the way your vault works by modifying the settings in the Vaults section. To adjust the settings for a vault, open the vault and click on the Settings tab. Here are the fields you can modify and their descriptions:

Secret Settings

Similar to vaults, secrets have their own metadata that can be modified in the Secrets tab. The following fields are available for each secret:

Permissions

For a vault within a Cloud workspace, you can set permissions to control who can access and manage the vault. Sharing a vault with your team members is a great way to improve security posture of your team. Remember, when we say "share", we only mean sharing the vault configuration, not the secrets themselves.

To set permissions for a vault:

1. Go to the Vaults section in Testfully.
2. Click on the vault you want to configure.
3. In the Settings tab, find the Permissions section.
4. Add team members or groups and assign them the desired permissions (e.g., read, write, admin).
5. Click Save to apply the changes.

More on permissions later on this page.

Using Secrets in Requests

Once you have set up your vault and secrets, you can use them in your API requests:

• Embed secrets in your requests using the following syntax:

  {{vault:secret_name}}
  

  Replace secret_name with the name of your secret.

Secrets in JSON format

If a secret value is a JSON document or key/value pair, you can extract specific values using JSONPath syntax. For example, if you have a secret called admin_cred with value {"username": "testuser", "password": "testpass"}:

• {{vault:admin_cred.username}} will insert the username.
• {{vault:admin_cred.password}} will insert the password.

Extracting values from JSON documents is not limited to the root level; you can also access nested values and arrays.

Protect Secrets with Domain Whitelisting

Domain Whitelisting is a powerful feature that allows you to control where secrets can be used. By specifying allowed domains or subdomains, you can ensure that secrets are only used in approved environments, enhancing security and preventing unauthorized access.

Domain whitelisting can be set at both the vault and secret levels, allowing you to fine-tune access control based on your specific needs. Secrets inherit the domain whitelisting settings from their parent vault, and you can also add additional allowed domains at the secret level.

Setting Up Domain Whitelisting for a Vault

To set up domain whitelisting for a vault:

1. Go to the Vaults section in Testfully.
2. Click on the vault you want to configure.
3. In the Settings tab, find the Domains field.
4. Enter a comma-separated list of allowed domains or subdomains (e.g., example.com, sub.example.com).
5. Use the wildcard * to allow all subdomains (e.g., *.example.com).
6. Click Save to apply the changes.

Setting Up Domain Whitelisting for a Secret

Similar to vaults, you can set up domain whitelisting for individual secrets:

1. Go to the Vaults section in Testfully.
2. Click on the vault containing the secret you want to configure.
3. In the Secrets tab, find the secret you want to modify.
4. In the Domains field, enter a comma-separated list of allowed domains or subdomains (e.g., example.com, sub.example.com).
5. Use the wildcard * to allow all subdomains (e.g., *.example.com).
6. Click Save to apply the changes.

Syncing vaults and providers

Vault providers (e.g. AWS Secrets Manager) hold secrets, while vaults in Testfully hold metadata about those secrets. When you sync a Testfully vault with a provider, Testfully fetches the secrets from the provider and makes them available in the vault.

• To sync all vaults with their providers, click on the "..." menu on the Vaults app and click on the "Sync Vaults" option.

• To sync a specific vault, go to the Vaults app, select the vault you want to sync, click on the "..." button, then click on the "Sync Secrets" option.

Debugging Sync Issues

If you encouter issues while syncing vaults, you can hover over the "Sync Errored" badge next to the vault name to see the error message. This can help you identify and resolve any issues with the vault or its provider connection.

AWS Secrets Manager Integration

Testfully Vault integrates with AWS Secrets Manager using best-in-class security practices from AWS. This integration allows you to securely fetch and use secrets stored in AWS.

Authentication and Setup

Testfully Vault leverages your existing AWS user profiles for authentication, allowing you to leverage SSO or Access Key ID authentication without sharing credentials with Testfully. AWS User profiles also offers to customise the role used for authentication, which is useful for cross-account access.

Once you have set up an AWS profile on your device, you can easily connect it to Testfully Vault:

1. Set up an AWS profile on your device if you haven't already. This takes less than a minute.
2. Select your AWS profile from the dropdown in the Vault settings.
3. Choose to pull all secrets or cherry-pick specific secrets in the Secrets tab.
4. Click Save to create the vault.

For more on setting up AWS profiles, see AWS documentation.

Secret Mapping

Testfully Vault maps AWS Secrets Manager secrets to Testfully secrets using the secret name. If you wish to use a different name for the secret in Testfully, you can specify the Secret ARN in the secret settings. This is particularly useful if the secret name in AWS is different from what you want to use in Testfully.

MacOS Keychain / Windows Credential Manager / Linux Secret Service Integration

MacOS, Windows and Linux operating systems come with a built-in security vault feature to store sensitive data like passwords, API keys, and tokens. These features are widely used by developers and is a great way to manage secrets locally.

On MacOS, this is known as the Keychain, on Windows it's the Credential Manager, and on Linux, it's the Secret Service API. Testfully Vault integrates with these native vaults to securely fetch and use secrets stored in them.

What Testfully Has Access To

Testfully, like any other application, has a dedicated space within MacOS KeyChain/Windows Credential Manager/Linux Secret Service where it can securely store and retrieve secrets. We don't have access to other spaces within the OS vault, ensuring that your secrets remain private and secure. We integrate with these vaults using native APIs, to access the secrets securely and efficiently.

Setting Up MacOS Keychain Vault/Windows Credential Manager Vault/Linux Secret Service Vault

There is no setup required to use a host vault with Testfully Vault. Simply create a new vault and select MacOS Keychain/Windows Credential Manager/Linux Secret Service as the provider. Testfully will automatically add a secret for each Testfully vault secret you have, and you can use them in your requests just like any other secret.

Where is my Vault Key?

Contrary to other API development tools where your secrets are stored in a local storage (other than the native vault that your OS provides), Testfully Vault does not store a vault key on your device. Instead, it uses the native vault provided by your operating system to securely store and retrieve secrets.

Since your OS handles the encryption and decryption of secrets, Testfully Vault does not need to manage a separate vault key, hence no vault key is required. Isn't that convenient?

We think Mac, Windows and Linux security researches have done a great job, and we would like to piggyback on their work to provide a secure vault solution without the need for a vault key.

Share Vaults with Your Team

In Testfully Cloud, you can share vaults with your team members to improve security posture of your workspace. Sharing a vault prevents mistakes and leaking secrets, a common issue when working with sensitive data in a team environment.

Sharing Vaults, not secrets

When you share a vault with your team, you are only sharing the vault configuration, the convenience of using secrets in requests.

Sharing a vault allows others to use the same security settings, while bringing their own secrets to the vault. This way, you can ensure that everyone in your team is using the same secrets and security settings, without exposing your own secrets to others.

Without Vault Sharing

Without vault sharing, each team member should decide how to leverage secrets in their requests. Should they provision and manage their own vaults, or should they use environment variables? Receipe for disaster, right?

Rather than having each team member guesswork how to use secrets in their requests, Testfully Vault allows you to share vaults with your team members, ensuring that everyone is using the same secrets and security settings.

Troubleshooting

If you encounter issues with using secrets in your requests, here are some common troubleshooting steps:

• Check vault and secret status: Ensure that the vault and the specific secret are enabled, and synced with the provider. Hover over the secret value and click on the "Eye icon to view the secret value. Is it what you expect?

• Verify domain whitelisting: Ensure that the domains you are using in your requests match the domains specified in the vault or secret. If domain whitelisting is enabled, secrets will only be used on the specified domains. Don't forget that secrets inherit the domain from the vault.

• Check secret syntax: Ensure you are using the correct syntax to embed secrets in your requests. The correct syntax is {{vault:secret_name}}, where secret_name is the name of the secret you want to use.

• Check for secret name: Ensure that the secret name you are using in your requests matches the name of the secret in the vault. If you are using AWS Secrets Manager, you can also use the secret ARN if the name is different.

Still having issues? Reach out to our support team via support@testfully.io for assistance.