:original_name: asm_01_0096.html

.. _asm_01_0096:

JWT Authentication Principles
=============================


JWT Authentication Principles
-----------------------------

JWT is an authentication mode in which the server issues tokens to the client. When a user logs in to the client using the username and password, the server generates and returns a token to the client. The client only needs to carry the token when sending a request to the server. The server verifies the token to determine whether the request is from a valid client and determines whether to return a response to the client. This method, which connects authenticated clients based on tokens in requests, solves various stateful problems of storing sessions on a server at an early stage.

In Istio, the JWT token is generated by a specific authentication service and verified by meshes, completely decoupling the authentication logic in user services and enabling applications to focus on their own services. :ref:`Figure 1 <asm_01_0096__fig184171654514>` shows the complete Istio-based JWT mechanism.

.. _asm_01_0096__fig184171654514:

.. figure:: /_static/images/en-us_image_0000001477127516.png
   :alt: **Figure 1** Istio JWT authentication process

   **Figure 1** Istio JWT authentication process

1. The client connects the authentication service by logging with the user name and password.

2. The authentication service verifies the username and password, generates a JWT token (including the user ID and expiration time), and signs the token with the private key of the authentication service.

3. The authentication service returns the JWT token to the client.

4. The client stores the JWT token locally for subsequent requests.

5. When requesting to another service, the client carries the JWT token and does not need to provide information such as the username and password.

6. The mesh data plane proxy intercepts the traffic and verifies the JWT token using the configured public key.

7. Once the JWT token is verified, the mesh proxy forwards the request to the server.

8. The server processes the request.

9. The server returns the response data to the mesh proxy.

10. The mesh data plane proxy forwards the response data to the caller.

The step 6 is important because the JWT authentication function is migrated from the server to the mesh proxy. The mesh data plane obtains, from the authentication policy configured by the control plane, the public key for verifying the JWT token. The public key may be one configured on the JWKS (JSON Web Key Set) or one obtained from a public key address configured by jwksUri. After obtaining the public key, the mesh proxy uses it to verify the token signed by the private key of the authentication service, decrypts the **iss** in the token, and verifies whether the issuer information in the authentication policy is matched. If the verification is successful, the request is sent to the application. If not, the request is rejected.

JWT Structure
-------------

JWT is of the JSON structure that contains specific declarations. Step 6 of the JWT authentication process shows the request identity can be confirmed by verifying the JSON structure. Querying the backend service is not needed. The following shows how the authentication information is carried by parsing the JWT structure.

A JWT token consists of three parts: header, payload, and signature.

-  Header

   Describes the JWT metadata, including the algorithm **alg** and type **typ**. **alg** describes the signature algorithm so that the receiver can verify the signature based on the corresponding algorithm. The default algorithm is **HS256** (as follows), indicating **HMAC-SHA256**. **typ** indicates the token type. If **typ** is **JWT**, indicating that the token is of the JWT type.

   .. code-block::

      {
        "alg": "HS256",
        "typ": "JWT"
      }

-  Payload

   Stores the main content of the token. The authentication service AuthN generates related information and places the information in the token payload. The attributes of **payload** include:

   -  **iss**: token issuer
   -  **aud**: token audience

   During JWT verification, the **iss** and **aud** will be verified to check whether they are matched with the token issuer and audience. The JWT content is not encrypted. All services that obtain the token can view the content in the token payload. You are advised not to store private information in the payload.

-  Signature

   Signature of the header and payload, ensuring that only the specific legitimate authentication services can issue tokens. Generally, the header and payload are converted into strings using Base64, and then the private key of the authentication service is used to sign the strings. The signature algorithm is the **alg** defined in the header.

The following is a complete JWT example. Signature is obtained by signing the header and payload.

.. code-block::

   # Header:
   {
     "alg": "RS512",
     "typ": "JWT"
   }

   # Payload
   {
     "iss": "weather@cloudnative-istio",
     "audience": "weather@cloudnative-istio"
   }

   # Signature
   RSASHA512(
     base64UrlEncode(header) + "." +
     base64UrlEncode(payload)
     )

The token output of the preceding structure is as follows. The three strings separated by periods (.) correspond to the header, payload, and signature of the JWT structure, respectively.

.. code-block::

   eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjQ2ODU5ODk3MDAsInZlciI6IjIuMCIsImlhdCI6MTUzMjM4OTcwMCwiaXNzIjoid2VhdGhlckBjbG91ZG5hdGl2ZS1pc3Rpby5ib29rIiwic3ViIjoid2VhdGhlckBjbG91ZG5hdGl2ZS1pc3Rpby5ib29rIn0.SEp-8qiMwI45BuBgQPH-wTHvOYxcE_jPI0wqOxEpauw
