Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions connections/credential-profiles.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,11 @@ A role on Vault's database secrets engine hands out a new database user for ever
| Vault Address | The server, such as `https://vault.example.com:8200`. Leave it empty to use `VAULT_ADDR` |
| Sign In With | **Token** reads `VAULT_TOKEN`, then `~/.vault-token` from `vault login`. **AppRole** takes a role ID and a file holding the secret ID. **OIDC** opens your browser once per launch |

The username field greys out, because Vault generates the username too. **Test Source** reads a lease, shows the username and password it got, and revokes it.
The username field greys out, because Vault generates the username too. **Test Source** shows the username and password the profile's connections sign in with, and reads a lease when none is held.

Each sign-in reads a new lease, so the main connection, a second database, and a backup each sign in as a user of their own. While connected, the lease renews before it expires. When Vault stops renewing it, at the role's maximum TTL or when renewal fails, the connection signs in again with a new lease before the old user is revoked. Disconnecting revokes the lease. The generated password stays in memory: it never reaches the Keychain, `connections.json`, or iCloud.
Everything on one profile signs in as one database user: the main connection, a second database, a backup, and a test. A backup tool that takes the password on its command line, such as SqlPackage, gets a user of its own, revoked when the backup ends. While in use, the lease renews before it expires. When Vault stops renewing it, at the role's maximum TTL or when renewal fails, the connection signs in again with a new lease. The lease is revoked when the last connection using it disconnects, after 10 minutes with nothing using it, and at quit, which waits up to 3 seconds for Vault. The generated password stays in memory: it never reaches the Keychain, `connections.json`, or iCloud.

Some databases refuse a user Vault has just created until they load it, such as Vitess or ProxySQL reloading users on a timer, or a MySQL replica catching up. When a MySQL-family server answers a new user with access denied (error 1045), the connect tries the same user again until 30 seconds after Vault created it, and the connection window shows *Waiting for the database to accept the new Vault user*. If the database still refuses it, the next attempt uses the same user. Any refused sign-in also asks Vault, by renewing the lease, whether it still exists, and a lease Vault no longer has is replaced on the next sign-in. A MySQL-family user the database accepted before and now refuses with error 1045 is replaced too, since Vault renews it without asking the database. On other engines, a user dropped in the database while Vault still has its lease stays in use until every connection on the profile disconnects.

An OIDC role must allow the redirect URI `http://localhost:8250/oidc/callback`, the one `vault login -method=oidc` uses. A connection that needs an OIDC sign-in offers **Sign In** instead of failing.

Expand Down
2 changes: 1 addition & 1 deletion features/connection-sharing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ A connection in `~/Library/Application Support/TablePro/connections.json` can sa
| `onePassword` | `op read` on the reference | `op signin` |
| `vault` | `vault kv get` for one field at a path | `VAULT_ADDR` and `VAULT_TOKEN` in TablePro's environment |
| `awsSecretsManager` | `aws secretsmanager get-secret-value`. `jsonKey` pulls one field out of a JSON secret; omit it for the whole value | |
| `vaultDatabaseRole` | A new lease from `<mount>/creds/<role>`, which supplies the username as well. `auth.method` is `token` (the default), `approle` with `roleId` and `secretIdPath`, or `oidc` with an optional `role`; each takes an optional `mount` | `address`, or `VAULT_ADDR` in TablePro's environment. See [Vault database roles](/connections/credential-profiles#vault-database-roles) |
| `vaultDatabaseRole` | A lease from `<mount>/creds/<role>`, shared by this connection's sign-ins, which supplies the username as well. `auth.method` is `token` (the default), `approle` with `roleId` and `secretIdPath`, or `oidc` with an optional `role`; each takes an optional `mount` | `address`, or `VAULT_ADDR` in TablePro's environment. See [Vault database roles](/connections/credential-profiles#vault-database-roles) |

Every command gets 30 seconds. The three CLI kinds quote each argument, so a reference cannot break out into the shell, and they need the tool on `PATH`, in `/usr/local/bin`, or in `/opt/homebrew/bin`.

Expand Down
Loading