request_authentication.proto

// Copyright 2019 Istio Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";

// $schema: istio.security.v1beta1.RequestAuthentication
// $title: RequestAuthentication
// $description: Request authentication configuration for workloads.
// $location: https://istio.io/docs/reference/config/security/request_authentication.html
// $aliases: [/docs/reference/config/security/v1beta1/request_authentication, /docs/reference/config/security/v1beta1/jwt, /docs/reference/config/security/v1beta1/jwt.html]

// RequestAuthentication defines what request authentication methods are supported by a workload.
// It will reject a request if the request contains invalid authentication information, based on the
// configured authentication rules. A request that does not contain any authentication credentials
// will be accepted but will not have any authenticated identity. To restrict access to authenticated
// requests only, this should be accompanied by an authorization rule.
// Examples:
//
// Require JWT for all request for workloads that have label `app:httpbin`:
//
// ```yaml
// apiVersion: security.istio.io/v1
// kind: RequestAuthentication
// metadata:
//   name: httpbin
//   namespace: foo
// spec:
//   selector:
//     matchLabels:
//       app: httpbin
//   jwtRules:
//   - issuer: "issuer-foo"
//     jwksUri: https://example.com/.well-known/jwks.json
// ---
// apiVersion: security.istio.io/v1
// kind: AuthorizationPolicy
// metadata:
//   name: httpbin
//   namespace: foo
// spec:
//   selector:
//     matchLabels:
//       app: httpbin
//   rules:
//   - from:
//     - source:
//         requestPrincipals: ["*"]
// ```
//
// A policy in the root namespace ("istio-system" by default) applies to workloads in all namespaces
// in a mesh. The following policy makes all workloads only accept requests that contain a
// valid JWT token:
//
// ```yaml
// apiVersion: security.istio.io/v1
// kind: RequestAuthentication
// metadata:
//   name: req-authn-for-all
//   namespace: istio-system
// spec:
//   jwtRules:
//   - issuer: "issuer-foo"
//     jwksUri: https://example.com/.well-known/jwks.json
// ---
// apiVersion: security.istio.io/v1
// kind: AuthorizationPolicy
// metadata:
//   name: require-jwt-for-all
//   namespace: istio-system
// spec:
//   rules:
//   - from:
//     - source:
//         requestPrincipals: ["*"]
// ```
//
// The next example shows how to set a different JWT requirement for a different `host`. The `RequestAuthentication`
// declares it can accept JWTs issued by either `issuer-foo` or `issuer-bar` (the public key set is implicitly
// set from the OpenID Connect spec):
//
// ```yaml
// apiVersion: security.istio.io/v1
// kind: RequestAuthentication
// metadata:
//   name: httpbin
//   namespace: foo
// spec:
//   selector:
//     matchLabels:
//       app: httpbin
//   jwtRules:
//   - issuer: "issuer-foo"
//   - issuer: "issuer-bar"
// ---
// apiVersion: security.istio.io/v1
// kind: AuthorizationPolicy
// metadata:
//   name: httpbin
//   namespace: foo
// spec:
//   selector:
//     matchLabels:
//       app: httpbin
//   rules:
//   - from:
//     - source:
//         requestPrincipals: ["issuer-foo/*"]
//     to:
//     - operation:
//         hosts: ["example.com"]
//   - from:
//     - source:
//         requestPrincipals: ["issuer-bar/*"]
//     to:
//     - operation:
//         hosts: ["another-host.com"]
// ```
//
// You can fine-tune the authorization policy to set different requirement per path. For example,
// to require JWT on all paths, except /healthz, the same `RequestAuthentication` can be used, but the
// authorization policy could be:
//
// ```yaml
// apiVersion: security.istio.io/v1
// kind: AuthorizationPolicy
// metadata:
//   name: httpbin
//   namespace: foo
// spec:
//   selector:
//     matchLabels:
//       app: httpbin
//   rules:
//   - from:
//     - source:
//         requestPrincipals: ["*"]
//   - to:
//     - operation:
//         paths: ["/healthz"]
// ```
//
// Alternatively, you can use `requireJwt: true` to enforce JWT requirement directly in the RequestAuthentication
// policy without needing a separate AuthorizationPolicy. This approach returns 401 Unauthorized with a
// `WWW-Authenticate: Bearer` header for missing JWTs instead of 403 Forbidden:
//
// ```yaml
// apiVersion: security.istio.io/v1
// kind: RequestAuthentication
// metadata:
//   name: httpbin
//   namespace: foo
// spec:
//   selector:
//     matchLabels:
//       app: httpbin
//   jwtRules:
//   - issuer: "issuer-foo"
//     jwksUri: https://example.com/.well-known/jwks.json
//     requireJwt: true
// ```
//
// With `requireJwt: true`, requests without a JWT will be rejected with 401 Unauthorized and a
// `WWW-Authenticate: Bearer` header, making it clearer that authentication is required. This is semantically
// more accurate than the 403 Forbidden returned by AuthorizationPolicy and complies with RFC 7235.
//
// [Experimental] Routing based on derived [metadata](https://istio.io/latest/docs/reference/config/security/conditions/)
// is now supported. A prefix '@' is used to denote a match against internal metadata instead of the headers in the request.
// Currently this feature is only supported for the following metadata:
//
// - `request.auth.claims.{claim-name}[.{nested-claim}]*` which are extracted from validated JWT tokens.
// Use the `.` or `[]` as a separator for nested claim names.
// Examples: `request.auth.claims.sub`, `request.auth.claims.name.givenName` and `request.auth.claims[foo.com/name]`.
// For more information, see [JWT claim based routing](https://istio.io/latest/docs/tasks/security/authentication/jwt-route/).
//
// The use of matches against JWT claim metadata is only supported in Gateways. The following example shows:
//
// - RequestAuthentication to decode and validate a JWT. This also makes the `@request.auth.claims` available for use in the VirtualService.
// - AuthorizationPolicy to check for valid principals in the request. This makes the JWT required for the request.
// - VirtualService to route the request based on the "sub" claim.
//
// ```yaml
// apiVersion: security.istio.io/v1
// kind: RequestAuthentication
// metadata:
//   name: jwt-on-ingress
//   namespace: istio-system
// spec:
//   selector:
//     matchLabels:
//       app: istio-ingressgateway
//   jwtRules:
//   - issuer: "example.com"
//     jwksUri: https://example.com/.well-known/jwks.json
// ---
// apiVersion: security.istio.io/v1
// kind: AuthorizationPolicy
// metadata:
//   name: require-jwt
//   namespace: istio-system
// spec:
//   selector:
//     matchLabels:
//       app: istio-ingressgateway
//   rules:
//   - from:
//     - source:
//         requestPrincipals: ["*"]
// ---
// apiVersion: networking.istio.io/v1
// kind: VirtualService
// metadata:
//   name: route-jwt
// spec:
//   hosts:
//   - foo.prod.svc.cluster.local
//   gateways:
//   - istio-ingressgateway
//   http:
//   - name: "v2"
//     match:
//     - headers:
//         "@request.auth.claims.sub":
//           exact: "dev"
//     route:
//     - destination:
//         host: foo.prod.svc.cluster.local
//         subset: v2
//   - name: "default"
//     route:
//     - destination:
//         host: foo.prod.svc.cluster.local
//         subset: v1
// ```
package istio.security.v1beta1;

