mirror of https://github.com/istio/istio.io.git
279 lines
8.0 KiB
HTML
279 lines
8.0 KiB
HTML
---
|
|
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: 3
|
|
---
|
|
<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:
|
|
- "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: <code>https://foobar.auth0.com</code>
|
|
Example: <code>1234567-compute@developer.gserviceaccount.com</code></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 <code>jwksUri</code> and <code>jwks</code> should be used.</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 <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>
|
|
<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 <code>Bearer</code> prefix:</p>
|
|
<pre><code class="language-yaml"> fromHeaders:
|
|
- name: x-jwt-assertion
|
|
prefix: "Bearer "
|
|
</code></pre>
|
|
<p>Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
|
|
such requests is undefined.</p>
|
|
|
|
</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 <code>/path?my_token=<JWT></code>), the config is:</p>
|
|
<pre><code class="language-yaml"> fromParams:
|
|
- "my_token"
|
|
</code></pre>
|
|
<p>Note: Requests with multiple tokens (at different locations) are not supported, the output principal of
|
|
such requests is undefined.</p>
|
|
|
|
</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 original token will be kept for the upstream request. Default is false.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="JWTRule-output_claim_to_headers">
|
|
<td><code>outputClaimToHeaders</code></td>
|
|
<td><code><a href="#ClaimToHeader">ClaimToHeader[]</a></code></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>
|
|
<td>
|
|
No
|
|
</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>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 <code>Authorization: Bearer <token></code>, prefix=<code>Bearer</code> with a space at the end.
|
|
If the header doesn’t have this exact prefix, it is considered invalid.</p>
|
|
|
|
</td>
|
|
<td>
|
|
No
|
|
</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>Type</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="ClaimToHeader-header">
|
|
<td><code>header</code></td>
|
|
<td><code>string</code></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>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
<tr id="ClaimToHeader-claim">
|
|
<td><code>claim</code></td>
|
|
<td><code>string</code></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>
|
|
<td>
|
|
No
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|