---
title: Authentication Policy
description: Authentication policy for Istio services.
location: https://istio.io/docs/reference/config/istio.authentication.v1alpha1.html
layout: protoc-gen-docs
generator: protoc-gen-docs
number_of_entries: 11
---
<p>This package defines user-facing authentication policy.</p>

<h2 id="Jwt">Jwt</h2>
<section>
<p>JSON Web Token (JWT) token format for authentication as defined by
https://tools.ietf.org/html/rfc7519. 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>For example:</p>

<p>A JWT for any requests:</p>

<pre><code class="language-yaml">issuer: https://example.com
audiences:
- bookstore_android.apps.googleusercontent.com
  bookstore_web.apps.googleusercontent.com
jwksUri: https://example.com/.well-known/jwks.json
</code></pre>

<p>A JWT for all requests except request at path <code>/health_check</code> and path with
prefix <code>/status/</code>. This is useful to expose some paths for public access but
keep others JWT validated.</p>

<pre><code class="language-yaml">issuer: https://example.com
jwks_uri: https://example.com/.well-known/jwks.json
trigger_rules:
- excluded_paths:
  - exact: /health_check
  - prefix: /status/
</code></pre>

<p>A JWT only for requests at path <code>/admin</code>. This is useful to only require JWT
validation on a specific set of paths but keep others public accessible.</p>

<pre><code class="language-yaml">issuer: https://example.com
jwks_uri: https://example.com/.well-known/jwks.json
trigger_rules:
- included_paths:
  - prefix: /admin
</code></pre>

<p>A JWT only for requests at path of prefix <code>/status/</code> but except the path of
<code>/status/version</code>. This means for any request path with prefix <code>/status/</code> except
<code>/status/version</code> will require a valid JWT to proceed.</p>

<pre><code class="language-yaml">issuer: https://example.com
jwks_uri: https://example.com/.well-known/jwks.json
trigger_rules:
- excluded_paths:
  - exact: /status/version
  included_paths:
  - prefix: /status/
</code></pre>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="Jwt-issuer">
<td><code>issuer</code></td>
<td><code>string</code></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>
Usually a URL or an email address.</p>

<p>Example: https://securetoken.google.com
Example: 1234567-compute@developer.gserviceaccount.com</p>

</td>
</tr>
<tr id="Jwt-audiences">
<td><code>audiences</code></td>
<td><code>string[]</code></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.googleusercontent.com
  bookstore_web.apps.googleusercontent.com
</code></pre>

</td>
</tr>
<tr id="Jwt-jwks_uri">
<td><code>jwksUri</code></td>
<td><code>string</code></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: https://www.googleapis.com/oauth2/v1/certs</p>

</td>
</tr>
<tr id="Jwt-jwt_headers">
<td><code>jwtHeaders</code></td>
<td><code>string[]</code></td>
<td>
<p>JWT is sent in a request header. <code>header</code> represents the
header name.</p>

<p>For example, if <code>header=x-goog-iap-jwt-assertion</code>, the header
format will be x-goog-iap-jwt-assertion: <JWT>.</p>

</td>
</tr>
<tr id="Jwt-jwt_params">
<td><code>jwtParams</code></td>
<td><code>string[]</code></td>
<td>
<p>JWT is sent in a query parameter. <code>query</code> represents the
query parameter name.</p>

<p>For example, <code>query=jwt_token</code>.</p>

</td>
</tr>
<tr id="Jwt-trigger_rules">
<td><code>triggerRules</code></td>
<td><code><a href="#Jwt-TriggerRule">Jwt.TriggerRule[]</a></code></td>
<td>
<p>List of trigger rules to decide if this JWT should be used to validate the
request. The JWT validation happens if any one of the rules matched.
If the list is not empty and none of the rules matched, authentication will
skip the JWT validation.
Leave this empty to always trigger the JWT validation.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="Jwt-TriggerRule">Jwt.TriggerRule</h2>
<section>
<p>Trigger rule to match against a request. The trigger rule is satisfied if
and only if both rules, excluded<em>paths and include</em>paths are satisfied.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="Jwt-TriggerRule-excluded_paths">
<td><code>excludedPaths</code></td>
<td><code><a href="#StringMatch">StringMatch[]</a></code></td>
<td>
<p>List of paths to be excluded from the request. The rule is satisfied if
request path does not match to any of the path in this list.</p>