import "google/api/field_behavior.proto";
import "google/protobuf/duration.proto";
import "type/v1beta1/selector.proto";

option go_package = "istio.io/api/security/v1beta1";

// <!-- crd generation tags
// +cue-gen:RequestAuthentication:groupName:security.istio.io
// +cue-gen:RequestAuthentication:versions:v1,v1beta1
// +cue-gen:RequestAuthentication:storageVersion
// +cue-gen:RequestAuthentication:annotations:helm.sh/resource-policy=keep
// +cue-gen:RequestAuthentication:labels:app=istio-pilot,chart=istio,istio=security,heritage=Tiller,release=istio
// +cue-gen:RequestAuthentication:subresource:status
// +cue-gen:RequestAuthentication:scope:Namespaced
// +cue-gen:RequestAuthentication:resource:categories=istio-io,security-istio-io,shortNames=ra
// +cue-gen:RequestAuthentication:preserveUnknownFields:false
// -->
//
// <!-- go code generation tags
// +kubetype-gen
// +kubetype-gen:groupVersion=security.istio.io/v1beta1
// +genclient
// +k8s:deepcopy-gen=true
// -->
// +kubebuilder:validation:XValidation:message="only one of targetRefs or selector can be set",rule="oneof(self.selector, self.targetRef, self.targetRefs)"
message RequestAuthentication {
  // Optional. The selector decides where to apply the request authentication policy. The selector will match with workloads
  // in the same namespace as the request authentication policy. If the request authentication policy is in the root namespace,
  // the selector will additionally match with workloads in all namespaces.
  //
  // If not set, the selector will match all workloads.
  //
  // At most one of `selector` or `targetRefs` can be set for a given policy.
  istio.type.v1beta1.WorkloadSelector selector = 1;

  // $hide_from_docs
  istio.type.v1beta1.PolicyTargetReference targetRef = 3;

  // Optional. The targetRefs specifies a list of resources the policy should be
  // applied to. The targeted resources specified will determine which workloads
  // the policy applies to.
  //
  // Currently, the following resource attachment types are supported:
  // * `kind: Gateway` with `group: gateway.networking.k8s.io` in the same namespace.
  // * `kind: GatewayClass` with `group: gateway.networking.k8s.io` in the root namespace.
  // * `kind: Service` with `group: ""` or `group: "core"` in the same namespace. This type is only supported for waypoints.
  // * `kind: ServiceEntry` with `group: networking.istio.io` in the same namespace.
  //
  // If not set, the policy is applied as defined by the selector.
  // At most one of the selector and targetRefs can be set.
  //
  // NOTE: If you are using the `targetRefs` field in a multi-revision environment with Istio versions prior to 1.22,
  // it is highly recommended that you pin the policy to a revision running 1.22+ via the `istio.io/rev` label.
  // This is to prevent proxies connected to older control planes (that don't know about the `targetRefs` field)
  // from misinterpreting the policy as namespace-wide during the upgrade process.
  //
  // NOTE: Waypoint proxies are required to use this field for policies to apply; `selector` policies will be ignored.
  // +kubebuilder:validation:MaxItems=16
  repeated istio.type.v1beta1.PolicyTargetReference targetRefs = 4;

  // Define the list of JWTs that can be validated at the selected workloads' proxy. A valid token
  // will be used to extract the authenticated identity.
  // Each rule will be activated only when a token is presented at the location recognized by the
  // rule. The token will be validated based on the JWT rule config. If validation fails, the request will
  // be rejected.
  // Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
  // such requests is undefined.
  // +kubebuilder:validation:MaxItems=4096
  repeated JWTRule jwt_rules = 2;
}

