Skip to content

agentgateway: http ext authz api #13044

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
howardjohn wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

agentgateway: http ext authz api #13044

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 65 additions & 1 deletion api/v1alpha1/agentgateway/agentgateway_policy_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -948,22 +948,86 @@ type AgentExtProcPolicy struct {
BackendRef gwv1.BackendObjectReference `json:"backendRef"`
}

// +kubebuilder:validation:ExactlyOneOf=grpc;http
type AgentExtAuthPolicy struct {
// backendRef references the External Authorization server to reach.
//
// Supported types: Service and Backend.
// +required
BackendRef gwv1.BackendObjectReference `json:"backendRef"`

// grpc specifies that the gRPC External Authorization
// [protocol](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto) should be used.
// +optional
GRPC *AgentExtAuthGRPC `json:"grpc,omitempty"`

// http specifies that the HTTP protocol should be used for connecting to the authorization server.
// The authorization server must return a `200` status code, otherwise the request is considered and authorization failure.
// +optional
HTTP *AgentExtAuthHTTP `json:"http,omitempty"`

// forwardBody configures whether to include the HTTP body in the request. If enabled, the request body will be
// buffered.
// +optional
ForwardBody *AgentExtAuthBody `json:"forwardBody,omitempty"`
}

type AgentExtAuthHTTP struct {
// path specifies the path to send to the authorization server. If unset, this defaults to the original request path.
// This is a CEL expression, which allows customizing the path based on the incoming request.
// For example, to add a prefix: `path: '"/prefix/" + request.path'`.
// +optional
Path *shared.CELExpression `json:"path,omitempty"`

// contextExtensions specifies additional arbitrary key-value pairs to send to the authorization server.
// redirect defines an optional expression to determine a path to redirect to on authorization failure.
// This is useful to redirect to a sign-in page.
// +optional
Redirect *shared.CELExpression `json:"redirect,omitempty"`

// allowedRequestHeaders specifies what additional headers from the client request
// will be sent to the authorization server.
//
// If unset, the following headers are sent by default: `Authorization`.
//
// +optional
// +kubebuilder:validation:MaxItems=64
AllowedRequestHeaders []ShortString `json:"allowedRequestHeaders,omitempty"`
Copy link
Contributor

@lgadban lgadban Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

on the envoy side this was a shared type between gRPC and HTTP, is it useful to do the same here?
i.e. should we move this out of the HTTP-specific type?

Copy link
Contributor Author

@howardjohn howardjohn Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kind of like it split since the docs are differnt for each (one defaults to all, the other does not) but I am fine either way.
tbh I don't get why anyone would not send all for gRPC but 🤷

Copy link
Contributor

@lgadban lgadban Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can buy the split for the different defaults (it was very hard to accurately portray that in the shared envoy type!) but just to make sure I'm not missing something, I don't see this current in the gRPC extauth type yet, correct?

And separately, given:

I kind of like it split since the docs are differnt for each (one defaults to all, the other does not) but I am fine either way.

I'm assuming this is to maintain the weird behavior envoy currently to e.g. enable compatibility with existing extauth servers?


// addRequestHeaders specifies what additional headers to add to the request to the authorization server.
// While allowedRequestHeaders just passes the original headers through, addRequestHeaders allows defining custom headers
// based on CEL Expressions.
//
// +optional
// +kubebuilder:validation:MaxProperties=64
AddRequestHeaders map[string]shared.CELExpression `json:"addRequestHeaders,omitempty"`

// allowedResponseHeaders specifies what headers from the authorization response
// will be copied into the request to the backend.
//
// +optional
// +kubebuilder:validation:MaxItems=64
AllowedResponseHeaders []ShortString `json:"allowedResponseHeaders,omitempty"`

// metadata specifies what metadata fields should be constructed from the authorization response. These will be
// included under the `extauthz` variable in future CEL expressions. Setting this is useful to do things like logging
// usernames, without needing to include them as headers to the backend (as `allowedResponseHeaders` would).
//
// +optional
// +kubebuilder:validation:MaxProperties=64
Metadata map[string]shared.CELExpression `json:"metadata,omitempty"`
Copy link
Contributor

@lgadban lgadban Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since this is a duplicated type between HTTP and gRPC is it worth moving up a level?

Copy link
Contributor Author

@howardjohn howardjohn Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its duplicated type but has entirely different behavior. One is the metadata to populate in the grpc request, and the grpc server returns the response metadata. In http, there is no metadata to send in the request or response, and this field instead sets response metadata based on the HTTP response.

Perhaps more explicit naming would help

Copy link
Contributor

@lgadban lgadban Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I wasn't paying close enough attention as was tricked by the similar naming.

Is there a more specific term for the agentgateway metadata?

Copy link
Contributor

@lgadban lgadban Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's long but maybe metadataFromResponse or something like that?

}

