https://github.com/septima/traefik-api-key-auth
Traefik Middleware for authenticating request using either a header, a query string or a prefix of the url path.
https://github.com/septima/traefik-api-key-auth
traefik-plugin
Last synced: 6 months ago
JSON representation
Traefik Middleware for authenticating request using either a header, a query string or a prefix of the url path.
- Host: GitHub
- URL: https://github.com/septima/traefik-api-key-auth
- Owner: Septima
- License: isc
- Created: 2023-09-22T12:11:24.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-24T06:00:26.000Z (about 2 years ago)
- Last Synced: 2025-10-22T22:58:03.657Z (8 months ago)
- Topics: traefik-plugin
- Language: Go
- Homepage:
- Size: 13.7 KB
- Stars: 21
- Watchers: 0
- Forks: 5
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# api-key-auth
This plugin allows you to protect routes with an API key specified in a header, query string param or path segment. If the user does not provide a valid key the middleware will return a 403.
## Config
### Static file
Add to your Traefik static configuration
#### yaml
```yaml
experimental:
plugins:
traefik-api-key-auth:
moduleName: "github.com/Septima/traefik-api-key-auth"
version: "v0.2.3"
```
#### toml
```toml
[experimental.plugins.traefik-api-key-auth]
moduleName = "github.com/Septima/traefik-api-key-auth"
version = "v0.2.3"
```
### CLI
Add to your startup args:
```sh
--experimental.plugins.traefik-api-key-auth.modulename=github.com/Septima/traefik-api-key-auth
--experimental.plugins.traefik-api-key-auth.version=v0.2.3
```
### K8s CRD
```yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: verify-api-key
spec:
plugin:
traefik-api-key-auth:
authenticationHeader: true
authenticationHeaderName: X-API-KEY
bearerHeader: true
bearerHeaderName: Authorization
queryParam: true
queryParamName: token
pathSegment: true
permissiveMode: false
removeHeadersOnSuccess: true
internalForwardHeaderName: ''
internalErrorRoute: ''
keys:
- some-api-key
```
## Plugin options
| option | default | type | description | optional |
|:----------------------------|:------------------|:---------|:------------------------------------------------------------------|:---------|
| `authenticationHeader` | `true` | bool | Use an authentication header to pass a valid key. | ⚠️ |
| `authenticationHeaderName` | `"X-API-KEY"` | string | The name of the authentication header. | ✅ |
| `bearerHeader` | `true` | bool | Use an authorization header to pass a bearer token (key). | ⚠️ |
| `bearerHeaderName` | `"Authorization"` | string | The name of the authorization bearer header. | ✅ |
| `queryParam` | `true` | bool | Use a query string param to pass a valid key. | ⚠️ |
| `queryParamName` | `"token"` | string | The name of the query string param. | ✅ |
| `pathSegment` | `true` | bool | Use match on path segment to pass a valid key. | ⚠️ |
| `permissiveMode` | `false` | bool | Dry-run option to allow the request even if no valid was provided | ✅ |
| `removeHeadersOnSuccess` | `true` | bool | If true will remove the header on success. | ✅ |
| `internalForwardHeaderName` | `""` | string | Optionally forward validated key as header to next middleware. | ✅ |
| `internalErrorRoute` | `""` | string | Optionally route to backend at specified path on invalid key | ✅ |
| `keys` | `[]` | []string | A list of valid keys that can be passed using the headers. | ❌ |
⚠️ - Is optional but at least one of `authenticationHeader`, `bearerHeader`, `queryparam` or `pathSegment` must be set to `true`.
❌ - Required.
✅ - Is optional and will use the default values if not set.