diff --git a/docs/content/assets/img/secure/oidc-auth-flow.png b/docs/content/assets/img/secure/oidc-auth-flow.png new file mode 100644 index 000000000..c41c32558 Binary files /dev/null and b/docs/content/assets/img/secure/oidc-auth-flow.png differ diff --git a/docs/content/secure/secure-api-access-with-jwt.md b/docs/content/secure/secure-api-access-with-jwt.md new file mode 100644 index 000000000..5e853a637 --- /dev/null +++ b/docs/content/secure/secure-api-access-with-jwt.md @@ -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!} diff --git a/docs/content/secure/secure-api-access-with-oidc.md b/docs/content/secure/secure-api-access-with-oidc.md new file mode 100644 index 000000000..f7b18def9 --- /dev/null +++ b/docs/content/secure/secure-api-access-with-oidc.md @@ -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) + +
+ +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!} diff --git a/docs/content/secure/secure-api-access-with-waf.md b/docs/content/secure/secure-api-access-with-waf.md new file mode 100644 index 000000000..455839b99 --- /dev/null +++ b/docs/content/secure/secure-api-access-with-waf.md @@ -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!} diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e1ccb61ee..9f72b634a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -193,6 +193,10 @@ nav: - 'Kubernetes': 'expose/kubernetes.md' - 'Docker': 'expose/docker.md' - 'Swarm': 'expose/swarm.md' + - 'Secure': + - 'Secure Access with JWT Traefik Hub API Gateway': 'secure/secure-api-access-with-jwt.md' + - 'Secure Access with OIDC Traefik Hub API Gateway': 'secure/secure-api-access-with-oidc.md' + - 'Secure Access with a WAF Traefik Hub API Gateway': 'secure/secure-api-access-with-waf.md' - 'Observe': - 'Overview': 'observe/overview.md' - 'Logs & Access Logs': 'observe/logs-and-access-logs.md'