docs: tighten README — tables, less prose

bbhorrigan · claude · bbhorrigan · commit 804f2adff96b · 2026-03-10T00:03:23.000-04:00
Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -1,126 +1,69 @@
 # vault-plugin-database-snowflake
 
-A community-maintained Vault plugin for Snowflake. It is one of the supported plugins for the HashiCorp
-Vault Database Secrets Engine and allows for the programmatic generation of unique,
-ephemeral Snowflake [Database User](https://docs.snowflake.com/en/user-guide/admin-user-management.html)
-credentials in a Snowflake account.
+A community-maintained Vault plugin for Snowflake that generates ephemeral
+[Database User](https://docs.snowflake.com/en/user-guide/admin-user-management.html) credentials
+via the HashiCorp Vault Database Secrets Engine.
 
-This project uses the database plugin interface introduced in Vault version 1.6.0.
+> **Note:** Community fork of [hashicorp/vault-plugin-database-snowflake](https://github.com/hashicorp/vault-plugin-database-snowflake).
+> Requires Vault 1.6+.
 
-> **Note:** This is a community-maintained fork of [hashicorp/vault-plugin-database-snowflake](https://github.com/hashicorp/vault-plugin-database-snowflake),
-> actively maintained by the Snowflake community. The plugin is included in Vault version 1.7+.
-
-> **Snowflake Password Deprecation:** Snowflake is deprecating single-factor password authentication.
-> Key-pair authentication will be required after November 2025. See [Snowflake's announcement](https://docs.snowflake.com/en/release-notes/2025/other/2025-01-17-password-authentication-deprecated)
-> for details. Both the service account connection and dynamic user credential type should be
-> migrated away from passwords before this date.
+> **⚠️ Snowflake is deprecating password authentication after November 2025.**
+> Migrate service account connections and dynamic roles to key-pair auth before that date.
 
 ## Bugs and Feature Requests
 
-Bugs should be filed under the [Issues](https://github.com/bbhorrigan/vault-plugin-database-snowflake/issues) section of this repo.
-
-Feature requests can be submitted in the Issues section as well.
-
-## Security
-
-If you believe you have found a security issue in this plugin, please open a GitHub issue or contact the maintainer directly.
+File issues at [bbhorrigan/vault-plugin-database-snowflake/issues](https://github.com/bbhorrigan/vault-plugin-database-snowflake/issues).
 
 ## Quick Links
 
- * [Database Secrets Engine for Snowflake - Docs](https://developer.hashicorp.com/vault/docs/secrets/databases/snowflake)
- * [Database Secrets Engine for Snowflake - API Docs](https://developer.hashicorp.com/vault/api-docs/secret/databases/snowflake)
- * [Snowflake Website](https://www.snowflake.com/)
- * [Vault Website](https://www.vaultproject.io)
+- [Database Secrets Engine - Docs](https://developer.hashicorp.com/vault/docs/secrets/databases/snowflake)
+- [Database Secrets Engine - API Docs](https://developer.hashicorp.com/vault/api-docs/secret/databases/snowflake)
+- [Snowflake Docs](https://docs.snowflake.com)
 
 ---
 
 ## Service Account Authentication
 
-The plugin connects to Snowflake using a service account. Four authentication methods are supported.
-Choose one based on your environment.
-
-### 1. Key-Pair Authentication (Recommended)
-
-The service account authenticates using an RSA private key. This is the recommended method and
-will be required after Snowflake's November 2025 password deprecation.
-
-**Prerequisites:**
-1. Generate an RSA key pair and assign the public key to your Snowflake service user:
-   ```sql
-   ALTER USER "VAULT-SERVICE-USER" SET RSA_PUBLIC_KEY='<your-public-key-base64>';
-   ```
-2. The public key should be the base64 body only (no PEM headers).
-
-**Configure the connection:**
-```sh
-vault write database/config/my-snowflake \
-  plugin_name=vault-plugin-database-snowflake \
-  connection_url="<account>.snowflakecomputing.com/<database>" \
-  username="VAULT-SERVICE-USER" \
-  private_key=@/path/to/rsa_key_pkcs8.pem \
-  allowed_roles="*"
-```
-
----
+Four methods are supported. Set exactly one per connection config.
 
-### 2. Workload Identity Federation (WIF)
+| Method | Field(s) | When to use |
+|--------|----------|-------------|
+| Key-pair | `private_key` | Recommended default |
+| WIF | `workload_identity_provider` | Cloud-native environments (AWS/GCP/Azure/OIDC) |
+| OAuth 2.0 | `oauth_client_id` + `oauth_client_secret` + `oauth_token_endpoint` | External IdP |
+| Password | `password` | **Deprecated** — removed Nov 2025 |
 
-The service account authenticates using a cloud provider identity — no long-lived credentials
-required. Supported providers: `AWS`, `GCP`, `AZURE`, `OIDC`.
+### Key-Pair
 
-WIF must be enabled in your Snowflake account:
+Assign your public key to the Snowflake user first:
 ```sql
-ALTER ACCOUNT SET ENABLE_IDENTIFIER_FIRST_LOGIN = TRUE;
-```
-
-**AWS (EC2/ECS/Lambda — uses instance/task role automatically):**
-```sh
-vault write database/config/my-snowflake \
-  plugin_name=vault-plugin-database-snowflake \
-  connection_url="<account>.snowflakecomputing.com/<database>" \
-  username="VAULT-SERVICE-USER" \
-  workload_identity_provider="AWS" \
-  allowed_roles="*"
+ALTER USER "VAULT-SERVICE-USER" SET RSA_PUBLIC_KEY='<base64-public-key>';
 ```
 
-**GCP (Compute Engine/Cloud Run — uses metadata service automatically):**
 ```sh
 vault write database/config/my-snowflake \
   plugin_name=vault-plugin-database-snowflake \
   connection_url="<account>.snowflakecomputing.com/<database>" \
   username="VAULT-SERVICE-USER" \
-  workload_identity_provider="GCP" \
+  private_key=@/path/to/rsa_key_pkcs8.pem \
   allowed_roles="*"
 ```
 
-**Azure (Managed Identity — uses IMDS automatically):**
-```sh
-vault write database/config/my-snowflake \
-  plugin_name=vault-plugin-database-snowflake \
-  connection_url="<account>.snowflakecomputing.com/<database>" \
-  username="VAULT-SERVICE-USER" \
-  workload_identity_provider="AZURE" \
-  workload_identity_entra_resource="<optional-entra-resource-url>" \
-  allowed_roles="*"
-```
+### Workload Identity Federation (WIF)
 
-**OIDC (any OIDC-compatible IdP — requires an explicit token):**
 ```sh
 vault write database/config/my-snowflake \
   plugin_name=vault-plugin-database-snowflake \
   connection_url="<account>.snowflakecomputing.com/<database>" \
   username="VAULT-SERVICE-USER" \
-  workload_identity_provider="OIDC" \
-  workload_identity_token="<oidc-jwt-token>" \
+  workload_identity_provider="AWS" \   # AWS | GCP | AZURE | OIDC
   allowed_roles="*"
 ```
 
----
-
-### 3. OAuth 2.0 Client Credentials
+OIDC requires an explicit token: `workload_identity_token="<jwt>"`.
+Azure supports an optional `workload_identity_entra_resource="<url>"`.
 
-The service account authenticates using OAuth 2.0 client credentials flow. The gosnowflake driver
-handles the token exchange with your IdP automatically.
+### OAuth 2.0 Client Credentials
 
 ```sh
 vault write database/config/my-snowflake \
@@ -130,49 +73,25 @@ vault write database/config/my-snowflake \
   oauth_client_id="<client-id>" \
   oauth_client_secret="<client-secret>" \
   oauth_token_endpoint="https://<your-idp>/oauth/token" \
-  oauth_scope="session:role:SYSADMIN" \
-  allowed_roles="*"
-```
-
-`oauth_scope` is optional. `username` is required for OAuth client credentials.
-
----
-
-### 4. Password Authentication (Deprecated)
-
-> **Warning:** Snowflake is removing password authentication after November 2025.
-> Migrate to key-pair, WIF, or OAuth before that date.
-
-```sh
-vault write database/config/my-snowflake \
-  plugin_name=vault-plugin-database-snowflake \
-  connection_url="<account>.snowflakecomputing.com/{{username}}:{{password}}@<account>.snowflakecomputing.com/<database>" \
-  username="VAULT-SERVICE-USER" \
-  password="<password>" \
+  oauth_scope="session:role:SYSADMIN" \   # optional
   allowed_roles="*"
 ```
 
 ---
 
 ## Dynamic User Credential Types
 
-The plugin supports two credential types for dynamically created users. The credential type
-is set per role and determines what Vault returns to the caller.
+Set `credential_type` on the role to control what Vault issues to callers.
 
-### RSA Key-Pair (Recommended)
+| Type | Vault returns | Snowflake auth | Status |
+|------|--------------|----------------|--------|
+| `rsa_private_key` | Private key | Key-pair | **Recommended** |
+| `password` | Password | Password | Deprecated Nov 2025 |
 
-Vault generates a fresh RSA key pair for every credential request. The public key is written
-to Snowflake when the user is created. The private key is returned to the caller. No password
-is ever set on the dynamic user.
+### RSA Key-Pair (Recommended)
 
-**How it works:**
-1. `vault read database/creds/<role>` is called
-2. Vault core generates a new RSA key pair
-3. The plugin runs the creation SQL with `{{public_key}}` substituted (PEM headers stripped per Snowflake requirements)
-4. The private key is returned in the `rsa_private_key` field of the response
-5. When the lease expires, Vault drops the user from Snowflake
+Vault generates a fresh key pair per request. The public key is written to Snowflake at user creation; the private key is returned to the caller.
 
-**Configure the role:**
 ```sh
 vault write database/roles/my-role \
   db_name=my-snowflake \
@@ -182,33 +101,15 @@ vault write database/roles/my-role \
   max_ttl=24h
 ```
 
-**Read credentials:**
 ```sh
 vault read database/creds/my-role
+# Key             Value
+# rsa_private_key -----BEGIN PRIVATE KEY-----...
+# username        v_token_my_role_xxxx_1234567890
 ```
-```
-Key             Value
----             -----
-lease_id        database/creds/my-role/...
-lease_duration  1h
-rsa_private_key -----BEGIN PRIVATE KEY-----
-                ...
-                -----END PRIVATE KEY-----
-username        v_token_my_role_xxxxxxxxxxxxxxxxxxxx_1234567890
-```
-
-The caller uses the private key to authenticate to Snowflake:
-```sh
-snowsql -a <account> -u <username> --private-key-path /path/to/private_key.pem
-```
-
----
 
 ### Password (Deprecated)
 
-> **Warning:** Snowflake is removing password authentication after November 2025.
-> Use `credential_type=rsa_private_key` instead.
-
 ```sh
 vault write database/roles/my-role \
   db_name=my-snowflake \
@@ -219,49 +120,31 @@ vault write database/roles/my-role \
 
 ---
 
-## Configure Plugin
+## Setup
 
-A [scripted configuration](bootstrap/configure.sh) of the plugin is provided in
-this repository. You can use the script or manually configure the secrets engine
-using documentation.
-
-To apply the scripted configuration, run the `make configure` target to
-register, enable, and configure the plugin with your local Vault instance. You
-can specify the plugin name, plugin directory, mount path, connection URL and
-private key path. Default values for plugin name and directory from the
-Makefile will be used if arguments aren't provided.
+A [scripted configuration](bootstrap/configure.sh) is available via `make configure`:
 
 ```sh
-$ PLUGIN_NAME=vault-plugin-database-snowflake \
-  PLUGIN_DIR=$GOPATH/vault-plugins \
-  CONNECTION_URL=foo.snowflakecomputing.com/BAR \
-  PRIVATE_KEY=/path/to/private/key/file \
-  SNOWFLAKE_USERNAME=user1 \
-  make configure
+PLUGIN_NAME=vault-plugin-database-snowflake \
+PLUGIN_DIR=$GOPATH/vault-plugins \
+CONNECTION_URL=foo.snowflakecomputing.com/BAR \
+PRIVATE_KEY=/path/to/private/key/file \
+SNOWFLAKE_USERNAME=user1 \
+make configure
 ```
 
 ---
 
 ## Acceptance Testing
 
-In order to perform acceptance testing, you need to set the environment variable `VAULT_ACC=1`
-as well as provide all the necessary information to connect to a Snowflake Project. All
-`SNOWFLAKE_*` environment variables must be provided in order for the acceptance tests to
-run properly. A cluster must be available during the test. A [30-day trial account](https://signup.snowflake.com/)
-can be provisioned manually to test.
-
-| Environment Variable | Description |
-|----------------------|-------------|
-| SNOWFLAKE_ACCOUNT    | The account string for your snowflake instance. If you are using a non-AWS provider, or a region that isn't us-west-1 for AWS, region and provider should be included here. (example: `ec#####.east-us-2.azure`) |
-| SNOWFLAKE_USER       | The accountadmin level user that you are using with Vault |
-| SNOWFLAKE_PASSWORD   | The password associated with the provided user (optional if using key-pair auth) |
-| SNOWFLAKE_PRIVATE_KEY | Path to the private key file for key-pair authentication |
-| SNOWFLAKE_DB         | optional: The DB you are restricting the connection to |
-| SNOWFLAKE_SCHEMA     | optional: The schema you are restricting the connection to |
-| SNOWFLAKE_WAREHOUSE  | optional: The warehouse you are restricting the connection to |
-
-To run the acceptance tests, invoke `make testacc`:
-
-```sh
-$ make testacc
-```
+Set `VAULT_ACC=1` and the following environment variables, then run `make testacc`.
+
+| Variable | Description |
+|----------|-------------|
+| `SNOWFLAKE_ACCOUNT` | Account identifier (e.g. `ec#####.east-us-2.azure`) |
+| `SNOWFLAKE_USER` | ACCOUNTADMIN-level user for Vault |
+| `SNOWFLAKE_PASSWORD` | Password (optional if using key-pair) |
+| `SNOWFLAKE_PRIVATE_KEY` | Path to private key file |
+| `SNOWFLAKE_DB` | optional |
+| `SNOWFLAKE_SCHEMA` | optional |
+| `SNOWFLAKE_WAREHOUSE` | optional |
