# Vault Plugin
The Vault plugin generates bearer tokens from vault-saved tokens based on OAuth2 configuration protecting a tool.
It receives a dictionary of secrets and use them to dispatch the authorization token to the server based on rules.
## Features
- **Tag-based metadata handling**: Supports dict format `{"id": "...", "label": "..."}`
- Supported tags must be created on an MCP server to drive the secret handling:
- system:<system host> where system host is the IDP provider for that MCP Server. For example system:github.com or system:mural.com
- AUTH_HEADER:<header name> where header name is the authorization header to be used for this MCP header if a PAT token is send
- **Complex token key format**: Supports secrets send via a header containing a JSON dictionary with keys like `github.com:USER:OAUTH2:TOKEN` or simple `github.com`
- **PAT (Personal Access Token) support**: Use `AUTH_HEADER` tag to specify a custom header to be dispatched to the backend server.
- **OAuth2 token support**: Default bearer token handling for OAuth2 tokens. If no specific rule for PAT the default behavior is to send the secret as Bearer token in Authorization header
- **Flexible configuration**: Falls back to default bearer token behavior when parts are missing
## Configuration
### Basic Configuration
```yaml
vault:
enabled: true
config:
system_tag_prefix: "system"
vault_header_name: "X-Vault-Tokens"
vault_handling: "raw"
system_handling: "tag"
auth_header_tag_prefix: "AUTH_HEADER"
```
### Configuration Options
- **system_tag_prefix**: Prefix for system identification tags (default: `"system"`)
- **vault_header_name**: HTTP header name for vault tokens (default: `"X-Vault-Tokens"`)
- **vault_handling**: Token handling mode (default: `"raw"`). Future version will handle token unwrapping
- **system_handling**: System identification mode (default: `"tag"`)
- **auth_header_tag_prefix**: Prefix for auth header tags (default: `"AUTH_HEADER"`)
## Token Key Format
The plugin supports complex token keys in the format:
```
system[:scope][:token_type][:token_name]
```
Where:
- **system** (required): The system identifier (e.g., `github.com`, `gitlab.com`)
- **scope** (optional): USER or GROUP (ignored in processing)
- **token_type** (optional): PAT or OAUTH2
- **token_name** (optional): Name of the token
### Examples
1. **Simple key**: `github.com`
- Uses default OAuth2 bearer token handling
2. **Full PAT key**: `github.com:USER:PAT:my-token`
- System: `github.com`
- Scope: `USER` (ignored)
- Token type: `PAT`
- Token name: `my-token`
- Checks for `AUTH_HEADER` tag to determine header name
3. **OAuth2 key**: `gitlab.com:GROUP:OAUTH2:app-token`
- System: `gitlab.com`
- Scope: `GROUP` (ignored)
- Token type: `OAUTH2`
- Token name: `TOKEN` (default name)
- Uses OAuth2 bearer token handling
## Token Type Handling
### PAT (Personal Access Token)
When `token_type` is `PAT`:
1. Checks if AUTH_HEADER:header tag exists
2. If found, uses the configured custom header
3. If not found, falls back to `Authorization: Bearer <token>`
### OAUTH2
When `token_type` is `OAUTH2` or missing:
- Uses standard `Authorization: Bearer <token>` header
### Unknown Types
For any other token type:
- Logs a warning
- Falls back to `Authorization: Bearer <token>`
## Gateway Metadata Tags
The plugin handles tags in dict format:
```json
{
"tags": [
{"id": "auto-generated-id", "label": "system:github.com"},
{"id": "another-id", "label": "AUTH_HEADER:X-GitHub-Token"},
{"id": "third-id", "label": "environment:production"}
]
}
```
The plugin extracts the `label` field from dict tags (the actual tag value), while `id` is autogenerated.
### Tag Types
1. **System Tag**: `system:<system_name>`
- Identifies which system the token is for
- Example: `system:github.com`
- Required for the plugin to work
2. **Auth Header Tag**: `AUTH_HEADER:<header_name>`
- Specifies custom header for PAT tokens
- Example: `AUTH_HEADER:X-GitHub-Token`
- Only used when token type is PAT
- Optional - falls back to Bearer token if not present
## Example Usage
### Request with Vault Tokens
```http
POST /api/tools/invoke
X-Vault-Tokens: {"github.com:USER:PAT:my-token": "ghp_xxxxxxxxxxxx", "gitlab.com": "glpat-yyyyyyyy"}
```
### Gateway with AUTH_HEADER Tag
If gateway has tags including `AUTH_HEADER:X-GitHub-Token`:
```json
{
"tags": [
{"id": "1", "label": "system:github.com"},
{"id": "2", "label": "AUTH_HEADER:X-GitHub-Token"}
]
}
```
The plugin will set:
```http
X-GitHub-Token: ghp_xxxxxxxxxxxx
```
### Without AUTH_HEADER Tag
If no `AUTH_HEADER` tag is defined, the plugin will use default Bearer token:
```http
Authorization: Bearer ghp_xxxxxxxxxxxx
```
## System Identification
The plugin supports two modes for identifying the system:
### TAG Mode (Default)
Extracts system from gateway tags with the configured prefix:
- Tag: `system:github.com` → System: `github.com`
### OAUTH2_CONFIG Mode
Extracts system from the OAuth2 configuration's `token_url`:
- Token URL: `https://github.com/login/oauth/access_token` → System: `github.com`
## Hook
- **tool_pre_invoke**: Processes vault tokens before tool invocation
## Testing
## Create a token
export MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key
export CLIENT_ID=xxx
export CLIENT_SECRET=xxx
## Register MCP server with the gateway and add OAuth2 configuration Using UI
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "github_com",
"url": "https://api.githubcopilot.com/mcp/",
"description": "A new MCP server added with OAuth2 authentication",
"auth_type": "oauth",
"auth_value": {
"client_id": "'$CLIENT_ID'",
"client_secret": "'$CLIENT_SECRET'",
"token_url": "https://github.com/login/oauth/access_token",
"redirect_url": "http://localhost:4444/oauth/callback"
},
"tags": ["system:github.com"],
"passthrough_headers": ["X-Vault-Tokens"]
}' \
http://localhost:4444/gateways
## Invocation
When the server is configured invoke the server and send a pass through header of form
"X-Vault-Tokens": {
"github.com": "key"
},
## Sample of Invoking a Tool on the Added Gateway
```bash
# Invoke a tool on the added gateway
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-H 'X-Vault-Tokens: "{\"github.com\": \"key\"}"' \
-d '{
"tool_name": "github-com-list-issues",
"arguments": {
"repo": "reponame"
}
}' \
http://localhost:4444/tools/invoke
```
