Secure Gateway Routes with Custom Auth Policies - Microservices Engine

A cloud-native gateway can delegate token validation to an external authentication service, so every incoming request is authenticated before it reaches your backend. Instead of integrating authentication logic into each microservice, define one authentication rule on the gateway to enforce token validation across all routes.

How it works

When a client sends a request to a protected route, the gateway forwards request metadata to your authentication service. Based on the response, the gateway either passes the original request to the backend or rejects it.

Cloud-native gateway custom authentication flow

The request flow:

The client sends a login request to the gateway.
The gateway forwards the request to the authentication server.
The authentication server validates the credentials (such as username and password) and returns a token. The gateway relays the token to the client.
The client sends a business request (for example, POST /order) with the token attached.
The gateway constructs an authentication request and sends it to your authentication service. This request includes: The authentication request path is a concatenation of the authentication API path and the business request path. For example, if the authentication API path is /validateToken and the business request path is /order, the authentication request path becomes /validateToken/order.
- The business request path and query parameters
- The HTTP method (GET, POST, and others)
- The token (from the header you specify in the MSE console)
- Optionally, the body of the business request
The authentication service validates the token and checks permissions based on the path.

Authentication result handling

The gateway determines success or failure based on the HTTP status code from the authentication service:

Response	Result
HTTP 200	Token is valid. The gateway forwards the original business request to the backend.
HTTP 401 or 403	Token is invalid or unauthorized. The gateway returns the authentication response to the client.

If your authentication service can only return HTTP 200 (due to business constraints), use the built-in header x-mse-external-authz-check-result instead:

Header value	Result
`x-mse-external-authz-check-result: true`	Token is valid. The gateway forwards the request to the backend.
`x-mse-external-authz-check-result: false`	Token is invalid. The gateway returns the authentication response to the client.

Default forwarded headers

The gateway automatically includes the following headers from the client request in every authentication request:

Header	Description
Host	The original request host
Method	The HTTP method of the original request
Path	The request path
Content-Length	The body length of the original request

To forward additional headers, configure them in the The headers that can be carried in an authentication request. parameter.

JWT vs. custom tokens

Token type	Validation method	When to use
JWT	The gateway validates tokens locally using a public key. No external service call is needed.	Standard token validation without custom business logic
Custom token	The gateway forwards tokens to an external authentication service for validation.	Custom validation logic, legacy token formats, or permission checks tied to business rules

This topic covers custom token authentication. For JWT authentication, see the JWT authentication documentation.

Prerequisites

Before you begin, make sure that you have:

A cloud-native gateway instance in Microservices Engine (MSE)
An HTTP-based authentication service deployed and accessible from the gateway

Note

Only HTTP services are supported as authentication services. Other protocols such as Dubbo are not supported.

Create a custom authentication rule

Log on to the MSE console.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. In the top navigation bar, select a region.
On the Gateways page, click the ID of the gateway.
In the left-side navigation pane, choose Security Management > Global Authentication.
On the Global Authentication page, click Create Authentication.
In the Create Authentication panel, configure the following parameters and click OK.

Basic parameters

Parameter	Description	Required
Authentication Name	A name for the custom authentication rule.	Yes
Authentication Type	Select User-created Authentication.	Yes
Authentication Service	The backend HTTP service that validates tokens and permissions. For more information, see Add a service.	Yes
Authentication API	The path of the authentication API. Supports prefix matching. For example, if your authentication API path is `/check`, configure your service to handle `/check/` requests. Spring MVC example: `@RequestMapping("/check/")`.	Yes
Token Location	The request header that contains the token. Typically Authorization or Cookie. Select Drop-down List or Manual Input to specify the header.	Yes

Note

For Kubernetes services with multiple ports, the first port is used by default. To use a different port, create a separate Kubernetes service in Container Service for Kubernetes (ACK) that exposes only the desired port.

Request and response headers

Parameter	Description	Default
The headers that can be carried in an authentication request.	Additional headers from the client business request to include in the authentication request.	Host, Method, Path, Content-Length
Allow Headers Include in Authentication Response	Headers from the authentication response to append to the client business request before forwarding to the backend. If a header already exists in the business request, the value is overwritten.	None
Allow Include Body in Authentication Request	When enabled, the authentication request includes the body of the business request. Set Maximum Body Bytes to limit the body size (in bytes).	Disabled

Timeout and failure handling

Parameter	Description	Default
Expiration Time	Maximum time (in seconds) to wait for the authentication service to respond.	10
Write mode	Controls gateway behavior when the authentication service is unavailable (connection failure or 5xx response).	Loose Mode

Write mode options:

Loose Mode (recommended): The gateway continues to accept client requests when the authentication service is unavailable.
Strict Mode: The gateway rejects all client requests when the authentication service is unavailable.

Note

Choose Strict Mode for high-security environments where unauthenticated access is unacceptable, even during auth service outages.

