Configure JWT authentication for an HTTP trigger - Function Compute

This topic describes the process of JSON Web Tokens (JWT) authentication and how to configure JWT authentication for an HTTP trigger in the Function Compute console.

Background

Function Compute allows you to enable JWT authentication for HTTP triggers. JWT is an open standard (RFC: 7519) that defines how to authenticate requests based on tokens. User status information is stored in tokens provided by clients. Functions or servers do not store tokens. Therefore, this method is particularly suitable for serverless applications. Function Compute can use the public JSON Web Key Set (JWKS) that is configured for an HTTP trigger to implement JWT authentication on HTTP requests. Function Compute forwards claims to functions based on the configurations of the HTTP trigger. This way, request authentication is not required in functions. You can focus on business logic. For more information about the authentication process and basic information about tokens in JWT, see JWT-based authentication and Introduction to JSON Web Tokens.

Usage notes

You can generate and distribute JWTs based on your business requirements. Function Compute authenticates the JWTs by using the public JWKS configured for triggers.
A JSON Web Key (JWK) without kid is supported.
You can configure multiple JWKs for a trigger.
A token can be read from a header, query (by using the GET method), form (by using the POST method), or cookie parameter.
You can forward claims as headers, queries (by using the GET method), forms (by using the POST method), or cookies to functions.

Important

We recommend that you use HTTPS to protect sensitive information such as tokens in requests to prevent token leaks.

JWT authentication process

The preceding figure shows the workflow of JWT authentication for HTTP triggers in Function Compute. In the process, an asymmetric encryption algorithm is used. The following information describes the process details.

The client sends an authentication request to a custom authorizer. In most cases, the username and password of a user are specified in the request.
The custom authorizer reads and verifies authentication information, such as the username and password of the user, in the request. After the request passes authentication, the authorizer uses a private key to generate a standard token.
The custom authorizer forwards the response that contains the token to the client. The client caches the token to an on-premises machine.
The client sends a business request that contains token to the HTTP trigger.
The HTTP trigger uses the configured public key to verify the token in the request.
After the verification succeeds, the request is passed to the protected function.
The protected function processes and responds to the request.
The HTTP trigger forwards the business response to the client.

Prerequisites

A service is created. For more information, see Manage services.
An HTTP function is created. For more information, see the "Create a function" section of the Manage functions topic.

Procedure

Log on to the Function Compute console. In the left-side navigation pane, click Services & Functions.
In the top navigation bar, select a region. On the Services page, click the desired service.
On the Functions page, click the name of the desired function. On the Function Details page that appears, click the Trigger Management (URL) tab.
On the Trigger Management (URL) tab, click Modify in the Actions column of the HTTP trigger.
In the Modify Trigger panel, configure the following parameters and click OK.
1. Set Authentication Method to JWT Authentication.
2. Configure JWKS.
  To configure JWT authentication for the HTTP trigger, you must provide a valid JWKS. You can prepare a JWKS on your own, or search for JSON Web Key generator in a web browser to obtain an online generator, such as mkjwk.org. If you have a key in the Privacy Enhanced Mail (PEM) format, you can use a tool such as jwx to convert the key to the JWKS format.
  The following sample code provides an example of a JWKS:
```
{
    "keys": [
        {
            "alg": "RS256",
            "e": "AQAB",
            "kty": "RSA",
            "n": "u1LWgoomekdOMfB1lEe96OHehd4XRNCbZRm96RqwOYTTc28Sc_U5wKV2umDzolfoI682ct2BNnRRahYgZPhbOCzHYM6i8sRXjz9Ghx3QHw9zrYACtArwQxrTFiejbfzDPGdPrMQg7T8wjtLtkSyDmCzeXpbIdwmxuLyt_ahLfHelr94kEksMDa42V4Fi5bMW4cCLjlEKzBEHGmFdT8UbLPCvpgsM84JK63e5ifdeI9NdadbC8ZMiR--dFCujT7AgRRyMzxgdn2l-nZJ2ZaYzbLUtAW5_U2kfRVkDNa8d1g__2V5zjU6nfLJ1S2MoXMgRgDPeHpEehZVu2kNaSFvDUQ",
            "use": "sig"
        }
    ]
}
```
  You can configure a JWKS for an HTTP trigger. After the JWKS is configured, the public JWK that is similar to the kid in the token is searched and used to verify the signature. You can leave at most one kid of a JWK unspecified or set kid to an empty string.
  The following table lists the algorithms that are supported by the JWT of Function Compute.
  Signature algorithm
  alg value
  RSASSA-PKCS1-V1_5
  RS256, RS384, or RS512
  RSASSA-PSS
  PS256, PS384, or PS512
  Elliptic Curve (ECDSA)
  ES256, ES384, or ES512
  HMAC
  HS256, HS384, or HS512
  EdDSA
  EdDSA
  Important
  The hash-based message authentication code (HMAC) signature algorithm uses symmetric encryption. This encryption is less secure. We recommend that you use an asymmetric encryption algorithm to improve security.
  When you use an asymmetric encryption algorithm, you need to include information only about public keys, instead of private keys in your JWT for security purposes.
3. In the JWT Token Configuration section, select the position to read the token and the name of the token.
  You can set the Read Position parameter of the token to Header, Cookie, Query Parameters, or Form Parameters. If you set the Read Position parameter of token to Header, you must specify a prefix that you want to remove when Function Compute obtains tokens.
4. In the JWT Claim Conversion section, select the position to pass parameters to the function, the original name of the parameter, and the new name of the parameter after it is passed to the function.
  You can set the Mapping Parameter Position parameter to Header, Cookie, Query Parameters, or Form Parameters.
