Skip to main content

Upstream Authentication

Traefik Hub enables seamless upstream authentication to backend APIs using dedicated middleware configurations. This guide demonstrates how to implement common authentication patterns required when your backend APIs expect specific authentication credentials.

Understanding Upstream Authentication​

Upstream authentication occurs when Traefik Hub automatically injects authentication credentials into requests before forwarding them to backend APIs. This pattern is essential when migrating from existing API platforms where backend services expect specific authentication formats.

The request flow in the context of upstream authentication is:

  1. Client authenticates to the gateway using an API key or a JWT (client authentication)
  2. Gateway authorizes the request based on configured policies (plans, subscriptions, RBAC)
  3. Gateway injects upstream credentials using Traefik Hub middlewares (Headers, Query Parameter, or OAuth Client Credentials)
  4. Backend service receives the request with the required upstream authentication

This approach decouples client authentication from upstream authentication, allowing you to maintain existing backend authentication requirements while providing a unified consumer experience.

Obtaining client credentials

Clients typically obtain their API key or JWT via the API Portal or an external IdP (for example, Okta or Keycloak). Those client credentials are used at the gateway (step 1) and are independent of the upstream credentials injected by the gateway (step 3).

Service accounts in Oracle OCI API Platform

Many Oracle deployments use a static service account identity for the gateway to authenticate to upstream services. The backend authorizes the gateway as the consumer and remains protected, even if clients are anonymous at the edge. The original caller’s identity is not propagated by the upstream authentication itself, but applications can carry user context in the request payload or headers as business data.

You can model a service account with:

  • BasicAuth or an API key injected by the gateway
  • OAuth 2.0 Client Credentials (gateway obtains and forwards an access token)

BasicAuth Pattern​

BasicAuth upstream authentication injects HTTP Basic Authentication headers into requests before forwarding them to backend APIs. This pattern is commonly used with legacy APIs that expect traditional username/password authentication.

The Headers middleware handles BasicAuth by adding a static Authorization header with Base64-encoded credentials.

BasicAuth upstream authentication using Headers middleware
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: upstream-basicauth
  namespace: apps
spec:
  headers:
    customRequestHeaders:
      Authorization: "Basic YXBpLWNsaWVudDpzZWN1cmUtcGFzc3dvcmQ="

Security Considerations​

For production deployments, avoid hardcoded BasicAuth credentials in the Headers middleware. Use a plugin that supports secret references, or prefer OAuth Client Credentials when possible.

Simple header injection
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: upstream-basicauth
  namespace: apps
spec:
  headers:
    customRequestHeaders:
      Authorization: "Basic YXBpLWNsaWVudDpzZWN1cmUtcGFzc3dvcmQ="

API Key Pattern​

API Key authentication supports both header-based and query parameter-based implementations. The choice depends on how your backend API expects to receive the API key.

Header-Based API Key​

Header-based API keys are transmitted through HTTP headers, typically using headers like X-API-Key, X-API-Token, or custom header names specified by the backend API.

API Key in X-API-Key header
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: upstream-api-key-header
  namespace: apps
spec:
  headers:
    customRequestHeaders:
      X-API-Key: "your-static-api-key-here"

Query Parameter-Based API Key​

Query parameter-based API keys are appended to the request URL as query parameters. The Query Parameter middleware handles this pattern by injecting static API keys into the request URL.

Inject API key as query parameter
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: upstream-api-key-param
  namespace: apps
spec:
  plugin:
    queryParam:
      set:
        - name: api_key
          value: "your-static-api-key-here"

Securing API Keys​

For production deployments, avoid hardcoded API keys. Here are some secure options available:

Query Parameter middleware supports URN syntax
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: upstream-api-keys
  namespace: apps
stringData:
  primary-api-key: "sk_live_abc123def456ghi789"
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: upstream-api-key-param-secure
  namespace: apps
spec:
  plugin:
    queryParam:
      set:
        - name: api_key
          value: "urn:k8s:secret:upstream-api-keys:primary-api-key"

OAuth Client Credentials Pattern​

OAuth Client Credentials flow provides token-based authentication for service-to-service communication. The OAuth 2.0 Client Credentials middleware automatically handles token acquisition, caching, and refresh cycles.

This pattern is ideal for backend APIs that require OAuth 2.0 access tokens and eliminates the complexity of manual token management.

Basic Configuration​

OAuth Client Credentials upstream authentication
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: upstream-oauth
  namespace: apps
spec:
  plugin:
    oAuthClientCredentials:
      url: https://auth.example.com/oauth/token
      clientID: urn:k8s:secret:oauth-credentials:clientID
      clientSecret: urn:k8s:secret:oauth-credentials:clientSecret
      audience: https://api.example.com

Advanced OAuth Configuration​

The OAuth middleware supports advanced features like token caching, custom claims validation, and header forwarding:

OAuth with caching and claims validation
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: upstream-oauth-advanced
  namespace: apps
spec:
  plugin:
    oAuthClientCredentials:
      url: https://auth.example.com/oauth/token
      clientID: urn:k8s:secret:oauth-credentials:clientID
      clientSecret: urn:k8s:secret:oauth-credentials:clientSecret
      audience: https://api.example.com
      claims: Equals(`scope`, `read:data`)
      forwardHeaders:
        X-Token-Subject: sub
        X-Token-Scope: scope
        X-Token-Expires: exp
      store:
        redis:
          endpoints: redis.traefik-hub.svc.cluster.local:6379

OAuth Token Lifecycle​

The OAuth middleware handles the complete token lifecycle:

  1. Initial Token Request: Acquires access token using client credentials
  2. Token Caching: Stores valid tokens in Redis to reduce authorization server load
  3. Automatic Refresh: Requests new tokens before expiration
  4. Error Handling: Retries unsuccessful requests and handles authorization server errors