Authorization rules

Authorization rules control which requests require authentication. Configure rules by clicking Simple Rule or Complex Rule on the right side of Authorization.

Simple rules

Simple rules support Whitelist and Blacklist methods:

Whitelist: Requests matching the specified hostnames and paths skip authentication. All other requests require authentication.
Blacklist: Only requests matching the specified hostnames and paths require authentication. All other requests skip authentication.

Click + Rule Condition to add conditions:

Condition type	Description
Domain Name	Host domains that access the cloud-native gateway.
Path	Request paths to match.
Path Match Condition	Exact Match (for example, `/app/v1/order`), Prefix Match (for example, `/app/`), or Regular Expression Match* (Google RE2 syntax).
Case Sensitive	When enabled, path matching is case-sensitive.
Header	Request headers to match. Click + Request Header to add multiple headers. Multiple headers use AND logic.

Header matching conditions:

Condition	Matches when
Equal To	Header value equals the specified value
Not Equal To	Header value differs from the specified value
exist	Header key exists in the request
Do Not Exist	Header key does not exist in the request
Include	Header value contains the specified value
Exclude	Header value does not contain the specified value
prefix	Header value starts with the specified value
suffix	Header value ends with the specified value
regular	Header value matches a regular expression (Google RE2 syntax)

Complex rules

Complex rules use the Envoy permission data structure in YAML format, supporting AND, OR, and NOT conditions. Requests that match the configured rules require authentication. Requests that do not match skip authentication.

For field definitions, see the Envoy documentation.

For configuration examples, see Complex rule examples.

Verify the result

Return to the Global Authentication page. If the new authentication rule appears in the list, the rule was created successfully.

View and manage authentication rules

Log on to the MSE console.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. In the top navigation bar, select a region.
On the Gateways page, click the ID of the gateway.
In the left-side navigation pane, choose Security Management > Global Authentication.
On the Global Authentication page, find the target authentication rule and click Details in the Actions column.

On the details page, the following sections are available:

Basic Information: Name, type, and service configuration.
Authentication Configuration: API path, token location, headers, timeout, and failure mode.
Authorization Information: Configured authorization rules. Click Create Authorization Info to add rules by specifying Request Host, Request Path, and match mode.

Manage authentication rules

On the Global Authentication page, find the target rule and use the Actions column:

Action	Description
Enable	Activate the authentication rule.
Disable	Deactivate the authentication rule.
Edit	Modify the rule configuration.
Delete	Remove the rule. The rule must be disabled before deletion.

Complex rule examples

Match domain names with regular expressions

This example enforces authentication only for requests to exampleA.com and exampleB.com that match the path prefix /. Requests to other domains (such as test.exampleA.com) skip authentication.

Note

The regular expression uses full-string matching, not partial matching. The expression follows Google RE2 syntax. For field definitions, see the Envoy documentation.

permissions:
# and_rules: Authentication is required when all rules match.
- and_rules:
    rules:
      - url_path:
          # Match all paths with prefix /
          path:
            prefix: /
      - header:
          # Match domain names using a regular expression
          safe_regex_match:
            regex: "(exampleA\\.com|exampleB\\.com)"
          # Use the :authority pseudo-header to match the domain name
          name: ":authority"

Combine AND, OR, and NOT conditions

This example enforces authentication for specific path and domain combinations while excluding certain paths:

Authentication is required for:

All paths under exampleA.com/api/, except:
- exampleA.com/api/appa/bbb
- exampleA.com/api/appb/ccc
All paths under exampleB.com/, except:
- exampleB.com/api/appa/bbb
- exampleB.com/api/appb/ccc
- Paths under exampleB.com/api/appc/, except:
  - exampleB.com/api/appc/bbb/ccc
  - exampleB.com/api/appc/ccc/ddd

permissions:
# or_rules: Authentication is required if any of the following rule sets match.
- or_rules:
    rules:
      # Rule set 1: exampleB.com/api/appc/bbb/ccc
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/bbb/ccc
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      # Rule set 2: exampleB.com/api/appc/ccc/ddd
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/ccc/ddd
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      # Rule set 3: exampleA.com/api/* (excluding specific paths)
      - and_rules:
          rules:
            - url_path:
                path:
                  prefix: /api/
            # Exclude /api/appa/bbb
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Exclude /api/appb/ccc
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc
            - header:
                exact_match: "exampleA.com"
                name: ":authority"
      # Rule set 4: exampleB.com/* (excluding specific paths and prefixes)
      - and_rules:
          rules:
            - url_path:
                path:
                  prefix: /
            # Exclude /api/appa/bbb
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Exclude /api/appb/ccc
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc
            # Exclude /api/appc/* (handled by rule sets 1 and 2)
            - not_rule:
                url_path:
                  path:
                    prefix: /api/appc/
            - header:
                exact_match: "exampleB.com"
                name: ":authority"