# Storing secrets in the vault

Galaxy can be configured to store secrets in an external vault, which is useful for secure handling and centralization of secrets management.
In particular, information fields in the "Manage information" section of the user profile, such as AWS credentials, can be configured to be stored
in an encrypted vault instead of the database. Vault keys are generally stored as key-value pairs in a hierarchical fashion, for example:
`/galaxy/user/2/preferences/aws/client_secret`.

## Vault backends

There are currently 3 supported backends.

| Backend     | Description                                                                                                                                                                                                                                                                                                                                   |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| hashicorp   | Hashicorp Vault is a secrets and encryption management system. https://www.vaultproject.io/                                                                                                                                                                                                                                                   |
| database    | The database backend stores secrets in an encrypted table in the Galaxy database itself. It is a convenient way to get started with a vault, and while it supports basic key rotation, we recommend using one of the other options in production.                                                                                           |

## Configuring Galaxy

The first step to using a vault is to configure the `vault_config_file` setting in `galaxy.yml`. 

```yaml
galaxy:
  # Vault config file
  # The value of this option will be resolved with respect to
  # <config_dir>.
  vault_config_file: vault_conf.yml
```

## Configuring vault_conf.yml

The vault_conf.yml file itself has two basic fields:
```yaml
type: hashicorp  # required
path_prefix: /galaxy  # optional
...
```

The `type` must be a valid backend type: `hashicorp`, or `database`. At present, only a single vault backend
is supported. The `path_prefix` property indicates  the root path under which to store all vault keys. If multiple
Galaxy instances are using the same vault, a prefix can  be used to uniquely identify the Galaxy instance.
If no path_prefix is provided, the prefix defaults to `/galaxy`.

## Vault configuration for Hashicorp Vault

```yaml
type: hashicorp
path_prefix: /my_galaxy_instance
vault_address: http://localhost:8200
vault_token: vault_application_token
```

## Vault configuration for database

```yaml
type: database
path_prefix: /galaxy
# Encryption keys must be valid fernet keys
# To generate a valid key:
#
# Use the ascii string value as a key
# For more details, see: https://cryptography.io/en/latest/fernet/#
encryption_keys:
  - 5RrT94ji178vQwha7TAmEix7DojtsLlxVz8Ef17KWgg=
  - iNdXd7tRjLnSqRHxuhqQ98GTLU8HUbd5_Xx38iF8nZ0=
  - IK83IXhE4_7W7xCFEtD9op0BAs11pJqYN236Spppp7g=
```

Secrets stored in the database are encrypted using Fernet keys. Therefore, all listed encryption keys must be valid fernet keys. To generate a new
Fernet key, use the following Python code:

```python
from cryptography.fernet import Fernet
Fernet.generate_key().decode('utf-8')
```

If multiple encryption keys are defined, only the first key is used to encrypt secrets. The remaining keys are tried in turn during decryption. This is useful for key rotation.
We recommend periodically generating a new fernet key and rotating old keys. However, before removing an old key, make sure that any data encrypted using that old key is no longer
present or the data will no longer be decryptable.

## Configuring user preferences to use the vault

The `user_preferences_extra_conf.yml` can be used to automatically route secrets to a vault. An example configuration follows:

```yaml
preferences:
    nextcloud:
        description: Your NextCloud account
        inputs:
            - name: password
              label: password
              type: password
              store: vault
              required: False
```

Note the `store: vault` property, which results in the property being stored in the vault. Note also that if you use `type: password`, the secret is sent to the client front-end,
but specifying `type: secret` would mean that the values cannot be retrieved by the client, only written to, providing an extra layer of security.

## Configuring file sources to use (user) secrets stored in a vault

In a file source the password could be used as follows:

```yaml
- type: webdav
  id: nextcloud
  label: NextCloud
  doc: UFZ NextCloud files (configure access in user preferences)
  url: https://some-nextcloud.org
  root: /remote.php/dav/files/${user.username}/
  login: ${user.username}
  password: ${user.user_vault.read_secret('preferences/ufz-nextcloud/password')}
```

This example assumes that the NextCloud username is identical to the Galaxy username. If this is not the case also the username could be a user preference that is stored in a vault.

## Tool Credentials System

Starting with Galaxy 25.1, tools can request credentials directly through a new tool credentials system. This system provides a secure, user-friendly way for tools to access external APIs and services using credentials stored in the vault.

### Overview

The tool credentials system allows tool developers to declaratively specify credential requirements in their tool XML, and Galaxy automatically:
- Presents a user-friendly credential management interface in the tool form
- Stores sensitive credentials (secrets) encrypted in the configured vault
- Injects credentials as environment variables when tools execute
- Provides centralized credential management in User Preferences

### How it works

1. **Tool Definition**: Tool developers add a `<credentials>` element to their tool XML defining required secrets (API keys, passwords) and optional variables (endpoints, usernames).
2. **User Experience**: When users run a tool requiring credentials, they see a credential management section in the tool form where they can provide or select existing credentials.
3. **Secure Storage**: All secrets are automatically stored encrypted in the vault (configured via `vault_config_file`).
4. **Automatic Injection**: When the tool runs, Galaxy injects the credentials as environment variables into the tool's execution environment.

### Vault Configuration Requirements

The tool credentials system requires a properly configured vault. Any of the supported vault backends (hashicorp, custos, or database) can be used. Ensure you have:

1. Set up your vault configuration as described in the sections above
2. Configured the `vault_config_file` setting in `galaxy.yml`
3. Tested that the vault is working properly

The tool credentials system will automatically use the configured vault to store all tool secrets.

### Admin Considerations

- **No additional configuration needed**: Unlike the older user preferences approach, the tool credentials system requires no admin configuration in `user_preferences_extra_conf.yml`. Tools can define their own credential requirements.
- **Vault is required**: The tool credentials system only works when a vault is configured. If no vault is configured, tools requesting credentials will not function properly.
- **User isolation**: Each user's credentials are isolated in the vault. Credentials cannot be shared between users.
- **Migration from user preferences**: If you previously configured tool credentials via `user_preferences_extra_conf.yml`, those can be gradually phased out as tools migrate to the new system. Both systems can coexist.

### API Access

The tool credentials system provides a REST API at `/api/users/{user_id}/credentials` for programmatic credential management. This can be useful for:
- Automating credential setup for multiple users
- Building custom credential management interfaces
- Integrating with external identity management systems

For more information on the tool credentials system from a developer perspective, see the [Tool XML Schema documentation](https://docs.galaxyproject.org/en/master/dev/schema.html#tool-requirements-credentials).