Vault Integration — Administrator Setup Guide ENT

Configuring corporate password-vault providers (Bitwarden, 1Password, HashiCorp Vault) in Slim Archiver Enterprise.

Audience: IT / security administrators · Applies to: Slim Archiver Enterprise.

Scope: this guide covers Slim Archiver's own configuration — which field takes which value, the reference/path formats, and the provider-specific gotchas. It assumes you already know how to operate your vault (Bitwarden, 1Password, or HashiCorp Vault); installing and running those tools is standard vendor procedure and is not repeated here.

1. Concepts you need before configuring

Where to configure: Enterprise Control Center → Shared Password Safes (or Settings, depending on build). Requires an active Enterprise license — vault integration is Enterprise-only and is enforced in the backend, not just hidden in the UI. Without an Enterprise license, vault references will not resolve anywhere in the app, including if typed manually.

How an archive uses a vault secret. Slim Archiver never stores the secret in the archive. At compress time it fetches the password string from the vault and encrypts the archive with it — exactly as if the operator had typed that password. A vault-sourced archive is therefore byte-for-byte identical to a manually-encrypted one, and can be opened either by fetching from the vault again or by typing the literal password. The vault controls who can retrieve the password, not who can open the archive.

Two ways an operator supplies a vault secret (they are mutually exclusive — typing in one clears the other):

Vault Secret ID field ENT (recommended). A dedicated, masked field on the compress/extract/unlock screens. The operator enters only the secret identifier; the app prepends the active provider automatically.
Inline in the password field. Type vault:<provider>:<secretId> directly. The <provider> token is the internal name: bitwarden, onepassword, or hashicorp (note: onepassword, not 1password).

Provider selection. The vault provider chosen and saved in Shared Password Safes (via Save Vault Configuration) is the “active” provider. The Vault Secret ID field only appears when a provider is active, and its content resolves against that saved provider.

Where secrets are stored at restTokens and client secrets are written to Windows Credential Manager under target names SlimArchiver_Vault_<provider>_Token and SlimArchiver_Vault_<provider>_ClientSecret. They are never written to settings.json — that file holds only non-secret config (provider, mode, endpoint URL). Save persists secrets immediately; no restart is required.

2. Token quick-reference (the single most error-prone step)

Each provider/mode expects a different kind of token in the Token field. Getting this wrong is the most common failure.

Provider	Mode	Token field expects	Looks like
Bitwarden	CLI	BW_SESSION value (from `bw unlock`)	long base64, ends `==`
Bitwarden	API	Secrets Manager machine-account access token	`0.<uuid>.<secret>:<base64key>`
1Password	CLI	Service-account token	`ops_…`
1Password	API (Connect)	Connect access token	`eyJ…` (a JWT)
HashiCorp	API	Vault token	`hvs.…`
HashiCorp	CLI	Vault token	`hvs.…`

3. Per-provider setup

Each section lists the app fields to set and the exact Vault Secret ID format. Where a field isn't listed, leave it blank.

3.1 Bitwarden — CLI mode

Install: the bw CLI. Both the standalone bw.exe and the npm-installed shim (bw.cmd) work. Auth: obtain a session — bw login, then bw unlock prints a BW_SESSION value.

App config: Provider Bitwarden · Mode Local CLI executable · CLI Path = full path to bw · Token = the BW_SESSION value.

Vault Secret ID: the Bitwarden item UUID (bw list items --search <name> → id).

GotchasPrefer the full path to the executable in CLI Path. bw alone relies on the app process inheriting your PATH, which it may not. BW_SESSION expires; a stale session yields a clean fetch error, not a hang.

3.2 Bitwarden — API mode (Secrets Manager)

Requires: Bitwarden Secrets Manager enabled on an organization (free tier covers a small machine-account + secret allotment). This is not the personal password vault — API mode is Secrets Manager only. Auth: a Secrets Manager machine-account access token (0.<uuid>.<secret>:<key>), granted read on the target project.