type AgentExtAuthGRPC struct {
// contextExtensions specifies additional arbitrary key-value pairs to send to the authorization server in the `context_extensions` field.
// +kubebuilder:validation:MaxProperties=64
// +optional
ContextExtensions map[string]string `json:"contextExtensions,omitempty"`
// metadata specifies metadata to be sent to the authorization server.
// This maps to the `metadata_context.filter_metadata` field of the request, and allows dynamic CEL expressions.
// If unset, by default the `envoy.filters.http.jwt_authn` key is set if the JWT policy is used as well, for compatibility.
// +kubebuilder:validation:MaxProperties=64
// +optional
Metadata map[string]shared.CELExpression `json:"metadata,omitempty"`
Copy link
Contributor

@lgadban lgadban Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe forwardMetadata ?

}

type AgentExtAuthBody struct {
Expand Down
95 changes: 88 additions & 7 deletions api/v1alpha1/agentgateway/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

107 changes: 100 additions & 7 deletions install/helm/kgateway-crds/templates/agentgateway.dev_agentgatewaypolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2489,13 +2489,6 @@ spec:
- message: Must have port for Service reference
rule: '(size(self.group) == 0 && self.kind == ''Service'')
? has(self.port) : true'
contextExtensions:
additionalProperties:
type: string
description: contextExtensions specifies additional arbitrary
key-value pairs to send to the authorization server.
maxProperties: 64
type: object
forwardBody:
description: |-
forwardBody configures whether to include the HTTP body in the request. If enabled, the request body will be
Expand All @@ -2511,9 +2504,109 @@ spec:
required:
- maxSize
type: object
grpc:
description: |-
grpc specifies that the gRPC External Authorization
[protocol](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto) should be used.
properties:
contextExtensions:
additionalProperties:
type: string
description: contextExtensions specifies additional arbitrary
key-value pairs to send to the authorization server
in the `context_extensions` field.
maxProperties: 64
type: object
metadata:
additionalProperties:
description: CELExpression represents a Common Expression
Language (CEL) expression.
maxLength: 16384
minLength: 1
type: string
description: |-
metadata specifies metadata to be sent to the authorization server.
This maps to the `metadata_context.filter_metadata` field of the request, and allows dynamic CEL expressions.
If unset, by default the `envoy.filters.http.jwt_authn` key is set if the JWT policy is used as well, for compatibility.
maxProperties: 64
type: object
type: object
http:
description: |-
http specifies that the HTTP protocol should be used for connecting to the authorization server.
The authorization server must return a `200` status code, otherwise the request is considered and authorization failure.
properties:
addRequestHeaders:
additionalProperties:
description: CELExpression represents a Common Expression
Language (CEL) expression.
maxLength: 16384
minLength: 1
type: string
description: |-
addRequestHeaders specifies what additional headers to add to the request to the authorization server.
While allowedRequestHeaders just passes the original headers through, addRequestHeaders allows defining custom headers
based on CEL Expressions.
maxProperties: 64
type: object
allowedRequestHeaders:
description: |-
allowedRequestHeaders specifies what additional headers from the client request
will be sent to the authorization server.

If unset, the following headers are sent by default: `Authorization`.
items:
maxLength: 256
minLength: 1
type: string
maxItems: 64
type: array
allowedResponseHeaders:
description: |-
allowedResponseHeaders specifies what headers from the authorization response
will be copied into the request to the backend.
items:
maxLength: 256
minLength: 1
type: string
maxItems: 64
type: array
metadata:
additionalProperties:
description: CELExpression represents a Common Expression
Language (CEL) expression.
maxLength: 16384
minLength: 1
type: string
description: |-
metadata specifies what metadata fields should be constructed from the authorization response. These will be
included under the `extauthz` variable in future CEL expressions. Setting this is useful to do things like logging
usernames, without needing to include them as headers to the backend (as `allowedResponseHeaders` would).
maxProperties: 64
type: object
path:
description: |-
path specifies the path to send to the authorization server. If unset, this defaults to the original request path.
This is a CEL expression, which allows customizing the path based on the incoming request.
For example, to add a prefix: `path: '"/prefix/" + request.path'`.
maxLength: 16384
minLength: 1
type: string
redirect:
description: |-
redirect defines an optional expression to determine a path to redirect to on authorization failure.
This is useful to redirect to a sign-in page.
maxLength: 16384
minLength: 1
type: string
type: object
required:
- backendRef
type: object
x-kubernetes-validations:
- message: exactly one of the fields in [grpc http] must be set
rule: '[has(self.grpc),has(self.http)].filter(x,x==true).size()
== 1'
extProc:
description: extProc specifies the external processing configuration
for the policy.
Expand Down
Loading