Idea: unified multi-token auth model for oidc-gateway

[tkircsi]

We are considering extending oidc-gateway from an OIDC-only Envoy jwt_authn + ext_authz gateway into a unified authentication gateway that can authorize requests using three credential types:

• OIDC bearer tokens
• SPIFFE JWT-SVID bearer tokens
• SPIFFE X.509-SVID client certificates

Why

The goal is to move authorization decisions out of downstream services and into oidc-gateway, while still supporting both human/user auth and workload identities.

In our case, the backend should receive a normalized identity contract regardless of how the caller authenticated.

Proposed auth precedence

For non-public paths:

1. If a valid SPIFFE X.509-SVID is present, use it.
2. If X.509-SVID is present, ignore any bearer token on the request.
3. If no X.509 identity is present, try bearer auth.
4. Bearer auth may succeed via either:
   • OIDC JWT
   • SPIFFE JWT-SVID
5. Otherwise deny.

For public paths:

• allow without credentials

Proposed backend contract

Instead of forwarding mechanism-specific headers, forward a single canonical header to the backend:

• x-auth-principal

The value format would be:

• <auth-family>:<canonical-principal>

Examples:

• spiffe:spiffe://example.org/ns/default/sa/backend
• oidc:dex:alice
• oidc:dex:sync-service
• oidc:github:repo:org/repo:workflow:deploy.yml:ref:refs/heads/main

This avoids sending redundant or auth-mechanism-specific headers like x-jwt-principal, x-user-id, x-auth-type, etc.

Proposed principal normalization

Canonical principal grammar:

• SPIFFE X.509-SVID: spiffe:<spiffe-id>
• SPIFFE JWT-SVID: spiffe:<spiffe-id>
• OIDC principal: oidc:<providerKey>:<principal>

Examples:

• spiffe:spiffe://example.org/ns/default/sa/backend
• oidc:dex:alice
• oidc:dex:sync-service
• oidc:github:repo:org/repo:workflow:deploy.yml:ref:refs/heads/main

For OIDC issuers, add an explicit stable providerKey to configuration and use that key, not the raw issuer URL, in canonical principals and authz rules. For example:

issuers:
  - providerKey: dex
    provider: https://dex.example.com
  - providerKey: github
    provider: https://token.actions.githubusercontent.com

This keeps principal strings and policy patterns readable and stable:

• oidc:dex:*
• oidc:github:*

Shared identity package

We are also considering adding a lightweight standalone package in this repo:

• package path: github.com/agntcy/oidc-gateway/identity
• package name: identity

This package would be intentionally dependency-light and reusable by authzserver, dir, or other consumers, but it would not import Envoy, Casbin, or gateway-specific logic.

A possible initial API shape:

type AuthFamily string

const (
    AuthFamilyOIDC   AuthFamily = "oidc"
    AuthFamilySPIFFE AuthFamily = "spiffe"
)

type IdentityPrincipal string

type Identity struct {
    AuthFamily AuthFamily
    Principal  string
}

func ParsePrincipal(p IdentityPrincipal) (Identity, error)
func (i Identity) PrincipalString() IdentityPrincipal
func (i Identity) Validate() error

Envoy / ext-authz shape

Conceptually this would mean:

• downstream TLS / mTLS establishes X.509-SVID identity first when present
• jwt_authn handles OIDC and JWT-SVID bearer validation as fallback
• ext_authz performs authorization over a normalized principal model
• upstream/backends trust only the normalized x-auth-principal header from the gateway

Authorization rules

We are also considering a rule model shaped roughly like:

auth:
  - routes:
      - "/agntcy.dir.store.v1.StoreService/Pull"
      - "/agntcy.dir.store.v1.StoreService/Lookup"
    principals:
      - "spiffe:*"
      - "oidc:dex:*"
      - "oidc:github:*"
      - "oidc:dex:ramizpolic"

That suggests subject matching should operate on canonical principal strings rather than a JWT-specific role mapping model.

Open design question

Would maintainers prefer this to be modeled as:

1. separate listeners / routes for mTLS and bearer auth, or
2. one listener where X.509 identity takes precedence and bearer auth is fallback?

Interested in feedback on:

• whether this fits the intended scope of oidc-gateway
• the precedence rule (X.509-SVID wins and bearer is ignored)
• the proposed single-header backend contract
• the explicit canonical principal grammar
• the idea of a lightweight identity package in this repo
• whether SPIFFE JWT-SVID support should live directly in Envoy config, ext_authz, or both