--- title: Managing agent keys using HashiCorp Vault summary: null url: >- https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/agent-management/hashicorp-vault --- With the Signal Sciences plugin for HashiCorp Vault, you can use Vault to manage the keys for your Next-Gen WAF agents. Vault is an identity-based secrets and encryption management system. Specifically, the plugin allows: - Vault to store the Agent Access Keys and Agent Secret Keys for your sites (also known as workspaces). - the Vault agent to pull the keys from Vault when needed and give the keys to the deployed Next-Gen WAF agent. - Vault to rotate or replace the keys. When Vault replaces keys, the Vault agent updates the configuration file for the relevant Next-Gen WAF agent and restarts the Next-Gen WAF agent. - authenticated applications, services, and machines to read the keys that are stored in Vault. ## Limitations and considerations Before setting up the plugin to manage the keys in Vault, keep the following in mind: - To use the Signal Sciences plugin for HashiCorp Vault, Vault must already be installed and [configured to load external plugins](https://developer.hashicorp.com/vault/docs/configuration#plugin_directory). - The key rotation process automatically restarts the Next-Gen WAF agent. Due to the agent's brief downtime during key rotation, we recommend rotating the keys during a maintenance window. - The Signal Sciences plugin for HashiCorp Vault is only supported on Linux on x86 CPU architectures. ## Set up plugin To set up the plugin for the first time on systems that use `systemd`, follow these steps: 1. Using the curl command line tool, copy the plugin binary to the external plugins directory: ```term copy nolinenums $ curl -O https://dl.security.fastly.com/vault-plugin-sigsci/latest/vault-plugin-sigsci.tar.gz $ tar xzvf vault-plugin-sigsci.tar.gz $ vault plugin register -sha256=$(sha256sum vault-plugin-sigsci|cut -c-64) secret vault-plugin-sigsci ``` 2. Using the command line, enable the plugin: ```term copy $ vault secrets enable -path=sigsci vault-plugin-sigsci ``` Vault mounts the plugin at path `/sigsci`. 3. [Create a user](https://www.fastly.com/documentation/guides/next-gen-waf/account-info/managing-users/) for the plugin. Assign the user the **User** role. An invitation email is sent to the email address you supplied for the plugin user. 4. From the plugin user's email account, open the invitation email and click **Accept invite**. The account creation form appears. 5. Fill out the account creation form: - Leave the **Email address** field as is. - In the **Name** field, enter `vault-user`. - In the **Password** field, enter a password for the account. - In the **Confirm password** field, enter the password again. 6. Click **Create account**. 7. [Create an API access token](https://www.fastly.com/documentation/guides/next-gen-waf/developer/using-an-api-with-the-next-gen-waf#creating-api-access-tokens) for the plugin user. Signal Sciences cloud API credentials are required for reading and managing agent keys. 8. Using the command line, copy the API access token to `token.txt` file: ```term copy $ vault write -f /sigsci/role/vault-user corp= email= token=@token.txt ``` Replace `` with the ID of your corp (account) and `` with the plugin user's email address. 9. Using the command line, copy agent keys for a single site (workspace) or all sites (workspaces) to vault: ```term copy $ vault write -f /sigsci/creds/vault-user/sites/ ``` Replace `` with the name of the site (workspace). or ```term copy $ vault write -f /sigsci/creds/vault-user/sites/ ``` 10. [Install and configure the Vault agent](https://developer.hashicorp.com/vault/docs/agent-and-proxy/agent#start-vault-agent) using the following template: ```text copy template { source = "/etc/signalsciences/agent.ctmpl" destination = "/etc/signalsciences/agent.conf" } ``` The Vault agent automates the rendering of the Next-Gen WAF agent configuration template when the agent keys are rotated. Example content of the configuration template `/etc/signalsciences/agent.ctmpl`: ```text {{ with secret "sigsci/creds/vault-user/sites/" }} accesskeyid={{ .Data.accessKey }} secretkey={{ .Data.secretKey }} {{ end }} ``` 11. Using the command line, create a systemd service to restart the agent: ```term copy nolinenums $ sudo tee -a /etc/systemd/system/sigsci-agent-restart.service < ``` Replace `` with the name of the relevant site (workspace). 2. Using the command line, delete the non-primary keys in Vault: ```term copy $ vault delete /sigsci/rotate/sites/ ``` Replace `` with the name of the relevant site (workspace). ## Manage plugin roles and keys Once the plugin is [set up](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/agent-management/hashicorp-vault#set-up-plugin), you can use the command line to perform these actions: | Action | Command | | ------------------------------------------------------------- | ----------------------------------------------------------- | | List roles | `vault read /sigsci/role/` | | Read role details | `vault read /sigsci/role/vault-user` | | Delete role | `vault delete /sigsci/role/vault-user` | | Copy keys for one site (workspace) to Vault | `vault write -f /sigsci/creds/vault-user/sites/` | | Copy keys for all sites (workspaces) to Vault | `vault write -f /sigsci/creds/vault-user/sites/` | | Rotate keys for a site (workspace) | `vault write -f /sigsci/rotate/sites/` | | List keys for all sites (workspaces) | `vault read /sigsci/creds/vault-user/sites/` | | Read keys for one site (workspace) | `vault read /sigsci/creds/vault-user/sites/` | | Delete the non-primary keys for a site (workspace) from Vault | `vault delete /sigsci/rotate/sites/` | | Delete the keys for a site (workspace) from Vault | `vault delete /sigsci/creds/vault-user/sites/` | ## Related content - [Using an API with the Next-Gen WAF](https://www.fastly.com/documentation/guides/next-gen-waf/developer/using-an-api-with-the-next-gen-waf)