Ronan-WeScale opened a new issue, #12908:
URL: https://github.com/apache/apisix/issues/12908
### Description
## Description
The `key-auth` plugin currently only supports custom header names (default:
`apikey`) for API key authentication. However, it does not support the standard
OAuth 2.0 Bearer token format (`Authorization: Bearer <token>`), which is
widely used in modern APIs and is the standard way to pass authentication
tokens.
## Current Behavior
Currently, when using the `key-auth` plugin:
- The API key can be passed via a custom header (default: `apikey`) or query
parameter
- The `header` parameter allows customization of the header name
- Example: `apikey: my-secret-key` or `X-API-KEY: my-secret-key`
## Expected Behavior
The plugin should support the standard Bearer token format:
- Accept tokens in the format: `Authorization: Bearer <token>`
- When enabled, the plugin should:
- Force the use of the `Authorization` header (ignoring the `header`
parameter)
- Extract the token after the "Bearer " prefix
- Validate the token format strictly
- Update the `WWW-Authenticate` response header to use "Bearer" scheme
instead of "apikey"
## Use Case
Many APIs and OAuth 2.0-based authentication systems use the Bearer token
format as a standard. Supporting this format in the `key-auth` plugin would:
1. **Standards Compliance**: Follow RFC 6750 (Bearer Token Usage) and OAuth
2.0 specifications
2. **Interoperability**: Allow APISIX to work seamlessly with existing OAuth
2.0 clients and tools
3. **Migration**: Enable easier migration from other API gateways that
support Bearer tokens
4. **Developer Experience**: Provide familiar authentication patterns that
developers expect
## Proposed Solution
Add a new boolean parameter `bearer_token` to the plugin schema:
```json
{
"plugins": {
"key-auth": {
"bearer_token": true
}
}
}
```
When `bearer_token` is set to `true`:
- The plugin should read from the `Authorization` header only
- Extract the token after "Bearer " prefix
- Return `401` with error message "Invalid Bearer token format" if the
prefix is missing
- Set `WWW-Authenticate: Bearer realm="key"` in error responses
## Example Configuration
```bash
# Create a consumer
curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
-H "X-API-KEY: ${admin_key}" \
-d '{
"username": "jack",
"plugins": {
"key-auth": {
"key": "my-secret-token"
}
}
}'
# Create a route with bearer_token enabled
curl "http://127.0.0.1:9180/apisix/admin/routes/1"; -X PUT \
-H "X-API-KEY: ${admin_key}" \
-d '{
"uri": "/protected",
"plugins": {
"key-auth": {
"bearer_token": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
# Valid request
curl "http://127.0.0.1:9080/protected"; \
-H "Authorization: Bearer my-secret-token"
# Returns: 200 OK
# Invalid request (missing Bearer prefix)
curl "http://127.0.0.1:9080/protected"; \
-H "Authorization: my-secret-token"
# Returns: 401 Unauthorized
# Response: {"message":"Invalid Bearer token format"}
```
## Benefits
- Backward compatible (default: `false`)
- No breaking changes to existing configurations
- Follows OAuth 2.0 and RFC 6750 standards
- Simple to implement and use
- Improves security by enforcing standard token format
## Alternative Considered
Using the existing `header` parameter set to "Authorization" doesn't work
because:
1. It doesn't validate the "Bearer " prefix
2. The `WWW-Authenticate` response header still uses "apikey" scheme
3. Tokens without "Bearer " prefix would be accepted, which is non-standard
## Environment
- APISIX Version: [version]
- Operating System: [OS]
- Deployment: [Docker/Bare Metal/Kubernetes]
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