Combining Authentication Patterns​

Complex scenarios may require multiple authentication mechanisms. Use middleware chaining to combine different upstream authentication patterns:

Combine OAuth and custom headers
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: multi-auth-chain
  namespace: apps
spec:
  chain:
    middlewares:
      - name: upstream-oauth
      - name: upstream-custom-headers

Middleware chaining allows you to tailor upstream authentication to match each backend's specific requirements. The most common pattern combines OAuth token forwarding with custom headers, enabling you to send both a bearer token and additional metadata like service identifiers or request context.

Legacy systems sometimes require multiple authentication methods simultaneously. You can chain an OAuth middleware with an API key middleware to satisfy backends that expect both a bearer token and a static API key. While less common in modern architectures, this approach ensures compatibility with existing upstream services during migration.

Troubleshooting​

When upstream authentication fails, Traefik Hub returns standardized HTTP error responses to clients while logging detailed diagnostic information. Understanding these error patterns helps identify and resolve configuration issues.

Real-World OAuth Error Scenario​

This example demonstrates a complete OAuth upstream authentication error using GitHub's OAuth endpoint with intentionally wrong credentials, showing exactly what clients and administrators see.

Test Request and Client Response​

# OAuth middleware configured with wrong credentials against GitHub's OAuth endpoint
curl -H "Host: whoami-oauth-test.localhost" http://localhost/ -v

# Client receives:
* Connected to localhost (::1) port 80
> GET / HTTP/1.1
> Host: whoami-oauth-test.localhost
> User-Agent: curl/8.7.1
> Accept: */*
>
< HTTP/1.1 401 Unauthorized
< Content-Type: text/plain; charset=utf-8
< X-Content-Type-Options: nosniff
< Date: Tue, 12 Aug 2025 10:03:07 GMT
< Content-Length: 13
<
Unauthorized

Key observations:

  • Client receives generic 401 Unauthorized with minimal information
  • No indication of the specific authentication error
  • Response includes security headers (X-Content-Type-Options)

Gateway Logs Analysis​

Traefik Hub logs reveal the complete error chain, the ID of the cluster, the name of the middleware and the type of the middleware:

DBG Unable to get token error="unauthorized: oauth2: cannot fetch token: 401 UNAUTHORIZED Response: "
    cluster_id=aebfc601-e306-4cfa-9f76-f5535b0fe16a
    middlewareName=traefik-upstream-oauth-github-wrong@kubernetescrd
    middlewareType=oAuthClientCredentials

Critical details in logs:

  • Middleware identification: upstream-oauth-github-wrong@kubernetescrd helps locate the failing configuration
  • Error type: oauth2: cannot fetch token: 401 UNAUTHORIZED indicates credential rejection
  • No retries: OAuth server responds immediately with 401, no retry attempts occur
  • Cluster context: cluster_id helps correlate logs in multi-cluster environments

Access Log Analysis​

Traefik Hub access logs reveal the complete request flow and confirm the error occurred in middleware processing:

{
  "ClientAddr":"10.42.0.1:55438",
  "DownstreamStatus":401,
  "Duration":522039148,
  "OriginContentSize":0,
  "OriginDuration":0,
  "OriginStatus":0,
  "Overhead":522039148,
  "RequestHost":"whoami-oauth-test.localhost",
  "RequestMethod":"GET",
  "RequestPath":"/",
  "RouterName":"traefik-whoami-oauth-upstream-test-3685623e73b09ae3ac3f@kubernetescrd"
}

Key access log indicators:

  • DownstreamStatus: 401: Client receives 401 Unauthorized response
  • OriginStatus: 0: Request never reached the backend service
  • OriginDuration: 0: Zero time spent communicating with backend
  • Duration: 522039148: Total request time (522ms)
  • Overhead: 522039148: All processing time consumed by middleware (no backend processing)

Common Error Patterns​

DNS Resolution Errors​

  • Client sees: 401 Unauthorized
  • Logs show: Multiple retry attempts with exponential backoff (1s, 2s, 4s intervals)
  • Key indicators: "no such host" errors, 4 retry attempts before giving up

Wrong Credentials​

  • Client sees: 401 Unauthorized (immediate response)
  • Logs show: "401 UNAUTHORIZED Response" from OAuth server
  • Key indicators: No retry attempts, immediate error.

Missing Kubernetes Secrets​

  • Client sees: 404 Not Found (route fails to register)
  • Logs show: "secret not found" during middleware loading
  • Key indicators: Route configuration errors, middleware creation errors.

Debugging​

  1. Check client response: 401 suggests authentication issues, 404 suggests configuration problems, 500 suggests middleware errors.

  2. Examine gateway logs: Filter for your middleware name and look for error patterns:

    kubectl logs -n traefik deployment/traefik | grep "middlewareName=your-middleware-name"

  3. Verify secret references: Ensure Kubernetes Secrets exist and contain expected keys:

    kubectl get secret your-secret-name -o yaml
    kubectl describe secret your-secret-name

  4. Test OAuth endpoints manually: Validate OAuth server connectivity and credentials:

    curl -X POST https://auth.example.com/oauth/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials&client_id=test&client_secret=test"

  5. Enable access and debug logging to track request patterns and response codes:

    logs:
      general:
        level: DEBUG
      access:
        enabled: true
        format: json

Successful upstream authentication shows the injected headers in backend logs, while failures show missing authentication context.

Conclusion​

This guide provides the foundation for implementing upstream authentication patterns with Traefik Hub. Each pattern can be adapted to specific backend API requirements while maintaining security best practices and operational simplicity.