5. Set the request matching mode.
  - Match All: All HTTP requests must be verified by using JWT.
  - Whitelist Mode: HTTP requests that are sent from the paths specified in Whitelist of Request Paths are not verified by using JWT. Other requests are verified by using JWT.
  - Blacklist Mode: HTTP requests that are sent from the paths specified in Blacklist of Request Paths are verified by using JWT. Other requests are not verified by using JWT.
  Whitelist Mode and Blacklist Mode support the following matching modes:
  - Exact match
    A path is matched only if it is exactly the same as the specified path. For example, if you set the Blacklist of Request Paths parameter to /a, JWT verification is required for requests that are sent from /a. JWT verification is not required for requests that are sent from /a/.
  - Fuzzy match
    You can set the value to a path that is appended with an asterisk wildcard (*). For example, if you set the Blacklist of Request Paths parameter to /login/*, requests that are sent from the paths prefixed with /login/, such as /login/a and /login/b/c/d, are verified by using JWT.

Verify the result

You can enter the endpoint and token based on the JWT configuration of the HTTP trigger to check whether the trigger can be accessed in the test tool. Postman is used as an example in this topic, as shown in the following figure.

jwt-auth-result

The content labeled with 1 is the public URL of the trigger. You can view the URL on the Trigger Management (URL) tab of the function.

The content labeled with 2 is the parameter name and token in JWT Token Configuration. Example token:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9uIFNub3ciLCJhZG1pbiI6dHJ1ZSwiZXhwIjo0ODI5NTk3NjQxfQ.eRcobbpjAd3OSMxcWbmbicOTLjO2vuLR9F2QZMK4rz1JqfSRHgwQVqNxcfOIO9ckDMNlF_3jtdfCfvXfka-phJZpHmnaQJxmnOA8zA3R4wF4GUQdz5zkt74cK9jLAXpokwrviz2ROehwxTCwa0naRd_N9eFhvTRnP3u7L0xn3ll4iOf8Q4jS0mVLpjyTa5WiBkN5xi9hkFxd__p98Pah_Yf0hVQ2ldGSyTtAMmdM1Bvzad-kdZ_wW0jcctIla9bLnOo-Enr14EsGvziMh_QTZ3HQtJuToSKZ11xkNgaz7an5de6PuF5ISXQzxigpFVIkG765aEDVtEnFkMO0xyPGLg

The content labeled with 3 is the name of the parameter after the claim is passed to the function.

Use JWT authentication with a custom domain name

The preceding figure shows that a custom domain name processes user requests before an HTTP trigger processes the requests. JWT authentication is performed on the HTTP trigger. This section describes how to use JWT authentication in scenarios in which custom domain names are configured.

Custom domain names with no rewrite policies configured

If routes are configured for the custom domain name and no rewrite policy is configured, the paths of the incoming HTTP requests are the paths of the custom domain names.

For example, the following table describes the route rule for the custom domain name www.fc-jwt.com. The Blacklist of Request Paths in the JWT configuration of the HTTP trigger for the jwt-demo function is /fc-jwt/auth/*.

Path	Service	Function	Version
/fc-jwt/*	jwt	jwt-demo	1

If the URL of a request is /fc-jwt/auth/aliyun, the HTTP trigger verifies the request because the path of the request matches the setting of Blacklist of Request Paths.

Custom domain names with rewrite policies configured

If routes are configured for the custom domain name and a rewrite policy is configured, the paths of the incoming HTTP requests are rewritten URLs. For more information about the rewrite feature for custom domain names, see Configure rewrite policies (in public review).

For example, the following table describes the route rules for the custom domain name www.fc-jwt.com. In the JWT configuration of the HTTP trigger for the jwt-demo function, the Blacklist of Request Paths parameter is set to /fc-jwt/auth/*, and a wildcard rewrite policy is configured. The match rule is /fc-jwt/*, and the replacement rule is /$1.

Path	Service	Function	Version
/fc-jwt/*	jwt	jwt-demo	1

If the URL of a request is /fc-jwt/auth/aliyun, the rewritten URL is /auth/aliyun. For more information about wildcard rewrite rules, see Configure rewrite policies (in public review). The HTTP trigger does not verify the request. In this case, the path of the request to the HTTP trigger is /auth/aliyun and does not match the Blacklist of Request Paths setting.

If you set the Request Path Blacklist parameter to /auth/*, the HTTP trigger performs JWT authentication on the request whose URL is /fc-jwt/auth/aliyun.

Troubleshooting

Why is the "invalid or expired jwt" message reported after I enable JWT authentication for an HTTP trigger?

This message indicates that JWT authentication fails. The following items list the possible causes:

The signature or format of your token is invalid, which results in an authentication error.
Your token has expired, which causes an authentication error.
The kid in your token does not match the JWKS configurations of the trigger, or the matched JWK is inaccurate and the token cannot be correctly verified.

Why is "the jwt token is missing" reported after I enable JWT authentication for an HTTP trigger?

This message indicates that Function Compute cannot find the token based on the JWT configuration. Check whether the request contains the token, and whether the position and name of the token are correct.

Does JWT authentication incur additional fees?

No, no additional fees are incurred when you use JWT authentication. By default, you are charged for gateway-related features provided by Function Compute based on the number of function invocations. Therefore, no additional fees are incurred regardless of whether you enable JWT authentication.

Signature algorithm	alg value
RSASSA-PKCS1-V1_5	RS256, RS384, or RS512
RSASSA-PSS	PS256, PS384, or PS512
Elliptic Curve (ECDSA)	ES256, ES384, or ES512
HMAC	HS256, HS384, or HS512
EdDSA	EdDSA