mirror of https://github.com/istio/istio.io.git
516 lines
14 KiB
HTML
516 lines
14 KiB
HTML
---
|
|
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: 9
|
|
---
|
|
<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>Example,</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>
|
|
|
|
<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’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>
|
|
</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
|
|
“params” 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 “productpage” 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 authenticationn
|
|
for productpage:9000. 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: "https://securetoken.google.com"
|
|
audiences:
|
|
- "productpage"
|
|
jwksUri: "https://www.googleapis.com/oauth2/v1/certs"
|
|
jwt_headers:
|
|
- "x-goog-iap-jwt-assertion"
|
|
principaBinding: USE_ORIGIN
|
|
</code></pre>
|
|
|
|
<p>Policy to require mTLS for peer authentication, and JWT for origin authenticationn
|
|
for productpage:9000, but allow origin authentication failed. Principal is set
|
|
from origin identity.
|
|
Note: this example can be used for use cases when we want to allow request from
|
|
certain peers, given it comes with an approperiate authorization poicy to check
|
|
and reject request accoridingly.</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: "https://securetoken.google.com"
|
|
audiences:
|
|
- "productpage"
|
|
jwksUri: "https://www.googleapis.com/oauth2/v1/certs"
|
|
jwt_headers:
|
|
- "x-goog-iap-jwt-assertion"
|
|
originIsOptional: true
|
|
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, and peer<em>is</em>optional flag is false (see below),
|
|
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-peer_is_optional">
|
|
<td><code>peerIsOptional</code></td>
|
|
<td><code>bool</code></td>
|
|
<td>
|
|
<p>Set this flag to true to accept request (for peer authentication perspective),
|
|
even when none of the peer authentication methods defined above satisfied.
|
|
Typically, this is used to delay the rejection decision to next layer (e.g
|
|
authorization).
|
|
This flag is ignored if no authentication defined for peer (peers field is empty).</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, and origin<em>is</em>optional
|
|
is false (see below), request will be rejected with authentication failed
|
|
error (401).
|
|
Leave the list empty if origin authentication is not required.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="Policy-origin_is_optional">
|
|
<td><code>originIsOptional</code></td>
|
|
<td><code>bool</code></td>
|
|
<td>
|
|
<p>Set this flag to true to accept request (for origin authentication perspective),
|
|
even when none of the origin authentication methods defined above satisfied.
|
|
Typically, this is used to delay the rejection decision to next layer (e.g
|
|
authorization).
|
|
This flag is ignored if no authentication defined for origin (origins field is empty).</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 orgin) 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 authenticationn 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="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>
|