Proposal: Add CRD-based AuthChain

[JefeDavis]

Problem

authservice currently depends on a statically defined JSON configuration for defining FilterChain entries. These chains are strictly ordered, and each defines how incoming requests are matched and filtered. This design creates friction for platform operators and application teams:

• Adding new applications requires central configuration updates and service restarts.
• GitOps workflows are inhibited, since dynamic configuration via Kubernetes-native mechanisms is unsupported.
• There is no way to define chains modularly and independently.

Motivation

A Kubernetes-native AuthChain Custom Resource would enable:

• Decentralized, declarative configuration of authservice chains.
• GitOps-friendly workflows for dynamically onboarding applications.
• Consistent lifecycle, validation, and scoping of OIDC and routing behavior.
• Dynamic, priority-aware request routing within the authservice.

Proposed Solution

1. Introduce a new namespaced AuthChain CRD

• Group: authservice.istio.io
• Version: v1alpha1
• Kind: AuthChain
• Scope: Namespaced

Each AuthChain defines:

• A priority to determine evaluation order.
• A match rule (using header, prefix, or equality) to decide whether the chain should process a given request.
• A list of one or more filters, aligned 1:1 with the FilterChain proto.

Example AuthChain Resource

apiVersion: authservice.istio.io/v1alpha1
kind: AuthChain
metadata:
  name: my-app-auth
  namespace: my-app
spec:
  priority: 100
  match:
    header: ":path"
    prefix: my-app.example.com
  filters:
    - oidc:
        configurationURI: https://auth.example.com
        authorizationURI: https://auth.example.com/auth
        tokenURI: https://auth.example.com/token
        callbackURI: https://my-app.example.com/callback
        clientID: my-app-client
        clientSecretRef:
          name: my-app-secret
          namespace: my-app
        scopes: [openid, email]
        cookieNamePrefix: myapp
        idToken:
          header: Authorization
          preamble: Bearer
        accessToken:
          header: X-Access-Token
        logout:
          path: /logout
          redirectURI: https://my-app.example.com
        absoluteSessionTimeout: 3600
        idleSessionTimeout: 600
        redisSessionStoreConfig:
          serverURI: tcp://redis.default.svc.cluster.local:6379
        trustedCertificateAuthority: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
        proxyURI: http://proxy.example.com:8080

2. Dynamic Discovery in AuthService

• AuthService would watch all AuthChain resources cluster-wide.
• It would build a prioritized, sorted in-memory list of chains.
• Matching is performed using match.header (e.g., ":path") with optional prefix or equality.
• Filters are applied in order, using the same logic as the current JSON configuration.

3. Ordering Support

• spec.priority controls evaluation order (lower values are evaluated first).
• Ties are broken lexicographically by metadata.name.

4. Compatibility and Migration

• The existing static JSON configuration remains supported.
• CRD-based chains are additive and opt-in. (chains would be appended to json based chains)
• Full alignment with the existing protobuf types is preserved.

Benefits

• Declarative, namespaced configuration
• Clean separation between applications and platform
• GitOps compatibility
• One-to-one mapping with existing chains config schema
• Enables modular, scalable onboarding of applications using OIDC

Next Steps

If this proposal is accepted, the following should be created:

• AuthChain CRD definition with OpenAPI validation
• Controller that watches AuthChain resources and updates the filter chain runtime
• Documentation, example manifests, and tests

[nacx]

Thanks for filing such a detailed proposal!

I agree this would be really nice to have. I'd only add one small thing: we'll also need to add a validation webhook to reject invalid configurations, the rest looks good to me.

Would you be willing to contribute this?