App config: Provider Bitwarden · Mode REST API Client · Token = the SM access token · Endpoint URL = only for self-hosted / EU (https://api.bitwarden.eu); leave blank for US cloud.

Vault Secret ID: the Secrets Manager secret UUID.

NoteThe app decrypts the Secrets Manager response locally (Bitwarden's zero-knowledge model). No Client ID / Client Secret is used — the legacy personal-vault “cipher API” path is intentionally not offered because it cannot return plaintext.

3.3 1Password — CLI mode

Install: the op CLI (op.exe). Auth: a service-account token (ops_…). Create it in the admin console under Developer → Service Account, granting it read on the target vault. The app passes it as OP_SERVICE_ACCOUNT_TOKEN when spawning op.

App config: Provider 1Password · Mode Local CLI executable · CLI Path = full path to op.exe · Token = the ops_… token.

Vault Secret ID: a 1Password secret reference URI — op://<Vault>/<Item>/password (e.g. op://Slimtest/slimtest-op/password). Use the item's title, not a login username.

GotchasA 1Password service account can only be granted vaults created after the service account exists. The default managed vaults (Employee, Shared) don't appear in the grant list — create a new vault for machine access. The item reference uses the item title. If the title is generic (e.g. “Login”), either rename it or use the item UUID in place of the title.

3.4 1Password — API mode (Connect)

Requires: a running 1Password Connect server (Docker) reachable from the workstation, plus a Connect access token and the target Vault ID. Connect is infrastructure you host; standing it up is standard 1Password procedure.

App config: Provider 1Password · Mode REST API Client · Endpoint URL = the Connect host (e.g. http://localhost:8080) · Token = the Connect token (eyJ…, not the service-account token) · Vault ID = the target vault's ID.

Vault Secret ID: the item ID (not an op:// URI). The app requests {endpoint}/v1/vaults/{VaultID}/items/{ItemID} and extracts the password field.

GotchaThe two 1Password modes use different tokens — Connect uses its own JWT token, issued with the Connect server; the ops_… service-account token is for CLI mode only.

3.5 HashiCorp Vault — API mode

Auth: a Vault token (hvs.…) with read on the secret path.

App config: Provider HashiCorp Vault · Mode REST API Client · Endpoint URL = VAULT_ADDR (e.g. http://127.0.0.1:8200) · Token = the Vault token.

Vault Secret ID: the raw API path, which for KV v2 includes the /data/ segment — secret/data/<name> (e.g. secret/data/slimtest).

3.6 HashiCorp Vault — CLI mode

Install: the vault CLI (vault.exe).

App config: Provider HashiCorp Vault · Mode Local CLI executable · CLI Path = full path to vault.exe · Endpoint URL = VAULT_ADDR · Token = the Vault token. (The app passes VAULT_ADDR and VAULT_TOKEN as environment variables to the CLI.)

Vault Secret ID: the logical KV path, without /data/ — secret/<name> (e.g. secret/slimtest). The CLI adds the /data/ segment itself.

Gotcha (important)The path format differs from API mode. API = secret/data/slimtest; CLI = secret/slimtest. Using the API path in CLI mode (or vice-versa) yields a “route not found” / 404-style error.

4. Verifying an integration (also your regression procedure)

Use this to confirm any provider end-to-end. It proves the fetched value is byte-exact without ever displaying the secret:

In the vault, set a test secret's value to a known string, e.g. MyTestPass123.
In Slim Archiver, configure the provider per Section 3 and Save Vault Configuration.
Compress a throwaway file, supplying the Vault Secret ID for that secret.
Extract the resulting archive using the literal password MyTestPass123.

Reading the resultSuccess = the vault fetch returned exactly MyTestPass123 (byte-exact proof). Failure = the fetched value differs; re-check the token, path/reference, and provider/mode. (Optional) Also confirm the Manager-side Unlock using the Vault Secret ID field, and — if you use filename encryption — that an encrypted-names archive lists and extracts via the vault.

5. Troubleshooting

Read the Raw Error line in the failure dialog; it usually names the real cause.

Symptom / raw error	Meaning & fix
`requires an Enterprise license`	The active license isn't Enterprise. Vault resolution is Enterprise-gated.
`spawn … ENOENT` on a `.cmd` path	Windows can't run a `.cmd` shim in some contexts. Use the full path; the app runs `.cmd` / `.bat` through `cmd.exe`. Native `.exe` (`op.exe`, `vault.exe`, standalone `bw.exe`) is simplest.
CLI command timed out	The CLI hung — usually a bad/expired session prompting for input. Refresh the token (`bw unlock`, valid `ops_…`, etc.).
Bitwarden MAC validation failed	Wrong or corrupt Secrets Manager access token. Re-copy the full `0.…:…` token.
HashiCorp connection refused	The Vault server isn't running or VAULT_ADDR is wrong. Confirm the server and endpoint.
HashiCorp route entry not found (404)	Wrong path format — check `/data/` (API) vs logical (CLI); see 3.5 / 3.6.
1Password isn't an item in the vault	Wrong item title or vault. Use the exact title or the item UUID; confirm the vault name (case-sensitive).
1Password No accounts configured	No token was passed, or the service account lacks access to the vault. Set the `ops_…` token and grant the account read on the vault.
Vault request timed out after 15000ms	The endpoint accepted the connection but never responded. Check host/firewall; the app fails cleanly rather than hanging.
Fetched value doesn't decrypt the archive	The Vault Secret ID field and the literal password field are mutually exclusive; a stale value in one may have been used. Clear both and retry with one.

6. Security notes for your records

Secrets are held in Windows Credential Manager, never in settings.json on disk.
Grant vault credentials least privilege — read-only, scoped to the specific project/vault/path used for archiving.
Vault-encrypted archives are not bound to the vault: anyone with the password string can open the archive offline. The vault governs retrieval of the string, not decryption of the archive.
Rotate machine-account / service-account tokens per your normal policy; update the Token field and re-save when you do.

Verified provider/mode matrixThis guide reflects the provider/mode matrix as verified for release: Bitwarden (CLI + Secrets Manager API), 1Password (CLI + Connect API), HashiCorp Vault (API + CLI).