Vaults
When you register a datasource (see Configure Data Sources), the Secret Backend and Key Mappings fields don’t hold a credential value directly — they store a reference to one: a file path, a keystore alias, or an AWS secret ID. The value itself lives, and is managed, wherever your organization already keeps it — Alien Giraffe only needs to be able to reach and read it.
This guide covers what to configure on the Alien Giraffe side so each backend is actually reachable: file, java-keystore, and aws-secrets-manager. For java-keystore and aws-secrets-manager — real secrets managers your organization likely already runs — it doesn’t cover managing the secret values themselves; that stays with whatever process you already use for that vault. (If you have no keystore yet, there is an example of building a first one with keytool.) file is the exception: it isn’t a separate vault system, so configuring access to it and putting a value in it are the same step, covered below. For the trust-boundary model behind why secrets work this way, see Secret Isolation.
Choosing A Backend
Section titled “Choosing A Backend”| Backend | Best for | What you configure |
|---|---|---|
file |
Local development, demos, and proof-of-concept setups | A JSON file connector can read |
java-keystore |
Deployments that already manage credentials in a Java keystore | A10E_KEYSTORE_PATH / A10E_KEYSTORE_PASSWORD |
aws-secrets-manager |
AWS-hosted deployments | AWS credentials or an IAM role |
java-keystore
Section titled “java-keystore”How it stores a secret
Section titled “How it stores a secret”Each secret is stored as a self-signed RSA key pair whose certificate’s Common Name (CN) is the secret value, in plaintext — not a conventional keystore “secret entry.” Because a certificate’s CN field has a practical size limit, this backend can’t hold large values like SSH private keys — the dashboard excludes java-keystore entirely as an option for SSH datasources. See Configure SSH Datasources for how to store one with file instead.
Format and alias requirements
Section titled “Format and alias requirements”Whatever process creates the keystore, two things are required for Alien Giraffe to read it:
- The file must be in JKS format — not PKCS12, which has been
keytool’s default store type since JDK 9 (keytool -genkeypairwith no-storetypeflag produces a PKCS12 file). A PKCS12 file fails to load outright. - Each distinct value needs its own alias. Alien Giraffe reads a field by looking up the alias you mapped it to and returning that certificate’s CN, so a field gets whatever CN its alias holds. Map two fields to the same alias, or point an alias at a certificate whose CN is someone else’s value, and the field silently gets that value, with no error at load or read time. Aliases whose CNs happen to match are fine when the values really are the same: several datasources can share the username
readerthrough their own aliases.
The datasource form pre-fills Key Mappings with these aliases when the backend is java-keystore:
| Datasource kind | Credential | Default alias |
|---|---|---|
| PostgreSQL | Username, Password | pg_username, pg_password |
| Oracle | Username, Password | oracle_username, oracle_password |
| MySQL | Username, Password | mysql_username, mysql_password |
| SQL Server | Username, Password | mssql_username, mssql_password |
| Snowflake | Username, PAT Token | snowflake_username, snowflake_token |
| S3 | Access Key ID, Secret Access Key, Session Token | aws_access_key, aws_secret_key, aws_session_token |
These are only defaults: each mapping field is editable, so any alias name works as long as the keystore and the datasource form’s Key Mappings name the same one. The keystore can’t hold an SSH private key, so the datasource form doesn’t offer java-keystore for an SSH datasource; it uses file or aws-secrets-manager instead (see Configure SSH Datasources). Two datasources of the same kind get the same default aliases, so if their credentials differ, give the second one its own aliases (for example mysql_reports_username) both in the keystore and in its Key Mappings.
To sanity-check a keystore before pointing Alien Giraffe at it:
keytool -list -v -keystore /secrets/keystore.jks -storepass <keystore password>Confirm the output starts with Keystore type: JKS (not PKCS12), and that each alias you plan to use shows the value you expect for it under Owner: CN=....
Example: create a keystore
Section titled “Example: create a keystore”If your organization has no keystore process yet, this builds a small JKS keystore holding one username and one password. The shell variables are only there to keep secrets out of the command history; your own process will differ.
sudo mkdir -p /opt/a10e/shared/secretsread -r -s -p 'Keystore password: ' KS_PASS; echoread -r -p 'Database username: ' DB_USERread -r -s -p 'Database password: ' DB_PASS; echoKS=/opt/a10e/shared/secrets/keystore.jks
for entry in "pg_username:$DB_USER" "pg_password:$DB_PASS"; do sudo keytool -genkeypair -storetype JKS -keystore "$KS" -storepass "$KS_PASS" \ -keypass "$KS_PASS" -alias "${entry%%:*}" -keyalg RSA -keysize 2048 -validity 3650 \ -dname "CN=${entry#*:}" 2>&1 | sed '/^[[:space:]]*for: CN=/d' [ "${PIPESTATUS[0]}" -eq 0 ] || { echo "keytool failed for alias ${entry%%:*}" >&2; break; }donesudo chmod 0600 "$KS"keytool prints a for: CN=<value> line after generating each key pair, which would echo the secret to your terminal; the sed drops that line and keeps every other message and the exit status. A harmless warning that JKS is a proprietary format is expected.
The alias names (pg_username, pg_password, the wizard’s defaults for PostgreSQL) are yours to choose; for another type, use its prefix, such as mysql_username and mysql_password. You enter them later in the datasource’s Key Mappings. A value that contains ,, =, +, ", \, <, > or ; must have those characters backslash-escaped in -dname. keytool ships with a JDK or JRE (on RHEL, sudo dnf install -y java-17-openjdk-headless). Then check the result as described above.
Example: S3 access key, secret key and session token
Section titled “Example: S3 access key, secret key and session token”An S3 datasource maps three aliases, aws_access_key, aws_secret_key and aws_session_token. The session token is only needed for temporary credentials (for example from AWS STS or single sign-on); with a long-lived access key, leave its mapping empty and create the first two aliases only. A session token is long, often over a thousand characters, and base64 text such as + and = is among the characters -dname needs escaped. The same keytool command stores it; the loop below escapes each value for you before it goes into -dname:
read -r -s -p 'Keystore password: ' KS_PASS; echoread -r -s -p 'AWS access key ID: ' AWS_KEY; echoread -r -s -p 'AWS secret access key: ' AWS_SECRET; echoread -r -s -p 'AWS session token: ' AWS_TOKEN; echoKS=/opt/a10e/shared/secrets/keystore.jks
for entry in "aws_access_key:$AWS_KEY" "aws_secret_key:$AWS_SECRET" "aws_session_token:$AWS_TOKEN"; do value=$(printf '%s' "${entry#*:}" | sed 's/[,=+"\\<>;]/\\&/g') sudo keytool -genkeypair -storetype JKS -keystore "$KS" -storepass "$KS_PASS" \ -keypass "$KS_PASS" -alias "${entry%%:*}" -keyalg RSA -keysize 2048 -validity 3650 \ -dname "CN=$value" 2>&1 | sed '/^[[:space:]]*for: CN=/d' [ "${PIPESTATUS[0]}" -eq 0 ] || { echo "keytool failed for alias ${entry%%:*}" >&2; break; }doneUse the keystore from the previous example, or create a new one the same way. keytool stores the value as the certificate’s CN with the backslashes removed, so -list -v shows the original token under Owner: CN=.... Check that it matches what you pasted, as described above. As with every keystore change, restart the service afterwards: connector reads the keystore once at startup.
Session credentials are temporary. Alien Giraffe reads the token from the keystore as it is and doesn’t refresh it, so once AWS expires it, the S3 datasource can no longer be scanned or loaded into a request. To restore access, put new values into the same three aliases (delete each alias first with keytool -delete, or keytool refuses to overwrite it) and restart the service. If you want a datasource that doesn’t need this upkeep, use a long-lived access key for a dedicated read-only IAM user and no session token.
Configuration
Section titled “Configuration”Set these two environment variables wherever connector runs — both are required, or the backend isn’t registered at all:
export A10E_KEYSTORE_PATH=/secrets/keystore.jksexport A10E_KEYSTORE_PASSWORD=<keystore password>On a bundle install, put the same two lines (without export) in /opt/a10e/shared/.env and run sudo systemctl restart a10e.service; the bundle reads .env only at start. Until you do, a datasource that uses this backend reports secret backend not registered: java-keystore.
This is the same keystore referenced by the [enzo] section of a10e.toml (keystore_path/keystore_password, see Installation) — connector and the env-enzo sidecar it launches per request each open the file independently, so both need to point at the same physical keystore with the same password.
On Kubernetes, the keystore file is mounted in from a Kubernetes Secret rather than baked into the image. Create it once:
kubectl create secret generic <release-name>-keystore \ --from-file=keystore.jks=/path/to/keystore.jks \ -n <namespace>and set envManager.keystore.enabled, .password, and .mountPath in your Helm values to match (see Install With Kubernetes And Helm). connector loads the keystore once at startup, so restart the process (or the pod) after the underlying keystore file changes.
aws-secrets-manager
Section titled “aws-secrets-manager”Credentials and region are resolved through the standard AWS SDK chain — environment variables, a shared AWS profile, or (recommended in production) an IAM role attached to the service via IRSA on EKS. There’s no Alien Giraffe–specific env var for this; if the AWS SDK can’t resolve credentials at all, this backend won’t be offered.
IAM policy
Section titled “IAM policy”At minimum, the running service needs read access to the secrets it will use:
{ "Effect": "Allow", "Action": ["secretsmanager:GetSecretValue"], "Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:<your-prefix>/*"}If those secrets are encrypted with a customer-managed KMS key rather than the AWS-managed default, also grant kms:Decrypt on that key.
In production, prefer an IAM role over static keys: set envManager.serviceAccount.roleArn in your Helm values so the pod assumes the role via IRSA instead of holding long-lived credentials.
Use the secret’s existing name or ARN as the Secret ID field when registering the datasource in the dashboard.
Unlike the other two backends, file isn’t a real secrets manager — it’s a plain JSON file on disk that connector reads directly. That makes it the quickest backend to stand up for local development, a demo, or a proof of concept, but it has none of the access control, auditing, or encryption-at-rest a dedicated vault provides. Prefer java-keystore or aws-secrets-manager for anything beyond that.
The file is a flat JSON object. Its keys need to match whatever names you use in the datasource’s Key Mappings — the defaults are the plain credential field names, for example:
{ "username": "reader_user", "password": "correct horse battery staple"}Put it somewhere connector can read, owned by the account it runs as, and locked down to that account only. On a bundle install (Standalone or Manual), connector runs as root, so the file belongs to root:
sudo install -d -m 0700 -o root -g root /secretssudo install -m 0600 -o root -g root /dev/null /secrets/prod-db.jsonsudo tee /secrets/prod-db.json >/dev/null <<'EOF'{ "username": "reader_user", "password": "correct horse battery staple"}EOFIf you run connector under its own service account instead, use that account in place of root, and write the file with sudo -u <account> tee.
Then point the datasource’s File Path field at /secrets/prod-db.json. There’s no watch/reload beyond what the datasource connection itself triggers, and no built-in versioning — editing the file in place replaces the value outright.