feat(pkg/cmd): add provider interface and Envoy AuthZ server

[tkircsi]

Implement Envoy External Authorization Server for GitHub Token Validation

New Components

Authentication Provider Framework

• Add generic provider interface in pkg/authprovider/
• Implement GitHub provider using github.com/google/go-github/v50
• Support for caching, token validation, and org membership checks
• Extensible design for future Google/Azure providers

Envoy ExtAuthz Service

• Add pkg/authzserver/ implementing Envoy ext_authz gRPC API
• Provider auto-detection from token format
• Support for allowlists, denylists, and org restrictions
• Add cmd/envoy-authz/ main service with configuration via env vars

[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 14, 2026, 3:09 PM

[paralta]

@tkircsi Just some quick notes on the overall structure after a quick review.

Regarding the cmd changes covering the authentication part, I think a more generic name like cmd/auth would be more appropriate. Installation files like Dockerfile and docker-compose.yml should probably be moved to the installation folder or maybe closer to the authorization server implementation (like we have the Dockerfile for the dir server inside the server folder). Additionally, the new pkg/ folder doesn't align with the existing project structure (maybe something like an auth module at root would be more appropriate?).

Before implementing a custom solution, investigate existing open-source tools that provide Envoy external authorization with GitHub OAuth support (oauth2-proxy, envoy OAuth2 filter).

On the authorization part, it would be good to add some notes on this topic in agntcy/dir-staging#19. Before adding a new server for authorization did you check any alternatives or considered what we discussed about moving authorization logic down to the existing directory server?

[tkircsi]

@tkircsi Just some quick notes on the overall structure after a quick review.

@paralta Thank You very much for the review!

Regarding the cmd changes covering the authentication part, I think a more generic name like cmd/auth would be more appropriate.

I kept cmd/envoy-authz to be explicit that this service implements the Envoy ext_authz gRPC API. If we add other auth services in the future, we can structure them separately (e.g., cmd/oauth-proxy).

Installation files like Dockerfile and docker-compose.yml should probably be moved to the installation folder...

I structured it the same way as the Directory server:

• cmd/envoy-authz/Dockerfile is next to cmd/envoy-authz/main.go
• server/Dockerfile is next to the server code

May I misunderstand something?

The docker-compose.yml is for local testing/development (similar to the test setup in cmd/envoy-authz/test/).

Additionally, the new pkg/ folder doesn't align with the existing project structure (maybe something like an auth module at root would be more appropriate?).

These are reusable libraries, not standalone services, but You're right. It doesn't align with the existing project structure.I'll restructure to match the project convention.

Before implementing a custom solution, investigate existing open-source tools that provide Envoy external authorization with GitHub OAuth support (oauth2-proxy, envoy OAuth2 filter).

I evaluated both alternatives before implementing the custom ext_authz server:

oauth2-proxy

• oauth2-proxy does not authenticate users with a GitHub Personal Access Token (PAT), and it’s not designed to work “headless”
• No PAT validation - Forces browser OAuth redirects, which breaks CLI workflows (dirctl auth token, dirctl push)
• Limited org authorization - GitHub org checking via --github-org, but no support for Azure tenants or Google domains
• No multi-provider token detection - Cannot auto-detect provider from token format
• External service - Adds another hop (Envoy → oauth2-proxy → Directory)

Envoy OAuth2 Filter

• Browser-only - Cannot validate pre-existing PATs, requires OAuth redirect flow
• No org membership checking - Only validates tokens, no authorization rules
• Single provider - Would need multiple filter chains for GitHub/Google/Azure
• Limited identity headers - Doesn't inject org membership or detailed user info

On the authorization part, it would be good to add some notes on this topic in agntcy/dir-staging#19.

Will do. I'll add a comment summarizing the implementation approach and why we chose a custom ext_authz server.

Before adding a new server for authorization did you check any alternatives or considered what we discussed about moving authorization logic down to the existing directory server?

That's still a little up in the air. Directory has an authz service, but only for workloads and using SPIFFE. I'm not sure we could mix workload and human authz. From Direcotry point of view every human identity is the Envoy(SPIFFEID). We could pass the user, org and other information to the dir via headers, but we would need to build a new authorization system inside the dir besides the SPIFFE one.

However, I'm open to discussion if you think embedding it in Directory is better. What are your concerns with the separate service approach? Otherwise my spike "Validate Identity Bridge Pattern for GitHub Authentication" agntcy/dir-staging#21 was about embedding the authz logic in the Directory based on the Identity Bridge pattern using the SPIFFE ID.

[paralta]

I kept cmd/envoy-authz to be explicit that this service implements the Envoy ext_authz gRPC API. If we add other auth services in the future, we can structure them separately (e.g., cmd/oauth-proxy).

Agree with being explicit but I still question if these new folders cmd and pkg fit our current project structure.

What are your concerns with the separate service approach?

No concerns at all, just interested to hear if you explored other options. I think the only drawback with the new server is the extra component that will need to be built/deployed.

[tkircsi]

Agree with being explicit but I still question if these new folders cmd and pkg fit our current project structure.

Unfortunately, not. Need to find out how to organize them. This whole OAuth component is an add-on to Dir in my mind. It is totally independent from Dir and user can opt-in if he/she wants. TBH I'd put this whole into a separate repo, but for v1.0.0 it was the easiest way. pkg contains the reusable modules and cmd the concrete implementation. Maybe I can move them into dir/auth/cmd, dir/auth/authprovider and dir/auth/authzserver.

No concerns at all, just interested to hear if you explored other options. I think the only drawback with the new server is the extra component that will need to be built/deployed.

As I mentioned, I think this component as an add-on. This is not a main function of Directory, it is only an independent authorization layer.

[tkircsi]

Solved with this PR #807