mirror of https://github.com/istio/istio.io.git
Add new security reference docs (#6755)
This commit is contained in:
Frank Budinsky
GitHub
parent
b54ad1d36f
commit
3f9e5a0e6c
|
|
@ -0,0 +1,227 @@
|
|||
---
|
||||
WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE 'https://github.com/istio/api' REPO
|
||||
source_repo: https://github.com/istio/api
|
||||
title: JWTRule
|
||||
description: Configuration to validate JWT.
|
||||
location: https://istio.io/docs/reference/config/security/jwt.html
|
||||
layout: protoc-gen-docs
|
||||
generator: protoc-gen-docs
|
||||
schema: istio.security.v1beta1.JWTRule
|
||||
aliases: [/docs/reference/config/security/v1beta1/jwt]
|
||||
number_of_entries: 2
|
||||
---
|
||||
<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>Type</th>
|
||||
<th>Description</th>
|
||||
<th>Required</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr id="JWTHeader-name">
|
||||
<td><code>name</code></td>
|
||||
<td><code>string</code></td>
|
||||
<td>
|
||||
<p>The HTTP header name.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
Yes
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTHeader-prefix">
|
||||
<td><code>prefix</code></td>
|
||||
<td><code>string</code></td>
|
||||
<td>
|
||||
<p>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 considerred invalid.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</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 followwing 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 token in 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
|
||||
jwtHeaders:
|
||||
- "x-goog-iap-jwt-assertion"
|
||||
</code></pre>
|
||||
|
||||
<table class="message-fields">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
<th>Required</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr id="JWTRule-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>
|
||||
A JWT with different <code>iss</code> claim will be rejected.</p>
|
||||
|
||||
<p>Example: https://foobar.auth0.com
|
||||
Example: 1234567-compute@developer.gserviceaccount.com</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
Yes
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTRule-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.example.com
|
||||
bookstore_web.apps.example.com
|
||||
</code></pre>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTRule-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: <code>https://www.googleapis.com/oauth2/v1/certs</code></p>
|
||||
|
||||
<p>Note: Only one of jwks<em>uri and jwks should be used. jwks</em>uri will be ignored if it does.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTRule-jwks">
|
||||
<td><code>jwks</code></td>
|
||||
<td><code>string</code></td>
|
||||
<td>
|
||||
<p>JSON Web Key Set of public keys to validate signature of the JWT.
|
||||
See https://auth0.com/docs/jwks.</p>
|
||||
|
||||
<p>Note: Only one of jwks<em>uri and jwks should be used. jwks</em>uri will be ignored if it does.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTRule-from_headers">
|
||||
<td><code>fromHeaders</code></td>
|
||||
<td><code><a href="#JWTHeader">JWTHeader[]</a></code></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 “Bearer ” prefix:</p>
|
||||
|
||||
<pre><code> fromHeaders:
|
||||
- name: x-jwt-assertion
|
||||
prefix: "Bearer "
|
||||
</code></pre>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTRule-from_params">
|
||||
<td><code>fromParams</code></td>
|
||||
<td><code>string[]</code></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 /path?my_token=<JWT>), the config is:</p>
|
||||
|
||||
<pre><code> fromParams:
|
||||
- "my_token"
|
||||
</code></pre>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTRule-output_payload_to_header">
|
||||
<td><code>outputPayloadToHeader</code></td>
|
||||
<td><code>string</code></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>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="JWTRule-forward_original_token">
|
||||
<td><code>forwardOriginalToken</code></td>
|
||||
<td><code>bool</code></td>
|
||||
<td>
|
||||
<p>If set to true, the orginal token will be kept for the ustream request. Default is false.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,211 @@
|
|||
---
|
||||
WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE 'https://github.com/istio/api' REPO
|
||||
source_repo: https://github.com/istio/api
|
||||
title: PeerAuthentication
|
||||
description: Peer authentication configuration for workloads.
|
||||
location: https://istio.io/docs/reference/config/security/peer_authentication.html
|
||||
layout: protoc-gen-docs
|
||||
generator: protoc-gen-docs
|
||||
schema: istio.security.v1beta1.PeerAuthentication
|
||||
aliases: [/docs/reference/config/security/v1beta1/peer_authentication]
|
||||
number_of_entries: 3
|
||||
---
|
||||
<h2 id="PeerAuthentication">PeerAuthentication</h2>
|
||||
<section>
|
||||
<p>PeerAuthentication defines how traffic will be tunneled (or not) to the sidecar.</p>
|
||||
|
||||
<p>Examples:</p>
|
||||
|
||||
<p>Policy to allow mTLS traffic for all workloads under namespace <code>foo</code>:</p>
|
||||
|
||||
<pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
|
||||
kind: PeerAuthentication
|
||||
metadata:
|
||||
name: default
|
||||
namespace: foo
|
||||
spec:
|
||||
mtls:
|
||||
mode: STRICT
|
||||
</code></pre>
|
||||
|
||||
<p>For mesh level, put the policy in root-namespace according to your Istio installation.</p>
|
||||
|
||||
<p>Policies to allow both mTLS & plaintext traffic for all workloads under namespace <code>foo</code>, but
|
||||
require mTLS for workload <code>finance</code>.</p>
|
||||
|
||||
<pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
|
||||
kind: PeerAuthentication
|
||||
metadata:
|
||||
name: default
|
||||
namespace: foo
|
||||
spec:
|
||||
mtls:
|
||||
mode: PERMISSIVE
|
||||
---
|
||||
apiVersion: security.istio.io/v1beta1
|
||||
kind: PeerAuthentication
|
||||
metadata:
|
||||
name: default
|
||||
namespace: foo
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: finance
|
||||
mtls:
|
||||
mode: STRICT
|
||||
</code></pre>
|
||||
|
||||
<p>Policy to allow mTLS strict for all workloads, but leave port 8080 to
|
||||
plaintext:</p>
|
||||
|
||||
<pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
|
||||
kind: PeerAuthentication
|
||||
metadata:
|
||||
name: default
|
||||
namespace: foo
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: finance
|
||||
mtls:
|
||||
mode: STRICT
|
||||
portLevelMtls:
|
||||
8080:
|
||||
mode: DISABLE
|
||||
</code></pre>
|
||||
|
||||
<p>Policy to inherite mTLS mode from namespace (or mesh) settings, and overwrite
|
||||
settings for port 8080</p>
|
||||
|
||||
<pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
|
||||
kind: PeerAuthentication
|
||||
metadata:
|
||||
name: default
|
||||
namespace: foo
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: finance
|
||||
mtls:
|
||||
mode: UNSET
|
||||
portLevelMtls:
|
||||
8080:
|
||||
mode: DISABLE
|
||||
</code></pre>
|
||||
|
||||
<table class="message-fields">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
<th>Required</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr id="PeerAuthentication-selector">
|
||||
<td><code>selector</code></td>
|
||||
<td><code><a href="/docs/reference/config/type/v1beta1/workload-selector.html#WorkloadSelector">WorkloadSelector</a></code></td>
|
||||
<td>
|
||||
<p>The selector determines the workloads to apply the ChannelAuthentication on.
|
||||
If not set, the policy will be applied to all workloads in the same namespace as the policy.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="PeerAuthentication-mtls">
|
||||
<td><code>mtls</code></td>
|
||||
<td><code><a href="#PeerAuthentication-MutualTLS">MutualTLS</a></code></td>
|
||||
<td>
|
||||
<p>Mutual TLS settings for workload. If not defined, inherit from parent.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="PeerAuthentication-port_level_mtls">
|
||||
<td><code>portLevelMtls</code></td>
|
||||
<td><code>map<uint32, <a href="#PeerAuthentication-MutualTLS">MutualTLS</a>></code></td>
|
||||
<td>
|
||||
<p>Port specific mutual TLS settings.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
<h2 id="PeerAuthentication-MutualTLS">PeerAuthentication.MutualTLS</h2>
|
||||
<section>
|
||||
<p>Mutual TLS settings.</p>
|
||||
|
||||
<table class="message-fields">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
<th>Required</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr id="PeerAuthentication-MutualTLS-mode">
|
||||
<td><code>mode</code></td>
|
||||
<td><code><a href="#PeerAuthentication-MutualTLS-Mode">Mode</a></code></td>
|
||||
<td>
|
||||
<p>Defines the mTLS mode used for peer authentication.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
<h2 id="PeerAuthentication-MutualTLS-Mode">PeerAuthentication.MutualTLS.Mode</h2>
|
||||
<section>
|
||||
<table class="enum-values">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr id="PeerAuthentication-MutualTLS-Mode-UNSET">
|
||||
<td><code>UNSET</code></td>
|
||||
<td>
|
||||
<p>Inherit from parent, if has one. Otherwise treated as PERMISSIVE.</p>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="PeerAuthentication-MutualTLS-Mode-DISABLE">
|
||||
<td><code>DISABLE</code></td>
|
||||
<td>
|
||||
<p>Connection is not tunneled.</p>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="PeerAuthentication-MutualTLS-Mode-PERMISSIVE">
|
||||
<td><code>PERMISSIVE</code></td>
|
||||
<td>
|
||||
<p>Connection can be either plaintext or mTLS tunnel.</p>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="PeerAuthentication-MutualTLS-Mode-STRICT">
|
||||
<td><code>STRICT</code></td>
|
||||
<td>
|
||||
<p>Connection is an mTLS tunnel (TLS with client cert must be presented).</p>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,159 @@
|
|||
---
|
||||
WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE 'https://github.com/istio/api' REPO
|
||||
source_repo: https://github.com/istio/api
|
||||
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]
|
||||
number_of_entries: 1
|
||||
---
|
||||
<h2 id="RequestAuthentication">RequestAuthentication</h2>
|
||||
<section>
|
||||
<p>RequestAuthentication defines what request authentication methods are supported by a workload.
|
||||
If 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>
|
||||
|
||||
<ul>
|
||||
<li>Require JWT for all request for workloads that have label <code>app:httpbin</code></li>
|
||||
</ul>
|
||||
|
||||
<pre><code class="language-yaml">apiVersion: security.istio.io/v1beta1
|
||||
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/v1beta1
|
||||
kind: AuthorizationPolicy
|
||||
metadata:
|
||||
name: httpbin
|
||||
namespace: foo
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: httpbin
|
||||
rules:
|
||||
- from:
|
||||
- source:
|
||||
requestPrincipals: ["*"]
|
||||
</code></pre>
|
||||
|
||||
<ul>
|
||||
<li>The next example shows how to set a different JWT requirement for a different <code>host</code>. The <code>RequestAuthentication</code>
|
||||
declares it can accpet JWTs issuer by either <code>issuer-foo</code> or <code>issuer-bar</code> (the public key set is implicitly
|
||||
set from the OpenID Connect spec).
|
||||
“`yaml
|
||||
apiVersion: security.istio.io/v1beta1
|
||||
kind: RequestAuthentication
|
||||
metadata:
|
||||
name: httpbin
|
||||
namespace: foo
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: httpbin
|
||||
jwtRules:
|
||||
|
||||
<ul>
|
||||
<li>issuer: “issuer-foo”</li>
|
||||
<li>issuer: “issuer-bar”
|
||||
—
|
||||
apiVersion: security.istio.io/v1beta1
|
||||
kind: AuthorizationPolicy
|
||||
metadata:
|
||||
name: httpbin
|
||||
namespace: foo
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: httpbin
|
||||
rules:</li>
|
||||
<li>from:</li>
|
||||
<li>source:
|
||||
requestPrincipals: [“issuer-foo/*”]
|
||||
to:
|
||||
hosts: [“example.com”]</li>
|
||||
<li>from:</li>
|
||||
<li>source:
|
||||
requestPrincipals: [“issuer-bar/<em>”]
|
||||
to:
|
||||
hosts: [“another-host.com”]
|
||||
<code>
|
||||
- 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:
|
||||
</code>yaml
|
||||
apiVersion: security.istio.io/v1beta1
|
||||
kind: AuthorizationPolicy
|
||||
metadata:
|
||||
name: httpbin
|
||||
namespace: foo
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: httpbin
|
||||
rules:
|
||||
- from:
|
||||
- source:
|
||||
requestPrincipals: [”</em>”]
|
||||
- to:
|
||||
- operation:
|
||||
paths: [“/healthz]
|
||||
“`</li>
|
||||
</ul></li>
|
||||
</ul>
|
||||
|
||||
<table class="message-fields">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Type</th>
|
||||
<th>Description</th>
|
||||
<th>Required</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr id="RequestAuthentication-selector">
|
||||
<td><code>selector</code></td>
|
||||
<td><code><a href="/docs/reference/config/type/v1beta1/workload-selector.html#WorkloadSelector">WorkloadSelector</a></code></td>
|
||||
<td>
|
||||
<p>The selector determines the workloads to apply the RequestAuthentication on.
|
||||
If not set, the policy will be applied to all workloads in the same namespace as the policy.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="RequestAuthentication-jwt_rules">
|
||||
<td><code>jwtRules</code></td>
|
||||
<td><code><a href="/docs/reference/config/security/jwt.html#JWTRule">JWTRule[]</a></code></td>
|
||||
<td>
|
||||
<p>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 recorgnized by the
|
||||
rule. The token will be validated based on the JWT rule config. If validation fails, the request will
|
||||
be rejected.
|
||||
Note: if more than one token is presented (at different locations), the output principal is nondeterministic.</p>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
No
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
Loading…
Reference in New Issue