How to Revert an Accidental Override of Vault’s Built‑In JWT Auth Plugin

Avatar
Eduardo Munoz
  • Updated

The information contained in this article has been verified as up‑to‑date on the date of the original publication of the article. HashiCorp endeavors to keep this information up‑to‑date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only. Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction
Vault identifies each authentication method by a global plugin name. The built‑in JWT auth method uses the reserved name jwt. When an external plugin is registered using this same name, Vault interprets it as an override of the built‑in implementation. According to HashiCorp’s official plugin registration behavior, Vault will default to the manually registered plugin when the same name is used for a built‑in plugin type. 

As a result, all JWT auth mounts in the cluster begin running the externally registered plugin binary instead of the Vault supplied built-in. This can introduce unintended environment variables (such as HTTP_PROXY), network behavior changes, or authentication failures. Deregistering the plugin alone does not immediately revert mounts to the built-in implementation because Vault continues running the previously loaded plugin binary until it is explicitly reloaded. 

This article explains how to safely undo an accidental override, restore the built‑in JWT auth plugin, and verify that all JWT mounts are once again using the correct Vault‑provided implementation.

Expected Outcome
After completing this procedure:
The plugin catalog will no longer contain an external entry named jwt.

All JWT auth mounts will return to using the built‑in JWT auth plugin.
  • The Running SHA256 value for all JWT auth mounts will show n/a, indicating built-in usage per auth list -detailed documentation.
  • Any unintended environment variables (such as proxy settings inherited during plugin registration) will no longer affect JWT authentication flows.

Prerequisites
  • Vault operator privileges allowing:
  • vault plugin deregister
  • vault plugin reload
  • Reading /sys/plugins/catalog/auth
  • Access during a maintenance or low‑traffic window (recommended)
  • All Vault versions that support external plugin registration

Use Case
This procedure is required when:
  • An operator unintentionally runs:
vault plugin register -sha256=... -env HTTP_PROXY=... auth jwt
An external plugin is mistakenly registered under the name jwt, overriding Vault’s built-in JWT auth plugin.

JWT authentication behavior changes cluster‑wide (e.g., unexpected proxy usage).
  • Deregistering the plugin does not fix the issue because the previously loaded external plugin binary remains active until reloaded.

Procedure
Step 1: Verify the Current Plugin State
Check whether the external plugin override is still present.
vault plugin info auth jwt
Expected symptoms of an override:
  • builtin = false
  • sha256 = <hash>
  • command = jwt
  • version = n/a or a user‑registered version
These fields correspond to Vault’s catalog data structure for external plugins, which include command, SHA256, and built-in status.

Step 2: Deregister the External JWT Plugin
Remove the catalog entry that overrides the built-in plugin:
vault plugin deregister auth jwt
Vault always returns success whether or not the entry exists, as documented in HashiCorp’s deregistration behavior.

Step 3:  Confirm the Catalog Entry Has Been Removed
Check again:
vault plugin info auth jwt
Expected output for a built-in plugin:
• builtin = true
• sha256 = n/a
• command = n/a
• version = vX.Y.Z+builtin
(version label depends on Vault release)
This matches HashiCorp’s documented output for built-in plugins, which shows builtin = true and no SHA256 value.

Step 4: Reload the JWT Auth Plugin Across the Cluster
Even after deregistration, Vault continues to run the previously loaded plugin binary.
Reload it to force all mounts to load the built-in implementation:
vault plugin reload -type=auth -plugin=jwt
This behavior is explicitly documented: reloading by plugin name reloads all mounts that use that plugin backend.

Note:
If running Vault in HA mode, the reload command must be run per node, or a rolling restart may be used instead.

Step 5: Verify the Running Plugin Version
Run:
vault auth list -detailed
Look for the JWT mounts. Expected fields:
  • Version = n/a
  • Running Version reflects built-in plugin
  • Running SHA256 = n/a
Per documentation, n/a in these fields indicate built-in or unversioned plugin usage. This ensures the override is fully removed.
• Plugin info command

Articles in this section

See more

Related articles