Configure self-hosted authentication

Create self-hosted authentication

1. Log on to the AI Gateway console.

2. In the navigation pane on the left, choose Instance. In the top menu bar, select a region.

3. On the Instance page, click the target instance ID.

4. In the left-side navigation pane, click Security Management > Global Authentication.

5. On the Global Authentication page, click Create Authentication. In the Create Authentication panel, configure the parameters and click OK.

   Parameter	Description
   Enable	Specifies whether to enable authentication.
   Authentication Name	The name of the authentication rule.
   Authentication Type	Select Custom Authentication Service.
   Authentication Service	The backend service to use for authentication. You can add services on the service management page. For more information, see Add a service. Note Only backend services that use the HTTP protocol are supported. Services that use other protocols, such as Dubbo, are not supported. If you select a Kubernetes service that has multiple ports, AI Gateway uses the first port by default. If you need to use a different port, you must create a separate Kubernetes service in Container Service for Kubernetes (ACK) that exposes only the target port.
   Authentication API	The request path of the authentication API provided by your authentication service. Path matching is based on prefixes. For example, if your authentication service is built with SpringMVC and exposes the authentication API /check/, you can configure it to handle requests for /check/*. The following code shows an example implementation: @RequestMapping("/check/") public ResponseEntity<RestResult<String>> check(){}
   Token Location	The header in the client request that contains the token. Common headers include Authorization and Cookie. You can select a header from the Select or select Add Manually to enter a custom header name.
   Allowed Headers in Authentication Rrequest	Additional headers from the original client request to forward to the authentication service. Note The Host, Method, Path, and Content-Length headers are forwarded by default and do not need to be added here.
   Allowed Headers in Authentication Response	Headers from the authentication service's response to add to the original request before forwarding it to the backend service. Note If a specified header already exists in the request, its value will be overwritten.
   Allow Body in Authentication Request	Select the Allow Body in Authentication Request option to include the body of the original request when sending it to the authentication service. Maximum Body Size: The maximum size of the request body, in bytes, that can be forwarded to the authentication service.
   Timeout Period	The maximum time, in seconds, that the gateway waits for a response from the authentication service. Default value: 10.
   Mode	The gateway's behavior when the authentication service is unavailable. Loose mode is recommended. Loose Mode: If the authentication service is unavailable (for example, the connection fails or the service returns a 5xx error), the gateway allows the client request to proceed to the backend service. Strict Mode: If the authentication service is unavailable, the gateway rejects the client request.
   Simple Condition	Click Simple Conditions to the right of Authorization. This mode supports Whitelist Mode and Blacklist Mode. Whitelist Mode: Requests that match the specified rules are exempt from authentication. All other requests require authentication. Blacklist Mode: Requests that match the specified rules require authentication. All other requests are exempt from authentication. Click Rule Condition to define rules based on the domain name, path, and request headers. Domain Name: The requested domain name (host). Path: The path of the requested API. Path Match Condition: Path supports exact match, prefix match, and regular expression match. Exact Match: Enter the full path, for example, /app/v1/order. Prefix Match: Enter a path prefix followed by an asterisk (*). For example, to match all requests that start with /app, enter /app/*. Regular Expression Match: The regular expression must follow the Google RE2 syntax. For more information, see Re2 Syntax. Case sensitive: If this option is selected, path matching is case-sensitive. Header: Define conditions based on request headers. Click Request Header to add a condition. If you define multiple header conditions, they are combined with a logical AND. HeaderKey: The name of the request header. Condition: The match condition for the header value. Equals To: The value of the header is equal to the specified value. Does Not Equal To: The value of the header is not equal to the specified value. Exists: The request contains the specified header. Does Not Exist: The request does not contain the specified header. Contains: The value of the header contains the specified value. Excludes: The value of the header does not contain the specified value. Prefix: The value of the header starts with the specified value. Suffix: The value of the header ends with the specified value. Regular Expression Match: The value of the header matches the specified regular expression. The expression must follow the Google RE2 syntax. For more information, see Re2 Syntax. Value: The value to match against the header.
   Complex Conditions	Click Complex Conditions to the right of Authorization. This mode allows you to define complex authorization rules using YAML to configure Envoy's permission data structure. You can combine conditions using AND, OR, and NOT logic. Requests that meet the configured conditions trigger authentication. Requests that do not meet the conditions bypass authentication. Note For a full description of the permission data structure, see the official Envoy documentation. For configuration examples, see Complex condition authorization examples.

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

Manage authentication services

1. Log on to the AI Gateway console.

2. In the navigation pane on the left, choose Instance. In the top menu bar, select a region.

3. On the Instance page, click the target instance ID.

4. In the left-side navigation pane, click Security Management > Global Authentication.

5. On the Authentication page, find the rule you want to manage and click Description in the Actions column. You can view the Basic Information and Authentication Configuration, and manage the Authorization Information.

   The details page is divided into three sections. The Basic Information section shows the authentication type is Self-managed Authentication Service. The Authentication Configuration section includes parameters such as Authentication Service, Authentication API, Token Position, Timeout, Mode, Body Allowed In Authentication Request, Headers Allowed In Authentication Request, and Headers Allowed In Authentication Response. The Authorization Information section displays the configured rules. In whitelist mode, multiple rules are combined by a logical OR, while conditions within a single rule are combined by a logical AND. The rules table includes the Request Domain, Request Path Match Items, Case-sensitive, Request Header Match Items, and Actions columns.

   In the Authorization Information section, click Create Authorization. In the dialog box that appears, enter a Request Domain Name and Request Path, select a Match Mode, and then click OK to add the new authorization rule.

Related operations

You can also perform the following operations to manage gateway authentication rules:

• Enable an authentication rule: On the Global Authentication page, find the target authentication rule and click Enable in the Actions column.

• Disable an authentication rule: On the Global Authentication page, find the target authentication rule and click Close in the Actions column.

• Edit an authentication rule: On the Global Authentication page, find the target authentication rule and click Edit in the Actions column.

• Delete an authentication rule: On the Global Authentication page, find the target authentication rule and click Delete in the Actions column.

Complex condition authorization

permissions:
# and_rules: Authentication is performed if all rules listed under this key are met.
- and_rules:
    rules:
      - url_path:
          # Match path by prefix
          path:
            prefix: /
      - header:
          # Match by regular expression
          safe_regex_match:
            regex: "(exampleA\\.com|exampleB\\.com)"
          # The :authority pseudo-header is used to match the domain name.
          name: ":authority"

Combine conditions with AND, OR, and NOT

This example meets the following requirements:

1. Requests with the prefix exampleA.com/api require authentication, except for the following:

   1. exampleA.com/api/appa/bbb does not require authentication.

   2. exampleA.com/api/appb/ccc does not require authentication.

2. All requests to exampleB.com require authentication, except for the following:

   1. exampleB.com/api/appa/bbb does not require authentication.

   2. exampleB.com/api/appb/ccc does not require authentication.

   3. Requests with the prefix exampleB.com/api/appc do not require authentication, with these exceptions:

      1. exampleB.com/api/appc/bbb/ccc requires authentication.

      2. exampleB.com/api/appc/ccc/ddd requires authentication.

The corresponding YAML configuration is as follows:

permissions:
# or_rules: Authentication is performed if any of the rules listed under this key is met.
- or_rules:
    rules:
      # Requirement 2.c.i: Authenticate 'exampleB.com/api/appc/bbb/ccc'.
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/bbb/ccc
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      # Requirement 2.c.ii: Authenticate 'exampleB.com/api/appc/ccc/ddd'.
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/ccc/ddd
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      # Requirement 1: Authenticate requests for 'exampleA.com' with the '/api/' prefix, excluding specific paths.
      - and_rules:
          rules:
            # Condition: Path must have prefix '/api/'.
            - url_path:
                path:
                  prefix: /api/
            # Exception 1.a: Do not authenticate if path is exactly '/api/appa/bbb'.
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Exception 1.b: Do not authenticate if path is exactly '/api/appb/ccc'.
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc                                
            # Condition: Host must be 'exampleA.com'.
            - header:
                exact_match: "exampleA.com"
                name: ":authority"                                
      # Requirement 2: Authenticate requests for 'exampleB.com', excluding specific paths.
      - and_rules:
          rules:
            # Condition: Path can be anything (prefix '/').
            - url_path:
                path:
                  prefix: /
            # Exception 2.a: Do not authenticate if path is exactly '/api/appa/bbb'.
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Exception 2.b: Do not authenticate if path is exactly '/api/appb/ccc'.
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc
            # Exception 2.c: Do not authenticate if path has prefix '/api/appc/'.
            - not_rule:
                url_path:
                  path:
                    prefix: /api/appc/                                         
            # Condition: Host must be 'exampleB.com'.
            - header:
                exact_match: "exampleB.com"
                name: ":authority"