mirror of
https://github.com/traefik/traefik.git
synced 2025-08-07 07:07:12 +02:00
chore: add secure seection
This commit is contained in:
sheddy-traefik
parent
16c536e83a
commit
e7b565bc10
BIN
docs/content/assets/img/secure/oidc-auth-flow.png
Normal file
BIN
docs/content/assets/img/secure/oidc-auth-flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 170 KiB |
204
docs/content/secure/secure-api-access-with-jwt.md
Normal file
204
docs/content/secure/secure-api-access-with-jwt.md
Normal 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 kind 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 REAL_NAME with your values
|
||||
jwksUrl: https://KEYCLOAK_URL/realms/REAL_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
110
docs/content/secure/secure-api-access-with-oidc.md
Normal 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:
|
||||
|
||||
|
||||
|
||||
<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!}
|
||||
180
docs/content/secure/secure-api-access-with-waf.md
Normal file
180
docs/content/secure/secure-api-access-with-waf.md
Normal file
@ -0,0 +1,180 @@
|
||||
---
|
||||
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.
|
||||
|
||||
There are two ways to implement Coraza WAF protection with Traefik:
|
||||
|
||||
- **Native Middleware** (Traefik Hub exclusive): A high-performance native implementation available exclusively in Traefik Hub API Gateway that provides at least 23 times better performance compared to the community plugin version.
|
||||
- **Community WASM Plugin** (Open Source Traefik Proxy): Available as a [community plugin](https://plugins.traefik.io/plugins/65f2aea146079255c9ffd1ec/coraza-waf) in the Traefik Plugin Catalog for open-source Traefik Proxy users through the [coraza-http-wasm-traefik](https://github.com/jcchavezs/coraza-http-wasm-traefik) project.
|
||||
|
||||
!!! note "Performance Advantage"
|
||||
The native middleware implementation in Traefik Hub API Gateway delivers significantly superior performance compared to the WASM-based community plugin available for open-source Traefik Proxy. This performance boost ensures that security enforcement does not compromise application responsiveness.
|
||||
|
||||
!!! note "Rule Compatibility"
|
||||
The native 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}'"
|
||||
```
|
||||
|
||||
```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:
|
||||
- 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
|
||||
```
|
||||
|
||||
```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!}
|
||||
@ -85,6 +85,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'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user