mirrors/traefik
1
0
Fork 0
mirror of https://github.com/traefik/traefik.git synced 2025-09-20 13:21:19 +02:00
Code Issues Projects Releases Wiki Activity

Add New Secure Section to the Documentation

Browse Source
This commit is contained in:
Sheddy 2025-09-11 08:44:04 +01:00 committed by GitHub
parent c294b87a45
commit 01bc0a0a0a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 508 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/content/assets/img/secure/oidc-auth-flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 170 KiB

204
docs/content/secure/secure-api-access-with-jwt.md Normal file
View File

@ -0,0 +1,204 @@
---
title: 'Secure API Access with JWT'
description: 'Traefik Hub API Gateway - Learn how to configure the JWT Authentication middleware for Ingress management.'
---
# Secure API Access with JWT
!!! info "Traefik Hub Feature"
This middleware is available exclusively in [Traefik Hub](https://traefik.io/traefik-hub/). Learn more about [Traefik Hub's advanced features](https://doc.traefik.io/traefik-hub/api-gateway/intro).
JSON Web Token (JWT) (defined in the [RFC 7519](https://tools.ietf.org/html/rfc7519)) allows
Traefik Hub API Gateway to secure the API access using a token signed using either a private signing secret or a plublic/private key.
Traefik Hub API Gateway provides many kinds of sources to perform the token validation:
- Setting a secret value in the middleware configuration (option `signingSecret`).
- Setting a public key: In that case, users should sign their token using a private key, and the public key can be used to verify the signature (option `publicKey`).
- Setting a [JSON Web Key (JWK)](https://datatracker.ietf.org/doc/html/rfc7517) file to define a set of JWK to be used to verify the signature of the incoming JWT (option `jwksFile`).
- Setting a [JSON Web Key (JWK)](https://datatracker.ietf.org/doc/html/rfc7517) URL to define the URL of the host serving a JWK set (option `jwksUrl`).
!!! note "One single source"
The JWT middleware does not allow you to set more than one way to validate the incoming tokens.
When a Hub API Gateway receives a request that must be validated using the JWT middleware, it verifies the token using the source configured as described above.
If the token is successfully checked, the request is accepted.
!!! note "Claim Usage"
A JWT can contain metadata in the form of claims (key-value pairs).
The claims contained in the JWT can be used for advanced use-cases such as adding an Authorization layer using the `claims`.
More information in the [dedicated section](../reference/routing-configuration/http/middlewares/jwt.md#claims).
## Verify a JWT with a secret
To allow the Traefik Hub API Gateway to validate a JWT with a secret value stored in a Kubernetes Secret, apply the following configuration:
```yaml tab="Middleware JWT"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-jwt
namespace: apps
spec:
plugin:
jwt:
signingSecret: "urn:k8s:secret:jwt:signingSecret"
```
```yaml tab="Kubernetes Secret"
apiVersion: v1
kind: Secret
metadata:
name: jwt
namespace: apps
stringData:
signingSecret: mysuperlongsecret
```
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: my-app
namespace: apps
spec:
entryPoints:
- websecure
routes:
- match: Path(`/my-app`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: test-jwt
```
```yaml tab="Service & Deployment"
kind: Deployment
apiVersion: apps/v1
metadata:
name: whoami
namespace: apps
spec:
replicas: 3
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
name: whoami
namespace: apps
spec:
ports:
- port: 80
name: whoami
selector:
app: whoami
```
## Verify a JWT using an Identity Provider
To allow the Traefik Hub API Gateway to validate a JWT using an Identity Provider, such as Keycloak and Azure AD in the examples below, apply the following configuration:
```yaml tab="JWKS with Keycloak URL"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-jwt
namespace: apps
spec:
plugin:
jwt:
# Replace KEYCLOAK_URL and REALM_NAME with your values
jwksUrl: https://KEYCLOAK_URL/realms/REALM_NAME/protocol/openid-connect/certs
# Forward the content of the claim grp in the header Group
forwardHeaders:
Group: grp
# Check the value of the claim grp before sending the request to the backend
claims: Equals(`grp`, `admin`)
```
```yaml tab="JWKS with Azure AD URL"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-jwt
namespace: apps
spec:
plugin:
jwt:
jwksUrl: https://login.microsoftonline.com/common/discovery/v2.0/keys
```
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: my-app
namespace: apps
spec:
entryPoints:
- websecure
routes:
- match: Path(`/my-app`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: test-jwt
```
```yaml tab="Service & Deployment"
kind: Deployment
apiVersion: apps/v1
metadata:
name: whoami
namespace: apps
spec:
replicas: 3
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
name: whoami
namespace: apps
spec:
ports:
- port: 80
name: whoami
selector:
app: whoami
```
!!! note "Advanced Configuration"
Advanced options are described in the [reference page](../reference/routing-configuration/http/middlewares/jwt.md).
For example, the metadata recovered from the Identity Provider can be used to restrict the access to the applications.
To do so, you can use the `claims` option, more information in the [dedicated section](../reference/routing-configuration/http/middlewares/jwt.md#claims).
{!traefik-for-business-applications.md!}

110
docs/content/secure/secure-api-access-with-oidc.md Normal file
View File

@ -0,0 +1,110 @@
---
title: 'Secure API Access with OIDC'
description: 'Traefik Hub API Gateway - The OIDC Authentication middleware secures your applications by delegating the authentication to an external provider.'
---
# Secure API Access with OIDC
!!! info "Traefik Hub Feature"
This middleware is available exclusively in [Traefik Hub](https://traefik.io/traefik-hub/). Learn more about [Traefik Hub's advanced features](https://doc.traefik.io/traefik-hub/api-gateway/intro).
OpenID Connect Authentication is built on top of the OAuth2 Authorization Code Flow (defined in [OAuth 2.0 RFC 6749, section 4.1](https://tools.ietf.org/html/rfc6749#section-4.1)).
It allows an application to be secured by delegating authentication to an external provider (Keycloak, Okta etc.)
and obtaining the end user's session claims and scopes for authorization purposes.
To authenticate the user, the middleware redirects through the authentication provider.
Once the authentication is complete, users are redirected back to the middleware before being authorized to access the upstream application, as described in the diagram below:
![OpenID Connect authentication flow](../assets/img/secure/oidc-auth-flow.png)
<br />
To allow the OIDC Middleware to use the credentials provided by the requests, apply the following configuration:
```yaml tab="Middleware OIDC"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: oidc-login
namespace: apps
spec:
plugin:
oidc:
issuer: MY_ISSUER_URL
clientId: "urn:k8s:secret:oidc-client:client_id"
clientSecret: "urn:k8s:secret:oidc-client:client_secret"
redirectUrl: /oidc/callback
```
```yaml tab="Kubernetes Secrets"
apiVersion: v1
kind: Secret
metadata:
name: oidc-client
stringData:
client_id: my-oauth-client-ID # Set your ClientID here
client_secret: my-oauth-client-secret # Set your client secret here
```
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: secure-applications-apigateway-oauth2-client-credentials
namespace: apps
spec:
entryPoints:
- websecure
routes:
- match: Path(`/my-app`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: oidc-login
```
```yaml tab="Service & Deployment"
kind: Deployment
apiVersion: apps/v1
metadata:
name: whoami
namespace: apps
spec:
replicas: 3
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
name: whoami
namespace: apps
spec:
ports:
- port: 80
name: whoami
selector:
app: whoami
```
!!! note "Advanced Configuration"
Advanced options are described in the [reference page](../reference/routing-configuration/http/middlewares/oidc.md).
For example, you can find how to customize the session storage:
- Using a cookie ([Options `session`](../reference/routing-configuration/http/middlewares/oidc.md#configuration-options) (default behavior))
- Using a [Redis store](../reference/routing-configuration/http/middlewares/oidc.md#sessionstore).
{!traefik-for-business-applications.md!}

190
docs/content/secure/secure-api-access-with-waf.md Normal file
View File

@ -0,0 +1,190 @@
---
title: 'Secure API Access with WAF'
description: 'Traefik Hub API Gateway - Learn how to configure the Coraza Web Application Firewall middleware to protect your applications from common web attacks.'
---
# Secure API Access with WAF
!!! info "Traefik Hub Feature"
This middleware is available exclusively in [Traefik Hub](https://traefik.io/traefik-hub/). Learn more about [Traefik Hub's advanced features](https://doc.traefik.io/traefik-hub/api-gateway/intro).
The [Coraza Web Application Firewall](https://coraza.io/) middleware in Traefik Hub API Gateway provides comprehensive protection against common web application attacks. The middleware supports the Coraza rule syntax and is compatible with [OWASP Core Rule Set (CRS)](https://coreruleset.org/docs/), allowing you to leverage proven security rules maintained by the security community.
## Basic WAF Protection
To protect your applications with custom security rules, apply the following configuration:
```yaml tab="Middleware WAF"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: waf-protection
namespace: apps
spec:
plugin:
coraza:
directives:
- SecRuleEngine On
- SecRule REQUEST_URI "@streq /admin" "id:101,phase:1,t:lowercase,log,deny"
- SecRule ARGS "@detectSQLi" "id:102,phase:2,block,msg:'SQL Injection Attack Detected',logdata:'Matched Data: %{MATCHED_VAR} found within %{MATCHED_VAR_NAME}'"
```
This configuration implements three security directives that work together to protect an application:
- **SecRuleEngine On**: Activates the WAF engine to begin processing incoming requests. Without this directive, all other rules remain inactive regardless of their configuration.
- **Admin Path Protection**: The second rule blocks all access to `/admin` paths by examining the request URI. This completely prevents access to administrative interfaces that often contain sensitive functionality like user management, system configuration, or database administration tools. The rule triggers during phase 1 (request headers processing) and applies lowercase transformation to catch variations like `/Admin` or `/ADMIN`.
- **SQL Injection Detection**: The third rule scans request parameters (query strings and form data) for SQL injection patterns using Coraza's built-in detection engine. The `ARGS` variable covers query string parameters like `?id=1` and form data from POST requests like `username=admin&password=123`, but does not include cookies. SQL injection attacks attempt to manipulate database queries by injecting malicious SQL code through user inputs. When detected, the rule blocks the request and logs detailed information about the attempted attack, including which parameter contained the malicious payload.
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: protected-app
namespace: apps
spec:
entryPoints:
- websecure
routes:
- match: Path(`/my-app`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: waf-protection
```
```yaml tab="Service & Deployment"
kind: Deployment
apiVersion: apps/v1
metadata:
name: whoami
namespace: apps
spec:
replicas: 3
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
name: whoami
namespace: apps
spec:
ports:
- port: 80
name: whoami
selector:
app: whoami
```
## Advanced Protection with OWASP Core Rule Set
To implement comprehensive protection using the OWASP Core Rule Set, which provides battle-tested rules against common attack patterns, apply the following configuration:
```yaml tab="Middleware WAF with CRS"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: waf-crs-protection
namespace: apps
spec:
plugin:
coraza:
crsEnabled: true
directives:
- SecRuleEngine On
- SecDefaultAction "phase:1,log,auditlog,deny,status:403"
- SecDefaultAction "phase:2,log,auditlog,deny,status:403"
- SecAction "id:900110, phase:1, pass, t:none, nolog, setvar:tx.inbound_anomaly_score_threshold=5, setvar:tx.outbound_anomaly_score_threshold=4"
- SecAction "id:900200, phase:1, pass, t:none, nolog, setvar:'tx.allowed_methods=GET POST'"
- Include @owasp_crs/REQUEST-911-METHOD-ENFORCEMENT.conf
- Include @owasp_crs/REQUEST-949-BLOCKING-EVALUATION.conf
```
This advanced configuration implements [OWASP Core Rule Set (CRS)](https://coreruleset.org/docs/) protection with anomaly scoring:
- **SecDefaultAction for Phase 1 & 2**: Sets default behavior for request processing phases. Phase 1 processes request headers while Phase 2 processes request body. When rules match, they log the event to both standard and audit logs, then deny the request with a 403 status code.
- **Anomaly Score Configuration**: The first `SecAction` sets anomaly score thresholds where `inbound_anomaly_score_threshold=5` means requests scoring 5 or higher are blocked, and `outbound_anomaly_score_threshold=4` applies the same logic to responses. This scoring system allows multiple suspicious patterns to accumulate points rather than blocking on first detection, reducing false positives while maintaining security.
- **Allowed Methods Configuration**: The second `SecAction` restricts HTTP methods to only `GET` and `POST` requests. This prevents potentially dangerous methods like `PUT`, `DELETE`, `PATCH`, or `OPTIONS` that could modify server resources or reveal system information.
- **METHOD-ENFORCEMENT Rule Set**: The `REQUEST-911-METHOD-ENFORCEMENT.conf` file enforces the allowed HTTP methods policy defined above. It checks incoming requests against the permitted methods and contributes to the anomaly score for disallowed methods.
- **BLOCKING-EVALUATION Rule Set**: The `REQUEST-949-BLOCKING-EVALUATION.conf` file evaluates the accumulated anomaly score against the configured thresholds. If the total score exceeds the threshold, it triggers the blocking action, preventing the request from reaching your application.
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: crs-protected-app
namespace: apps
spec:
entryPoints:
- websecure
routes:
- match: Path(`/my-app`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: waf-crs-protection
```
```yaml tab="Service & Deployment"
kind: Deployment
apiVersion: apps/v1
metadata:
name: whoami
namespace: apps
spec:
replicas: 3
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
name: whoami
namespace: apps
spec:
ports:
- port: 80
name: whoami
selector:
app: whoami
```
!!! warning
Starting with Traefik Hub v3.11.0, Coraza requires read/write permissions to `/tmp`. This requirement stems from upstream changes in the Coraza engine.
!!! note "Advanced Configuration"
Advanced options and detailed rule configuration are described in the [reference page](../reference/routing-configuration/http/middlewares/waf.md).
The WAF middleware supports extensive customization through Coraza directives. You can create custom rules, tune detection thresholds, configure logging levels, and integrate with external threat intelligence feeds. For comprehensive rule writing guidance, consult the [Coraza documentation](https://coraza.io/docs/tutorials/introduction/) and [OWASP CRS documentation](https://coreruleset.org/docs/).
{!traefik-for-business-applications.md!}

4
docs/mkdocs.yml
View File

@ -193,6 +193,10 @@ nav:
- 'Kubernetes': 'expose/kubernetes.md'
- 'Docker': 'expose/docker.md'
- 'Swarm': 'expose/swarm.md'
- 'Secure':
- '<span class="nav-link-with-icon">Secure Access with JWT <img src="https://doc.traefik.io/traefik-hub/img/ps-traefik-hub-logo-light.svg" class="menu-icon" alt="Traefik Hub API Gateway"></span>': 'secure/secure-api-access-with-jwt.md'
- '<span class="nav-link-with-icon">Secure Access with OIDC <img src="https://doc.traefik.io/traefik-hub/img/ps-traefik-hub-logo-light.svg" class="menu-icon" alt="Traefik Hub API Gateway"></span>': 'secure/secure-api-access-with-oidc.md'
- '<span class="nav-link-with-icon">Secure Access with a WAF <img src="https://doc.traefik.io/traefik-hub/img/ps-traefik-hub-logo-light.svg" class="menu-icon" alt="Traefik Hub API Gateway"></span>': 'secure/secure-api-access-with-waf.md'
- 'Observe':
- 'Overview': 'observe/overview.md'
- 'Logs & Access Logs': 'observe/logs-and-access-logs.md'