APIAuth

Configure API authentication with the APIAuth Custom Resource Definition (CRD).

---

Introduction

The APIAuth resource provides a declarative way to configure authentication for your APIs in Traefik Hub API Management. This resource works in both online and offline environments, allowing you to manage API authentication settings through Kubernetes manifests.

APIAuth enables per-namespace authentication overrides, allowing you to run different authentication methods on the same gateway by placing APIs in different namespaces. Previously, this required separate Hub workspaces and separate gateways. Now your workspace settings act as a "global default" that you can override on a per-namespace basis with CRDs.

When defined, the CRD configuration takes precedence over workspace-level dashboard settings.

APIAuth works seamlessly in both online and offline modes.

In online environments, it integrates fully with self-service & managed applications, allowing users to create API keys through the Developer Portal while respecting the authentication method defined in the APIAuth resource.

In offline environments where connectivity to the Traefik Hub Online Dashboard is restricted, APIAuth allows you to maintain full control over API authentication while operating in air-gapped environments.

Example Use Case: You can now have APIs in the payments namespace using JWT authentication, APIs in the public namespace using API Key authentication, and APIs in the internal namespace using your workspace default authentication method - all on the same gateway!

The APIAuth resource supports two authentication methods:

• API Key Authentication: Key-based authentication
• JWT Authentication: Token-based authentication using JSON Web Tokens

Namespace Scope and Default Behavior

The APIAuth CRD is namespace-scoped, meaning it applies to all APIs within the same namespace. This design follows the principle of least privilege while providing convenient management for APIs grouped by namespace.

isDefault Behavior

APIAuth resources are only recognized when isDefault is set to true. Resources with isDefault: false or without this property will be ignored by the system. When isDefault: true is configured, the authentication method applies to all APIs within the same namespace. If multiple APIAuth resources exist in a namespace with isDefault: true, the system will use the first one when sorted alphabetically by name.

Configuration Example

Basic Structure

API Key

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: auth-config
  namespace: apps
spec:
  isDefault: true
  apiKey: {} # API Key authentication

JWT

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: auth-config
  namespace: default
spec:
  isDefault: true
  jwt: {} # JWT authentication

Configuration Options

Field	Description	Required	Default
isDefault	Specifies if this APIAuth should be the default authentication method for the namespace.	Yes	-
Authentication Method	Either apiKey or jwt (exactly one must be specified).	Yes	-

API Key Authentication

API Key authentication provides an authentication method using pre-shared keys. In online environments, users can create self-service applications and generate API keys through the Developer Portal. In offline or declarative scenarios, API keys are managed by ManagedApplication resources.

Configuration Example

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: apikey-auth
  namespace: production
spec:
  isDefault: true
  apiKey: {}

The apiKey configuration requires no additional properties. Authentication is handled through API keys created either via self-service applications in the Developer Portal or through ManagedApplication resources.

JWT Authentication

JWT authentication validates JSON Web Tokens using various verification methods.

Configuration Example

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: jwt-auth
  namespace: production
spec:
  isDefault: true
  jwt:
    appIdClaim: azp
    jwksUrl: https://auth.example.com/.well-known/jwks.json

Configuration Options

Field	Description	Required	Default
jwt.appIdClaim	Name of the JWT claim containing the application identifier	Yes	-
jwt.jwksUrl	URL to fetch JWKS for JWT verification.	No	-
jwt.jwksFile	JWKS file content for JWT verification.	No	-
jwt.publicKey	PEM-encoded public key for JWT verification.	No	-
jwt.signingSecretName	Name of Kubernetes Secret containing signing secret. The secret must be of type Opaque and contain a key named value.	No	-
jwt.stripAuthorizationHeader	Whether to strip Authorization header before forwarding.	No	false
jwt.tokenQueryKey	Query parameter name for JWT token. If not set, only the Authorization header is used.	No	-
jwt.forwardHeaders	Additional headers to forward with the request.	No	-
jwt.tokenNameClaim	JWT claim for token name (used in metrics).	No	-

Note

One of jwksUrl, jwksFile, publicKey, or signingSecretName must be specified.

JWT Verification Methods

Choose the appropriate JWT verification method based on your authentication provider:

JWKS URL

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: jwks-auth
  namespace: default
spec:
  isDefault: true
  jwt:
    appIdClaim: azp
    jwksUrl: https://auth.example.com/.well-known/jwks.json

Use this method when your JWT issuer provides a JWKS endpoint. Most OAuth2 providers support this.

JWKS File

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: jwks-file-auth
  namespace: default
spec:
  isDefault: true
  jwt:
    appIdClaim: client_id
    jwksFile: |
      {
        "keys": [
          {
            "kty": "RSA",
            "kid": "example-key-id",
            "use": "sig",
            "n": "...",
            "e": "AQAB"
          }
        ]
      }

Use this method for static JWKS configuration when you have the key set available.

Public Key

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: pubkey-auth
  namespace: default
spec:
  isDefault: true
  jwt:
    appIdClaim: sub
    publicKey: |
      -----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
      -----END PUBLIC KEY-----

Use this method when you have a static public key for verification.

Signing Secret

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: secret-auth
  namespace: default
spec:
  isDefault: true
  jwt:
    appIdClaim: aud
    signingSecretName: jwt-signing-secret

---
apiVersion: v1
kind: Secret
metadata:
  name: jwt-signing-secret
  namespace: default
type: Opaque
data:
  value: <base64-encoded-secret>

Use this method for symmetric key verification with secrets stored in Kubernetes.

OAuth2 Provider Integration

Below is an example of how to configure APIAuth for Auth0 :

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: auth0-integration
  namespace: api-services
spec:
  isDefault: true
  jwt:
    appIdClaim: azp
    jwksUrl: https://your-domain.auth0.com/.well-known/jwks.json
    forwardHeaders:
      X-User-ID: sub
      X-User-Email: email

Migration from Dashboard Configuration

When migrating from online dashboard authentication to APIAuth CRDs:

1. Identify Current Settings: Note your authentication configuration from the online dashboard
2. Create APIAuth Resource: Convert dashboard settings to APIAuth CRD format
3. Deploy and Validate: Use the Traefik Hub static analyzer to ensure correct configuration
4. Test Authentication: Verify that APIs continue to authenticate properly

Migration Example

Dashboard JWT configuration with Auth0:

• JWKS URL: https://auth.company.com/.well-known/jwks.json
• App ID Claim: azp
• Forward email as header: X-User-Email

Equivalent APIAuth CRD with Auth0:

apiVersion: hub.traefik.io/v1alpha1
kind: APIAuth
metadata:
  name: migrated-auth
  namespace: default
spec:
  isDefault: true
  jwt:
    appIdClaim: cid
    jwksUrl: https://your-domain.auth0.com/.well-known/jwks.json
    forwardHeaders:
      X-User-Email: email

Troubleshooting

• APIs not authenticating: Ensure APIAuth resource exists in the same namespace as your APIs with isDefault: true.
• Multiple authentication methods: Verify only one authentication method (apiKey or jwt) is specified in the APIAuth resource.
• JWT verification failing: Check that your JWKS URL is accessible and contains the correct public keys.
• Missing application identifier: Ensure the appIdClaim matches the claim name in your JWT tokens.

Related Content

• Learn more about the APIPortalAuth in its dedicated section.
• Learn more about ManagedApplication in its dedicated section.
• Learn more about the API object in its dedicated section.
• Learn more about Offline Mode in its dedicated section.