[RFE]: Vault JWT auth via Keycloak JWT and mTLS

[atharvamhaske]

Is your feature request related to a problem? Please describe.

The Vault provider currently supports token and AppRole authentication. Deployments that already use Keycloak or another OIDC provider cannot authenticate the plugin to Vault with short-lived JWTs issued by Keycloak.

This makes it harder to avoid static Vault tokens or AppRole secrets in Docker plugin configuration, especially in environments that require certificate-bound connectivity and stronger identity verification.

Describe the solution you'd like

Add a Vault JWT authentication mode that lets the plugin authenticate to Vault by submitting a Keycloak-issued JWT to the Vault JWT auth API, then using the returned Vault client token for secret reads and rotation checks.

Planned behavior:

• Add VAULT_AUTH_METHOD=jwt.
• Accept a Keycloak-issued JWT from plugin configuration or a mounted file.
• Call the Vault JWT login endpoint, for example auth/<jwt_mount>/login.
• Send the configured Vault JWT role with the login request.
• Store the returned Vault client token in the Vault client.
• Continue using the existing Vault KV read and rotation behavior after authentication.
• Support mTLS for Vault API communication using the existing Vault TLS settings.
• Keep token and AppRole authentication backward compatible.

Expected configuration:

VAULT_AUTH_METHOD=jwt
VAULT_JWT_ROLE=<vault-jwt-role>
VAULT_JWT=<keycloak-issued-jwt>
VAULT_JWT_FILE=/run/secrets/keycloak-jwt
VAULT_JWT_AUTH_PATH=jwt
VAULT_CACERT=/run/secrets/vault-ca.pem
VAULT_CLIENT_CERT=/run/secrets/vault-client.pem
VAULT_CLIENT_KEY=/run/secrets/vault-client-key.pem

Describe alternatives you've considered

• Continue using long-lived VAULT_TOKEN, which is simple but weaker for environments that require short-lived workload identity.
• Continue using AppRole, which works today but still requires distributing role ID and secret ID to the plugin.
• Add full OIDC browser/device flow support, which is not appropriate for a headless Docker secrets plugin.
• Use an external sidecar to exchange Keycloak JWTs for Vault tokens, which adds operational complexity and another runtime dependency.

Acceptance criteria

• VAULT_AUTH_METHOD=jwt is accepted by the Vault provider.
• JWT auth validates required inputs and returns clear errors when role, JWT, or JWT file inputs are missing.
• JWT file input is preferred for secret material, while direct JWT input remains available for simple deployments.
• Vault login uses the configured auth mount path and role.
• mTLS settings continue to apply to the Vault API client before JWT login is attempted.
• Existing token and approle auth flows continue to work unchanged.
• Unit tests cover successful JWT login, missing configuration, login failure, and precedence between direct JWT and JWT file configuration.
• Documentation shows Keycloak-to-Vault JWT auth setup and Docker plugin configuration.

Additional context

This issue follows the planned Vault JWT auth design:

• Keycloak issues the workload JWT.
• The plugin attests to Vault by calling the Vault JWT auth API.
• Vault validates the JWT against its configured OIDC/JWKS settings and bound claims.
• The plugin uses the returned Vault token for normal secret reads.
• Vault API transport can be protected with mTLS using the existing client certificate configuration.

[sanjay7178]

I see keycloak might be a provider for long lived JWT tokens and niche developers usage of our plugin with it .

[atharvamhaske]

I see keycloak might be a provider for long lived JWT tokens and niche developers usage of our plugin with it .

I didn't get you ?

[sanjay7178]

I mean you can get issued JWT token from GIthub CI , OIDC auth ... , So our plugin doesn't have JWT auth yet to use with Vault , although to start integrate JWT into the plugin use openssl and then later on one can implement to use with Keycloak.

[atharvamhaske]

I mean you can get issued JWT token from GIthub CI , OIDC auth ... , So our plugin doesn't have JWT auth yet to use with Vault , although to start integrate JWT into the plugin use openssl and then later on one can implement to use with Keycloak.

okay works