request_authentication.pb.html

---
title: RequestAuthentication
description: Request authentication configuration for workloads.
location: https://istio.io/docs/reference/config/security/request_authentication.html
layout: protoc-gen-docs
generator: protoc-gen-docs
schema: istio.security.v1beta1.RequestAuthentication
aliases: [/docs/reference/config/security/v1beta1/request_authentication, /docs/reference/config/security/v1beta1/jwt, /docs/reference/config/security/v1beta1/jwt.html]
number_of_entries: 4
---
<p>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:</p>
<p>Require JWT for all request for workloads that have label <code>app:httpbin</code>:</p>
<pre><code class="language-yaml">apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: httpbin
  namespace: foo
spec:
  selector:
    matchLabels:
      app: httpbin
  jwtRules:
  - issuer: &quot;issuer-foo&quot;
    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: [&quot;*&quot;]
</code></pre>
<p>A policy in the root namespace (&ldquo;istio-system&rdquo; 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:</p>
<pre><code class="language-yaml">apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: req-authn-for-all
  namespace: istio-system
spec:
  jwtRules:
  - issuer: &quot;issuer-foo&quot;
    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: [&quot;*&quot;]
</code></pre>
<p>The next example shows how to set a different JWT requirement for a different <code>host</code>. The <code>RequestAuthentication</code>
declares it can accept JWTs issued by either <code>issuer-foo</code> or <code>issuer-bar</code> (the public key set is implicitly
set from the OpenID Connect spec):</p>
<pre><code class="language-yaml">apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: httpbin
  namespace: foo
spec:
  selector:
    matchLabels:
      app: httpbin
  jwtRules:
  - issuer: &quot;issuer-foo&quot;
  - issuer: &quot;issuer-bar&quot;
---
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: httpbin
  namespace: foo
spec:
  selector:
    matchLabels:
      app: httpbin
  rules:
  - from:
    - source:
        requestPrincipals: [&quot;issuer-foo/*&quot;]
    to:
    - operation:
        hosts: [&quot;example.com&quot;]
  - from:
    - source:
        requestPrincipals: [&quot;issuer-bar/*&quot;]
    to:
    - operation:
        hosts: [&quot;another-host.com&quot;]
</code></pre>
<p>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 <code>RequestAuthentication</code> can be used, but the
authorization policy could be:</p>
<pre><code class="language-yaml">apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: httpbin
  namespace: foo
spec:
  selector:
    matchLabels:
      app: httpbin
  rules:
  - from:
    - source:
        requestPrincipals: [&quot;*&quot;]
  - to:
    - operation:
        paths: [&quot;/healthz&quot;]
</code></pre>
<p>[Experimental] Routing based on derived <a href="https://istio.io/latest/docs/reference/config/security/conditions/">metadata</a>
is now supported. A prefix &lsquo;@&rsquo; 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:</p>
<ul>
<li><code>request.auth.claims.{claim-name}[.{nested-claim}]*</code> which are extracted from validated JWT tokens.
Use the <code>.</code> or <code>[]</code> as a separator for nested claim names.
Examples: <code>request.auth.claims.sub</code>, <code>request.auth.claims.name.givenName</code> and <code>request.auth.claims[foo.com/name]</code>.
For more information, see <a href="https://istio.io/latest/docs/tasks/security/authentication/jwt-route/">JWT claim based routing</a>.</li>
</ul>
<p>The use of matches against JWT claim metadata is only supported in Gateways. The following example shows:</p>
<ul>
<li>RequestAuthentication to decode and validate a JWT. This also makes the <code>@request.auth.claims</code> available for use in the VirtualService.</li>
<li>AuthorizationPolicy to check for valid principals in the request. This makes the JWT required for the request.</li>
<li>VirtualService to route the request based on the &ldquo;sub&rdquo; claim.</li>
</ul>
<pre><code class="language-yaml">apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: jwt-on-ingress
  namespace: istio-system
spec:
  selector:
    matchLabels:
      app: istio-ingressgateway
  jwtRules:
  - issuer: &quot;example.com&quot;
    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: [&quot;*&quot;]
---
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: route-jwt
spec:
  hosts:
  - foo.prod.svc.cluster.local
  gateways:
  - istio-ingressgateway
  http:
  - name: &quot;v2&quot;
    match:
    - headers:
        &quot;@request.auth.claims.sub&quot;:
          exact: &quot;dev&quot;
    route:
    - destination:
        host: foo.prod.svc.cluster.local
        subset: v2
  - name: &quot;default&quot;
    route:
    - destination:
        host: foo.prod.svc.cluster.local
        subset: v1
</code></pre>

<h2 id="RequestAuthentication">RequestAuthentication</h2>
<section>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="RequestAuthentication-selector">
<td><div class="field"><div class="name"><code><a href="#RequestAuthentication-selector">selector</a></code></div>
<div class="type"><a href="https://istio.io/docs/reference/config/type/workload-selector.html#WorkloadSelector">WorkloadSelector</a></div>
</div></td>
<td>
<p>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.</p>
<p>If not set, the selector will match all workloads.</p>
<p>At most one of <code>selector</code> or <code>targetRefs</code> can be set for a given policy.</p>

</td>
</tr>
<tr id="RequestAuthentication-targetRefs">
<td><div class="field"><div class="name"><code><a href="#RequestAuthentication-targetRefs">targetRefs</a></code></div>
<div class="type"><a href="https://istio.io/docs/reference/config/type/workload-selector.html#PolicyTargetReference">PolicyTargetReference[]</a></div>
</div></td>
<td>
<p>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.</p>
<p>Currently, the following resource attachment types are supported:</p>
<ul>
<li><code>kind: Gateway</code> with <code>group: gateway.networking.k8s.io</code> in the same namespace.</li>
<li><code>kind: GatewayClass</code> with <code>group: gateway.networking.k8s.io</code> in the root namespace.</li>
<li><code>kind: Service</code> with <code>group: &quot;&quot;</code> or <code>group: &quot;core&quot;</code> in the same namespace. This type is only supported for waypoints.</li>
<li><code>kind: ServiceEntry</code> with <code>group: networking.istio.io</code> in the same namespace.</li>
</ul>
<p>If not set, the policy is applied as defined by the selector.
At most one of the selector and targetRefs can be set.</p>
<p>NOTE: If you are using the <code>targetRefs</code> 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 <code>istio.io/rev</code> label.
This is to prevent proxies connected to older control planes (that don&rsquo;t know about the <code>targetRefs</code> field)
from misinterpreting the policy as namespace-wide during the upgrade process.</p>
<p>NOTE: Waypoint proxies are required to use this field for policies to apply; <code>selector</code> policies will be ignored.</p>

</td>
</tr>
<tr id="RequestAuthentication-jwt_rules">
<td><div class="field"><div class="name"><code><a href="#RequestAuthentication-jwt_rules">jwtRules</a></code></div>
<div class="type"><a href="#JWTRule">JWTRule[]</a></div>
</div></td>
<td>
<p>Define the list of JWTs that can be validated at the selected workloads&rsquo; 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.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="JWTRule">JWTRule</h2>
<section>
<p>JSON Web Token (JWT) token format for authentication as defined by
<a href="https://tools.ietf.org/html/rfc7519">RFC 7519</a>. See <a href="https://tools.ietf.org/html/rfc6749">OAuth 2.0</a> and
<a href="http://openid.net/connect">OIDC 1.0</a> for how this is used in the whole
authentication flow.</p>
<p>Examples:</p>
<p>Spec for a JWT that is issued by <code>https://example.com</code>, with the audience claims must be either
<code>bookstore_android.apps.example.com</code> or <code>bookstore_web.apps.example.com</code>.
The token should be presented at the <code>Authorization</code> header (default). The JSON Web Key Set (JWKS)
will be discovered following OpenID Connect protocol.</p>
<pre><code class="language-yaml">issuer: https://example.com
audiences:
- bookstore_android.apps.example.com
  bookstore_web.apps.example.com
</code></pre>
<p>This example specifies a token in a non-default location (<code>x-goog-iap-jwt-assertion</code> header). It also
defines the URI to fetch JWKS explicitly.</p>
<pre><code class="language-yaml">issuer: https://example.com
jwksUri: https://example.com/.secret/jwks.json
fromHeaders:
- &quot;x-goog-iap-jwt-assertion&quot;
</code></pre>
<p>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.</p>
<pre><code class="language-yaml">issuer: https://example.com
spaceDelimitedClaims:
- &quot;custom_scope&quot;
- &quot;provider.login.scope&quot;
- &quot;roles&quot;
</code></pre>
<p>With this configuration, a JWT containing <code>&quot;custom_scope&quot;: &quot;read write admin&quot;</code> will allow
authorization policies to match against individual values like &ldquo;read&rdquo;, &ldquo;write&rdquo;, or &ldquo;admin&rdquo;.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="JWTRule-issuer">
<td><div class="field"><div class="name"><code><a href="#JWTRule-issuer">issuer</a></code></div>
<div class="type">string</div>
</div></td>
<td>
<p>Identifies the issuer that issued the JWT. See
<a href="https://tools.ietf.org/html/rfc7519#section-4.1.1">issuer</a>
A JWT with different <code>iss</code> claim will be rejected.</p>
<p>Example: <code>https://foobar.auth0.com</code>
Example: <code>1234567-compute@developer.gserviceaccount.com</code></p>

</td>
</tr>
<tr id="JWTRule-audiences">
<td><div class="field"><div class="name"><code><a href="#JWTRule-audiences">audiences</a></code></div>
<div class="type">string[]</div>
</div></td>
<td>
<p>The list of JWT
<a href="https://tools.ietf.org/html/rfc7519#section-4.1.3">audiences</a>
that are allowed to access. A JWT containing any of these
audiences will be accepted.</p>
<p>The service name will be accepted if audiences is empty.</p>
<p>Example:</p>
<pre><code class="language-yaml">audiences:
- bookstore_android.apps.example.com
  bookstore_web.apps.example.com
</code></pre>

</td>
</tr>
<tr id="JWTRule-jwks_uri">
<td><div class="field"><div class="name"><code><a href="#JWTRule-jwks_uri">jwksUri</a></code></div>
<div class="type">string</div>
</div></td>
<td>
<p>URL of the provider&rsquo;s public key set to validate signature of the
JWT. See <a href="https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata">OpenID Discovery</a>.</p>
<p>Optional if the key set document can either (a) be retrieved from
<a href="https://openid.net/specs/openid-connect-discovery-1_0.html">OpenID
Discovery</a> of
the issuer or (b) inferred from the email domain of the issuer (e.g. a
Google service account).</p>
<p>Example: <code>https://www.googleapis.com/oauth2/v1/certs</code></p>
<p>Note: Only one of <code>jwksUri</code> and <code>jwks</code> should be used.</p>

</td>
</tr>
<tr id="JWTRule-jwks">
<td><div class="field"><div class="name"><code><a href="#JWTRule-jwks">jwks</a></code></div>
<div class="type">string</div>
</div></td>
<td>
<p>JSON Web Key Set of public keys to validate signature of the JWT.
See <a href="https://auth0.com/docs/jwks">https://auth0.com/docs/jwks</a>.</p>
<p>Note: Only one of <code>jwksUri</code> and <code>jwks</code> should be used.</p>

</td>
</tr>
<tr id="JWTRule-from_headers">
<td><div class="field"><div class="name"><code><a href="#JWTRule-from_headers">fromHeaders</a></code></div>
<div class="type"><a href="#JWTHeader">JWTHeader[]</a></div>
</div></td>
<td>
<p>List of header locations from which JWT is expected. For example, below is the location spec
if JWT is expected to be found in <code>x-jwt-assertion</code> header, and have <code>Bearer</code> prefix:</p>
<pre><code class="language-yaml">  fromHeaders:
  - name: x-jwt-assertion
    prefix: &quot;Bearer &quot;
</code></pre>
<p>Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
such requests is undefined.</p>

</td>
</tr>
<tr id="JWTRule-from_params">
<td><div class="field"><div class="name"><code><a href="#JWTRule-from_params">fromParams</a></code></div>
<div class="type">string[]</div>
</div></td>
<td>
<p>List of query parameters from which JWT is expected. For example, if JWT is provided via query
parameter <code>my_token</code> (e.g <code>/path?my_token=&lt;JWT&gt;</code>), the config is:</p>
<pre><code class="language-yaml">  fromParams:
  - &quot;my_token&quot;
</code></pre>
<p>Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
such requests is undefined.</p>

</td>
</tr>
<tr id="JWTRule-output_payload_to_header">
<td><div class="field"><div class="name"><code><a href="#JWTRule-output_payload_to_header">outputPayloadToHeader</a></code></div>
<div class="type">string</div>
</div></td>
<td>
<p>This field specifies the header name to output a successfully verified JWT payload to the
backend. The forwarded data is <code>base64_encoded(jwt_payload_in_JSON)</code>. If it is not specified,
the payload will not be emitted.</p>

</td>
</tr>
<tr id="JWTRule-from_cookies">
<td><div class="field"><div class="name"><code><a href="#JWTRule-from_cookies">fromCookies</a></code></div>
<div class="type">string[]</div>
</div></td>
<td>
<p>List of cookie names from which JWT is expected.	//
For example, if config is:</p>
<pre><code class="language-yaml">  fromCookies:
  - auth-token
</code></pre>
<p>Then JWT will be extracted from <code>auth-token</code> cookie in the request.</p>
<p>Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
such requests is undefined.</p>

</td>
</tr>
<tr id="JWTRule-forward_original_token">
<td><div class="field"><div class="name"><code><a href="#JWTRule-forward_original_token">forwardOriginalToken</a></code></div>
<div class="type">bool</div>
</div></td>
<td>
<p>If set to true, the original token will be kept for the upstream request. Default is false.</p>

</td>
</tr>
<tr id="JWTRule-output_claim_to_headers">
<td><div class="field"><div class="name"><code><a href="#JWTRule-output_claim_to_headers">outputClaimToHeaders</a></code></div>
<div class="type"><a href="#ClaimToHeader">ClaimToHeader[]</a></div>
</div></td>
<td>
<p>This field specifies a list of operations to copy the claim to HTTP headers on a successfully verified token.
This differs from the <code>output_payload_to_header</code> 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.</p>
<pre><code>  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
</code></pre>
<p>[Experimental] This feature is a experimental feature.</p>

</td>
</tr>
<tr id="JWTRule-timeout">
<td><div class="field"><div class="name"><code><a href="#JWTRule-timeout">timeout</a></code></div>
<div class="type"><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></div>
</div></td>
<td>
<p>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.</p>

</td>
</tr>
<tr id="JWTRule-space_delimited_claims">
<td><div class="field"><div class="name"><code><a href="#JWTRule-space_delimited_claims">spaceDelimitedClaims</a></code></div>
<div class="type">string[]</div>
</div></td>
<td>
<p>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 &lsquo;scope&rsquo; and &lsquo;permission&rsquo; claims as space-delimited.</p>
<p>Example usage for custom claims:</p>
<pre><code class="language-yaml">spaceDelimitedClaims:
- &quot;custom_scope&quot;
- &quot;provider.login.scope&quot;
- &quot;roles&quot;
</code></pre>
<p>This allows authorization policies to match individual values within space-separated
claim strings, maintaining compatibility with existing JWT token formats.</p>
<p>Note: The default claims &lsquo;scope&rsquo; and &lsquo;permission&rsquo; are always treated as space-delimited
regardless of this setting.</p>

</td>
</tr>
<tr id="JWTRule-require_expiration">
<td><div class="field"><div class="name"><code><a href="#JWTRule-require_expiration">requireExpiration</a></code></div>
<div class="type">bool</div>
</div></td>
<td>
<p>If set to true, a JWT without an expiration
(<a href="https://tools.ietf.org/html/rfc7519#section-4.1.4"><code>exp</code></a>) claim is rejected.
This enforces that every accepted token is short-lived and will eventually
expire, which is recommended for zero-trust deployments that rely on token
expiration rather than revocation (for example,
<a href="https://github.com/spiffe/spiffe/blob/main/standards/JWT-SVID.md#33-expiration-time">SPIFFE JWT-SVID</a>
expiration restrictions).</p>
<p>By default (<code>false</code>), a JWT without an <code>exp</code> claim is accepted and treated as
non-expiring, matching the existing behavior.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="JWTHeader">JWTHeader</h2>
<section>
<p>This message specifies a header location to extract JWT token.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="JWTHeader-name">
<td><div class="field"><div class="name"><code><a href="#JWTHeader-name">name</a></code></div>
<div class="type">string</div>
<div class="required">Required</div>
</div></td>
<td>
<p>The HTTP header name.</p>

</td>
</tr>
<tr id="JWTHeader-prefix">
<td><div class="field"><div class="name"><code><a href="#JWTHeader-prefix">prefix</a></code></div>
<div class="type">string</div>
</div></td>
<td>
<p>The prefix that should be stripped before decoding the token.
For example, for <code>Authorization: Bearer &lt;token&gt;</code>, prefix=<code>Bearer</code> with a space at the end.
If the header doesn&rsquo;t have this exact prefix, it is considered invalid.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ClaimToHeader">ClaimToHeader</h2>
<section>
<p>This message specifies the detail for copying claim to header.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="ClaimToHeader-header">
<td><div class="field"><div class="name"><code><a href="#ClaimToHeader-header">header</a></code></div>
<div class="type">string</div>
<div class="required">Required</div>
</div></td>
<td>
<p>The name of the header to be created. The header will be overridden if it already exists in the request.</p>

</td>
</tr>
<tr id="ClaimToHeader-claim">
<td><div class="field"><div class="name"><code><a href="#ClaimToHeader-claim">claim</a></code></div>
<div class="type">string</div>
<div class="required">Required</div>
</div></td>
<td>
<p>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.</p>

</td>
</tr>
</tbody>
</table>
</section>