</td>
</tr>
<tr id="Jwt-TriggerRule-included_paths">
<td><code>includedPaths</code></td>
<td><code><a href="#StringMatch">StringMatch[]</a></code></td>
<td>
<p>List of paths that the request must include. If the list is not empty, the
rule is satisfied if request path matches at least one of the path in the list.
If the list is empty, the rule is ignored, in other words the rule is always satisfied.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="MutualTls">MutualTls</h2>
<section>
<p>TLS authentication params.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="MutualTls-allow_tls">
<td><code>allowTls</code></td>
<td><code>bool</code></td>
<td>
<p>WILL BE DEPRECATED, if set, will translates to <code>TLS_PERMISSIVE</code> mode.
Set this flag to true to allow regular TLS (i.e without client x509
certificate). If request carries client certificate, identity will be
extracted and used (set to peer identity). Otherwise, peer identity will
be left unset.
When the flag is false (default), request must have client certificate.</p>

</td>
</tr>
<tr id="MutualTls-mode">
<td><code>mode</code></td>
<td><code><a href="#MutualTls-Mode">MutualTls.Mode</a></code></td>
<td>
<p>Defines the mode of mTLS authentication.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="MutualTls-Mode">MutualTls.Mode</h2>
<section>
<p>Defines the acceptable connection TLS mode.</p>

<table class="enum-values">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="MutualTls-Mode-STRICT">
<td><code>STRICT</code></td>
<td>
<p>Client cert must be presented, connection is in TLS.</p>

</td>
</tr>
<tr id="MutualTls-Mode-PERMISSIVE">
<td><code>PERMISSIVE</code></td>
<td>
<p>Connection can be either plaintext or TLS, and client cert can be omitted.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="OriginAuthenticationMethod">OriginAuthenticationMethod</h2>
<section>
<p>OriginAuthenticationMethod defines authentication method/params for origin
authentication. Origin could be end-user, device, delegate service etc.
Currently, only JWT is supported for origin authentication.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="OriginAuthenticationMethod-jwt">
<td><code>jwt</code></td>
<td><code><a href="#Jwt">Jwt</a></code></td>
<td>
<p>Jwt params for the method.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="PeerAuthenticationMethod">PeerAuthenticationMethod</h2>
<section>
<p>PeerAuthenticationMethod defines one particular type of authentication, e.g
mutual TLS, JWT etc, (no authentication is one type by itself) that can
be used for peer authentication.
The type can be progammatically determine by checking the type of the
&ldquo;params&rdquo; field.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="PeerAuthenticationMethod-mtls" class="oneof oneof-start">
<td><code>mtls</code></td>
<td><code><a href="#MutualTls">MutualTls (oneof)</a></code></td>
<td>
<p>Set if mTLS is used.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="Policy">Policy</h2>
<section>
<p>Policy defines what authentication methods can be accepted on workload(s),
and if authenticated, which method/certificate will set the request principal
(i.e request.auth.principal attribute).</p>

<p>Authentication policy is composed of 2-part authentication:
- peer: verify caller service credentials. This part will set source.user
(peer identity).
- origin: verify the origin credentials. This part will set request.auth.user
(origin identity), as well as other attributes like request.auth.presenter,
request.auth.audiences and raw claims. Note that the identity could be
end-user, service account, device etc.</p>

<p>Last but not least, the principal binding rule defines which identity (peer
or origin) should be used as principal. By default, it uses peer.</p>

<p>Examples:</p>

<p>Policy to enable mTLS for all services in namespace frod</p>

<pre><code class="language-yaml">apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
  name: mTLS_enable
  namespace: frod
spec:
  peers:
  - mtls:
</code></pre>

<p>Policy to disable mTLS for &ldquo;productpage&rdquo; service</p>

<pre><code class="language-yaml">apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
  name: mTLS_disable
  namespace: frod
spec:
  targets:
  - name: productpage
</code></pre>

<p>Policy to require mTLS for peer authentication, and JWT for origin authentication
for productpage:9000 except the path &lsquo;/health_check&rsquo; . Principal is set from origin identity.</p>

<pre><code class="language-yaml">apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
  name: mTLS_enable
  namespace: frod
spec:
  target:
  - name: productpage
    ports:
    - number: 9000
  peers:
  - mtls:
  origins:
  - jwt:
      issuer: &quot;https://securetoken.google.com&quot;
      audiences:
      - &quot;productpage&quot;
      jwksUri: &quot;https://www.googleapis.com/oauth2/v1/certs&quot;
      jwt_headers:
      - &quot;x-goog-iap-jwt-assertion&quot;
      trigger_rules:
      - excluded_paths:
        - exact: /health_check
  principalBinding: USE_ORIGIN
