feat(dir/dirctl/helm): add Envoy external authorization with multi-provider authentication

[tkircsi]

Implements a production-ready Envoy ExtAuthz solution for authenticating dirctl users via GitHub OAuth2 while maintaining SPIFFE mTLS for service-to-service communication.

New Components

Authentication Provider Framework

• Add generic provider interface in auth/authprovider/
• Implement GitHub OAuth2 provider using github.com/google/go-github/v50
• Support for token validation, caching (5min TTL), and org membership checks
• Extensible design for future providers

Envoy ExtAuthz Service

• Add auth/authzserver/ implementing Envoy ext_authz gRPC API (v3)
• Provider auto-detection from token format (GitHub only for now)
• Support for allowlists, denylists, and org membership requirements
• Add auth/cmd/envoy-authz/ main service with environment-based configuration

dirctl CLI Enhancements

• Add dirctl auth login - GitHub OAuth (Device Flow default, Web Flow with --web)
• Add dirctl auth status - Show authentication status and validate token
• Add dirctl auth logout - Clear cached credentials
• Update client library with OAuth flows and token caching at ~/.config/dirctl/
• CI/CD support via --auth-token flag or DIRECTORY_CLIENT_TOKEN env var

Deployment & Infrastructure

• Add Helm chart install/charts/envoy-authz/
• Integrate as optional subchart in dir Helm chart (disabled by default)
• Add Dockerfile for multi-arch builds (amd64/arm64) with distroless base
• Add Docker Compose setup for local testing with mock backend
• Update docker-bake.hcl for image builds
• Update GitHub workflows for automated releases

Key Features

• GitHub OAuth2 only: Device Flow (default, uses GitHub CLI client ID) and Web Flow
• PAT support: Available via env var/flag for CI/CD (DIRECTORY_CLIENT_TOKEN)
• Optional deployment: Disabled by default, opt-in via Helm values

Module Structure

New independent modules in auth/ directory:

• auth/authprovider/ - Provider interface and GitHub implementation
• auth/authzserver/ - ExtAuthz gRPC server
• auth/cmd/envoy-authz/ - Main service with Dockerfile

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / verify-proto (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	⏩ skipped	✅ passed	Jan 21, 2026, 1:52 PM

[tkircsi]

Test mock server for local development only. Intentionally logs HTTP headers and user input to verify Envoy ext_authz integration. Never deployed to production. Security disclaimer added to package documentation. No actual credentials logged. Dismiss alert for cmd/envoy-authz/test/mock-directory.go file only

[codecov]

Codecov Report

❌ Patch coverage is 11.88119% with 445 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
client/oauth.go	0.0%	146 Missing ⚠️
cli/cmd/auth/login.go	8.2%	101 Missing ⚠️
cli/cmd/auth/token.go	5.4%	69 Missing and 1 partial ⚠️
cli/cmd/auth/status.go	4.3%	44 Missing ⚠️
client/token_cache.go	37.3%	31 Missing and 1 partial ⚠️
client/options.go	23.1%	27 Missing and 3 partials ⚠️
cli/cmd/auth/logout.go	0.0%	10 Missing ⚠️
client/github.go	0.0%	9 Missing ⚠️
cli/cmd/auth/auth.go	70.0%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[ramizpolic]

@tkircsi did you manage to find any existing implementations for ext_authz service that works with OAuth2? AFAIR we discussed that we can drop the org/gh implementation for a generic one and configure the authz rules outside of the service itself but through configs

[tkircsi]

@ramizpolic I investigated whether we could replace our custom auth/ package with existing ext_authz implementations, but what I've found is production-grade ext_authz services require OIDC, not pure OAuth2. Do you have any suggestions?
GitHub only provides OAuth2 (opaque tokens), not OIDC. So, we would introduce an OIDC provider besides Envoy in our solution. This can be useful for future, but I don't think in v1.

[paralta]

a couple of comments on the cli changes, will continue with the other parts

[paralta]

client code looks good overall 👍

However, the OAuth code (oauth_web.go, oauth_device.go, token_cache.go) talks to GitHub, not the Directory server, so I think it does not really belong in the Dir client module. I would suggest moving to auth/client.

[paralta]

Regarding the auth changes, the three modules under this folder (authprovider, authzserver, cmd/envoy-authz) are tightly coupled. I think it would be simpler to have a single module with subpackages, WDYT?

[tkircsi]

That's a good idea, and I agree. But let's wait for the OIDC provider PoC, because with the OIDC provider (Zitadel(or other) + Envoy) solution, the entire auth package can be deleted.