External Credential Providers

Dodeca external credential providers resolve credentials at runtime without storing the target system’s username and password in a SQL connection artifact. A tenant stores a CredentialSource connection artifact that identifies the provider and its provider-specific configuration. SQL connections refer to that source and a provider-specific secret path.

HashiCorp Vault and CyberArk CCP are currently supported provider types. Provider-specific settings are stored as properties on the credential source rather than as fields in the common credential-source model.

Inspect provider properties

Use credential-source-properties to see all configuration accepted by a provider, including which properties are sensitive:

credential-source-properties --type HASHICORP_VAULT
credential-source-properties --type CYBERARK_CCP

HashiCorp Vault

HashiCorp Vault supports token and AppRole authentication. Authentication secrets can be supplied through an env:NAME or file:PATH secret source, entered through a masked interactive prompt using prompt:, or supplied directly using literal:VALUE. Prefer environment variables, files with appropriately restricted permissions, or the masked prompt. Literal values may be visible in shell history and process information.

Complete local Docker example

The following example starts an ephemeral HashiCorp Vault development server, writes database credentials to its KV v2 secrets engine, creates a Dodeca credential source, and tests that Dodeca can resolve the secret.

Vault development mode is intentionally insecure: it runs without TLS, stores data only in memory, starts unsealed, and uses a root token. Use this example only for local development and testing. Do not use this configuration or token strategy in production.

This example requires Docker, a built Dodeca Shell JAR, a Dodeca repository connection, and an existing tenant. It uses the same Vault image and secret structure as Dodeca’s automated Vault integration test.

Start Vault in a terminal and leave it running:

docker run --rm \
  --name dodeca-vault-dev \
  --cap-add=IPC_LOCK \
  -p 8200:8200 \
  -e VAULT_DEV_ROOT_TOKEN_ID=dodeca-test-root-token \
  -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 \
  hashicorp/vault:1.20.4

Vault is available from the host at http://localhost:8200. The explicit root token is for this local example only.

In another terminal, verify that the Vault server is ready:

docker exec \
  -e VAULT_ADDR=http://127.0.0.1:8200 \
  -e VAULT_TOKEN=dodeca-test-root-token \
  dodeca-vault-dev vault status

Add example database credentials to the development server’s default KV v2 engine:

docker exec \
  -e VAULT_ADDR=http://127.0.0.1:8200 \
  -e VAULT_TOKEN=dodeca-test-root-token \
  dodeca-vault-dev vault kv put \
  -mount=secret \
  dodeca/database \
  username=dodeca_db_user \
  password=not-printed-dodeca-password

The Vault CLI uses the logical KV path dodeca/database. Dodeca reads the same KV v2 secret through its full HTTP API path, secret/data/dodeca/database.

Start Dodeca Shell, connect to the repository, and select the tenant that will own the credential source. Adapt the connection file and tenant name to your environment:
```
java -jar target/dshell.jar

connect --connection-file /path/to/dodeca.properties
use --tenant SAMPLE
```
Optionally inspect the supported HashiCorp properties:
```
credential-source-properties --type HASHICORP_VAULT
```
Create the credential source using the masked interactive prompt:
```
credential-source-create \
  --id LocalVault \
  --name "Local Vault development server" \
  --type HASHICORP_VAULT \
  --properties Endpoint=http://localhost:8200,AuthenticationType=TOKEN \
  --secret-properties Token=prompt:
```
When Dodeca Shell displays Secret value for Token:, enter dodeca-test-root-token. The token is not echoed. For noninteractive execution, set the token in the environment before starting Dodeca Shell and use Token=env:DODECA_VAULT_TOKEN, or write it to a suitably protected file and use Token=file:/path/to/token.
Test credential resolution:
```
credential-source-test \
  --id LocalVault \
  --secret-path secret/data/dodeca/database
```
A successful result lists the resolved property names:
```
Property
--------
username
password
```
The test command intentionally does not display dodeca_db_user, not-printed-dodeca-password, the Vault token, or any other resolved values.
When finished, stop the development server:
```
docker stop dodeca-vault-dev
```
Because the container was started with --rm and Vault development mode uses in-memory storage, stopping it removes the container and all secrets created in this example.

For details about the development server and KV command syntax, see the HashiCorp Vault development server documentation and vault kv put documentation.

Configuring HashiCorp Vault

Create a token-authenticated source:

credential-source-create \
  --id CorporateVault \
  --name "Corporate Vault" \
  --type HASHICORP_VAULT \
  --properties Endpoint=https://vault.example.com:8200,AuthenticationType=TOKEN \
  --secret-properties Token=env:DODECA_VAULT_TOKEN

For interactive setup, request a masked prompt:

credential-source-create \
  --id CorporateVault \
  --type HASHICORP_VAULT \
  --properties Endpoint=https://vault.example.com:8200,AuthenticationType=TOKEN \
  --secret-properties Token=prompt:

Create an AppRole-authenticated source:

credential-source-create \
  --id CorporateVault \
  --type HASHICORP_VAULT \
  --properties Endpoint=https://vault.example.com:8200,AuthenticationType=APP_ROLE,RoleId=11111111-2222-3333-4444-555555555555 \
  --secret-properties SecretId=file:/run/secrets/dodeca-vault-secret-id

The AppRole mount defaults to approle; add AuthPath=another-path to --properties when the deployment uses another mount path. HashiCorp Vault Enterprise deployments may similarly set Namespace.

HashiCorp’s KV v2 HTTP path includes the data segment. Test a source with the full API path:

credential-source-test --id CorporateVault --secret-path secret/data/databases/reporting

The test command displays only the resolved property names. It never displays credential values.

CyberArk CCP

CyberArk CCP uses provider properties rather than a bootstrap token:

credential-source-create \
  --id CorporateCyberArk \
  --type CYBERARK_CCP \
  --properties Endpoint=https://cyberark.example.com,AppID=Dodeca,Safe=Dodeca,Folder=Root,Object=ReportingDatabase

credential-source-test --id CorporateCyberArk --secret-path ignored

Use credential-source-properties --type CYBERARK_CCP for the complete property list and defaults.

Security considerations

HashiCorp authentication tokens and AppRole secret IDs are stored in the tenant’s CredentialSource artifact because they bootstrap access to the external provider. Use narrowly scoped, renewable credentials and restrict repository access accordingly. Shell output and credential-source-test do not reveal these values, but repository backups and artifact exports must be protected as sensitive material.