</code></pre>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="Policy-targets">
<td><code>targets</code></td>
<td><code><a href="#TargetSelector">TargetSelector[]</a></code></td>
<td>
<p>List rules to select destinations that the policy should be applied on.
If empty, policy will be used on all destinations in the same namespace.</p>

</td>
</tr>
<tr id="Policy-peers">
<td><code>peers</code></td>
<td><code><a href="#PeerAuthenticationMethod">PeerAuthenticationMethod[]</a></code></td>
<td>
<p>List of authentication methods that can be used for peer authentication.
They will be evaluated in order; the first validate one will be used to
set peer identity (source.user) and other peer attributes. If none of
these methods pass, request will be rejected with authentication failed error (401).
Leave the list empty if peer authentication is not required</p>

</td>
</tr>
<tr id="Policy-origins">
<td><code>origins</code></td>
<td><code><a href="#OriginAuthenticationMethod">OriginAuthenticationMethod[]</a></code></td>
<td>
<p>List of authentication methods that can be used for origin authentication.
Similar to peers, these will be evaluated in order; the first validate one
will be used to set origin identity and attributes (i.e request.auth.user,
request.auth.issuer etc). If none of these methods pass, request will be
rejected with authentication failed error (401).
A method may be skipped, depends on its trigger rule. If all of these methods
are skipped, origin authentication will be ignored, as if it is not defined.
Leave the list empty if origin authentication is not required.</p>

</td>
</tr>
<tr id="Policy-principal_binding">
<td><code>principalBinding</code></td>
<td><code><a href="#PrincipalBinding">PrincipalBinding</a></code></td>
<td>
<p>Define whether peer or origin identity should be use for principal. Default
value is USE_PEER.
If peer (or origin) identity is not available, either because of peer/origin
authentication is not defined, or failed, principal will be left unset.
In other words, binding rule does not affect the decision to accept or
reject request.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="PortSelector">PortSelector</h2>
<section>
<p>PortSelector specifies the name or number of a port to be used for
matching targets for authentication policy. This is copied from
networking API to avoid dependency.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="PortSelector-number" class="oneof oneof-start">
<td><code>number</code></td>
<td><code>uint32 (oneof)</code></td>
<td>
<p>Valid port number</p>

</td>
</tr>
<tr id="PortSelector-name" class="oneof">
<td><code>name</code></td>
<td><code>string (oneof)</code></td>
<td>
<p>Port name</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="PrincipalBinding">PrincipalBinding</h2>
<section>
<p>Associates authentication with request principal.</p>

<table class="enum-values">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="PrincipalBinding-USE_PEER">
<td><code>USE_PEER</code></td>
<td>
<p>Principal will be set to the identity from peer authentication.</p>

</td>
</tr>
<tr id="PrincipalBinding-USE_ORIGIN">
<td><code>USE_ORIGIN</code></td>
<td>
<p>Principal will be set to the identity from origin authentication.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="StringMatch">StringMatch</h2>
<section>
<p>Describes how to match a given string. Match is case-sensitive.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="StringMatch-exact" class="oneof oneof-start">
<td><code>exact</code></td>
<td><code>string (oneof)</code></td>
<td>
<p>exact string match.</p>

</td>
</tr>
<tr id="StringMatch-prefix" class="oneof">
<td><code>prefix</code></td>
<td><code>string (oneof)</code></td>
<td>
<p>prefix-based match.</p>

</td>
</tr>
<tr id="StringMatch-suffix" class="oneof">
<td><code>suffix</code></td>
<td><code>string (oneof)</code></td>
<td>
<p>suffix-based match.</p>

</td>
</tr>
<tr id="StringMatch-regex" class="oneof">
<td><code>regex</code></td>
<td><code>string (oneof)</code></td>
<td>
<p>ECMAscript style regex-based match as defined by <a href="http://en.cppreference.com/w/cpp/regex/ecmascript">EDCA-262</a>.
Example: &ldquo;^/pets/(.*?)?&rdquo;</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="TargetSelector">TargetSelector</h2>
<section>
<p>TargetSelector defines a matching rule to a service/destination.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="TargetSelector-name">
<td><code>name</code></td>
<td><code>string</code></td>
<td>
<p>REQUIRED. The name must be a short name from the service registry. The
fully qualified domain name will be resolved in a platform specific manner.</p>

</td>
</tr>
<tr id="TargetSelector-ports">
<td><code>ports</code></td>
<td><code><a href="#PortSelector">PortSelector[]</a></code></td>
<td>
<p>Specifies the ports on the destination. Leave empty to match all ports
that are exposed.</p>

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