// JSON Web Token (JWT) token format for authentication as defined by
// [RFC 7519](https://tools.ietf.org/html/rfc7519). See [OAuth 2.0](https://tools.ietf.org/html/rfc6749) and
// [OIDC 1.0](http://openid.net/connect) for how this is used in the whole
// authentication flow.
//
// Examples:
//
// Spec for a JWT that is issued by `https://example.com`, with the audience claims must be either
// `bookstore_android.apps.example.com` or `bookstore_web.apps.example.com`.
// The token should be presented at the `Authorization` header (default). The JSON Web Key Set (JWKS)
// will be discovered following OpenID Connect protocol.
//
// ```yaml
// issuer: https://example.com
// audiences:
// - bookstore_android.apps.example.com
//   bookstore_web.apps.example.com
// ```
//
// This example specifies a token in a non-default location (`x-goog-iap-jwt-assertion` header). It also
// defines the URI to fetch JWKS explicitly.
//
// ```yaml
// issuer: https://example.com
// jwksUri: https://example.com/.secret/jwks.json
// fromHeaders:
// - "x-goog-iap-jwt-assertion"
// ```
//
// This example shows how to configure custom claims to be treated as space-delimited strings.
// This is useful when JWT tokens contain custom claims with multiple space-separated values
// that should be available for individual matching in authorization policies.
//
// ```yaml
// issuer: https://example.com
// spaceDelimitedClaims:
// - "custom_scope"
// - "provider.login.scope"
// - "roles"
// ```
//
// With this configuration, a JWT containing `"custom_scope": "read write admin"` will allow
// authorization policies to match against individual values like "read", "write", or "admin".
//
// This example shows how to require JWT tokens and return 401 for missing tokens:
//
// ```yaml
// issuer: https://example.com
// jwksUri: https://example.com/.well-known/jwks.json
// requireJwt: true
// ```
//
// With `requireJwt: true`, requests without a JWT will receive a 401 Unauthorized response with a
// `WWW-Authenticate: Bearer` header directly from the authentication filter, eliminating the need
// for a separate AuthorizationPolicy when you simply want to require authentication.
// +kubebuilder:validation:XValidation:message="only one of jwks or jwksUri can be set",rule="oneof(self.jwksUri, self.jwks_uri, self.jwks)"
message JWTRule {
  // Identifies the issuer that issued the JWT. See
  // [issuer](https://tools.ietf.org/html/rfc7519#section-4.1.1)
  // A JWT with different `iss` claim will be rejected.
  //
  // Example: `https://foobar.auth0.com`
  // Example: `1234567-compute@developer.gserviceaccount.com`
  // +kubebuilder:validation:MinLength=1
  string issuer = 1;

  // The list of JWT
  // [audiences](https://tools.ietf.org/html/rfc7519#section-4.1.3)
  // that are allowed to access. A JWT containing any of these
  // audiences will be accepted.
  //
  // The service name will be accepted if audiences is empty.
  //
  // Example:
  //
  // ```yaml
  // audiences:
  // - bookstore_android.apps.example.com
  //   bookstore_web.apps.example.com
  // ```
  // +protoc-gen-crd:list-value-validation:MinLength=1
  repeated string audiences = 2;

  // URL of the provider's public key set to validate signature of the
  // JWT. See [OpenID Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).
  //
  // Optional if the key set document can either (a) be retrieved from
  // [OpenID
  // Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) of
  // the issuer or (b) inferred from the email domain of the issuer (e.g. a
  // Google service account).
  //
  // Example: `https://www.googleapis.com/oauth2/v1/certs`
  //
  // Note: Only one of `jwksUri` and `jwks` should be used.
  // +kubebuilder:altName=jwks_uri
  // +kubebuilder:validation:MinLength=1
  // +kubebuilder:validation:MaxLength=2048
  // +kubebuilder:validation:XValidation:message="url must have scheme http:// or https://",rule="url(self).getScheme() in ['http', 'https']"
  string jwks_uri = 3;

  // JSON Web Key Set of public keys to validate signature of the JWT.
  // See https://auth0.com/docs/jwks.
  //
  // Note: Only one of `jwksUri` and `jwks` should be used.
  string jwks = 10;

  // The next two fields define how to extract the JWT from an HTTP request.
  //
  // If no explicit location is specified the following default
  // locations are tried in order:
  //
  //     1) The Authorization header using the Bearer schema,
  //        e.g. Authorization: Bearer <token>. (see
  //        [Authorization Request Header
  //        Field](https://tools.ietf.org/html/rfc6750#section-2.1))
  //
  //     2) The `access_token` query parameter (see
  //     [URI Query Parameter](https://tools.ietf.org/html/rfc6750#section-2.3))

  // List of header locations from which JWT is expected. For example, below is the location spec
  // if JWT is expected to be found in `x-jwt-assertion` header, and have `Bearer` prefix:
  //
  // ```yaml
  //   fromHeaders:
  //   - name: x-jwt-assertion
  //     prefix: "Bearer "
  // ```
  //
  // Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
  // such requests is undefined.
  repeated JWTHeader from_headers = 6;

  // List of query parameters from which JWT is expected. For example, if JWT is provided via query
  // parameter `my_token` (e.g `/path?my_token=<JWT>`), the config is:
  //
  // ```yaml
  //   fromParams:
  //   - "my_token"
  // ```
  //
  // Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
  // such requests is undefined.
  // +protoc-gen-crd:list-value-validation:MinLength=1
  repeated string from_params = 7;

  // This field specifies the header name to output a successfully verified JWT payload to the
  // backend. The forwarded data is `base64_encoded(jwt_payload_in_JSON)`. If it is not specified,
  // the payload will not be emitted.
  string output_payload_to_header = 8;

  // List of cookie names from which JWT is expected.	//
  // For example, if config is:
  //
  // ``` yaml
  //   fromCookies:
  //   - auth-token
  // ```
  // Then JWT will be extracted from `auth-token` cookie in the request.
  //
  // Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
  // such requests is undefined.
  // +protoc-gen-crd:list-value-validation:MinLength=1
  repeated string from_cookies = 12;

  // If set to true, the original token will be kept for the upstream request. Default is false.
  bool forward_original_token = 9;

  // This field specifies a list of operations to copy the claim to HTTP headers on a successfully verified token.
  // This differs from the `output_payload_to_header` by allowing outputting individual claims instead of the whole payload.
  // The header specified in each operation in the list must be unique. Nested claims of type string/int/bool is supported as well.
  // ```
  //   outputClaimToHeaders:
  //   - header: x-my-company-jwt-group
  //     claim: my-group
  //   - header: x-test-environment-flag
  //     claim: test-flag
  //   - header: x-jwt-claim-group
  //     claim: nested.key.group
  // ```
  // [Experimental] This feature is a experimental feature.
  repeated ClaimToHeader output_claim_to_headers = 11; // [TODO:Update the status whenever this feature is promoted.]

  // The maximum amount of time that the resolver, determined by the PILOT_JWT_ENABLE_REMOTE_JWKS environment variable,
  // will spend waiting for the JWKS to be fetched. Default is 5s.
  google.protobuf.Duration timeout = 13;

  // List of JWT claim names that should be treated as space-delimited strings.
  // These claims will be split on whitespace and each individual value will be available
  // for matching in authorization policies. This extends the default behavior that only
  // treats 'scope' and 'permission' claims as space-delimited.
  //
  // Example usage for custom claims:
  // ```yaml
  // spaceDelimitedClaims:
  // - "custom_scope"
  // - "provider.login.scope"
  // - "roles"
  // ```
  //
  // This allows authorization policies to match individual values within space-separated
  // claim strings, maintaining compatibility with existing JWT token formats.
  //
  // Note: The default claims 'scope' and 'permission' are always treated as space-delimited
  // regardless of this setting.
  // +protoc-gen-crd:list-value-validation:MinLength=1
  // +kubebuilder:validation:MaxItems=64
  repeated string space_delimited_claims = 14;

  // If set to true, requests without a valid JWT token will be rejected with a 401 Unauthorized status code
  // along with a `WWW-Authenticate` header indicating the Bearer authentication scheme is required.
  // If set to false or unset (default), requests without a JWT token are allowed to pass through but will not have
  // an authenticated identity. In the default case, to enforce that requests must have authentication,
  // you should use an AuthorizationPolicy with requestPrincipals.
  //
  // Note: Setting this to true changes the HTTP status code for missing JWT from 403 (via AuthorizationPolicy)
  // to 401 (via RequestAuthentication), which is semantically more accurate for authentication failures and
  // includes the proper `WWW-Authenticate` header as required by RFC 7235.
  //
  // Example usage:
  // ```yaml
  // jwtRules:
  // - issuer: "https://example.com"
  //   jwksUri: https://example.com/.well-known/jwks.json
  //   requireJwt: true
  // ```
  //
  // With `requireJwt: true`:
  // - Request with missing JWT -> 401 Unauthorized (with WWW-Authenticate: Bearer header)
  // - Request with invalid/expired JWT -> 401 Unauthorized (with WWW-Authenticate: Bearer header)
  // - Request with valid JWT -> Accepted
  //
  // With `requireJwt: false` (default):
  // - Request with missing JWT -> Accepted (no authenticated identity)
  // - Request with invalid/expired JWT -> 401 Unauthorized (with WWW-Authenticate: Bearer header)
  // - Request with valid JWT -> Accepted (with authenticated identity)
  bool require_jwt = 15;

  // $hide_from_docs
  // Next available field number: 16
}

// This message specifies a header location to extract JWT token.
message JWTHeader {
  // The HTTP header name.
  // +kubebuilder:validation:MinLength=1
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // The prefix that should be stripped before decoding the token.
  // For example, for `Authorization: Bearer <token>`, prefix=`Bearer` with a space at the end.
  // If the header doesn't have this exact prefix, it is considered invalid.
  string prefix = 2;
}

// This message specifies the detail for copying claim to header.
message ClaimToHeader {
  // The name of the header to be created. The header will be overridden if it already exists in the request.
  // +kubebuilder:validation:MinLength=1
  // +kubebuilder:validation:Pattern=^[-_A-Za-z0-9]+$
  string header = 1 [(google.api.field_behavior) = REQUIRED];

  // The name of the claim to be copied from. Only claim of type string/int/bool is supported.
  // The header will not be there if the claim does not exist or the type of the claim is not supported.
  // +kubebuilder:validation:MinLength=1
  string claim = 2 [(google.api.field_behavior) = REQUIRED];
}