IDaaS Open Platform

Gateway Configuration

Gateway

# Gateway Configuration Instructions

  • In the advanced configuration, you can define the basic functional configurations for the gateway cluster. Currently, configurations for three modules can be defined: admin, logging, and security.
  • Configurations added under the application security gateway are inherited by all new gateway Servers created under it.

# admin Configuration Instructions

{
    "admin":{
        "enabled": true,
        "listen": ":2019"
    }
}
1
2
3
4
5
6
Parameter Type Required Default Description
enabled bool Optional false Whether to enable the admin service, default is false
listen string Required Admin service access address, e.g., :2019, indicating listening on port 2019

This module defines the endpoint capabilities provided by the gateway service.

Interface Description
/config View the current gateway configuration content
/firewall/ip View the port hidden IP whitelist list
/debug/pprof pprof performance monitoring port
/metrics prometheus service data pull port

# logging Configuration Instructions

{
  "logging" : {
        "logs": {
            "file_log": {
                "writer" : {
                    "output": "file",
                    "filename": "log/gateway.log",
                    "roll": true,
                    "roll_size_mb": 0,
                    "roll_gzip": true,
                    "roll_local_time": false,
                    "roll_keep": 10,
                    "roll_keep_days": 90
                },
                "level": "debug",
            }
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Under logging, the fixed value is logs. Under logs, multiple log configurations can be added. Each log configuration name must be unique. The example value here is "file_log".

Parameter Type Required Default Description
writer.output string Required Log output type, fixed value file
writer.filename string Required Log file path
writer.roll bool Optional true Whether to enable log rolling, default is enabled
writer.roll_size_mb int Optional 100 When the log file reaches approximately this size, it will be rotated. When the value is less than or equal to 0, the default is 100MB.
writer.roll_gzip bool Optional true Whether to compress rolled files, default is true
writer.roll_local_time bool Optional false Whether to use local timestamps in rolled file names, default is false.
writer.roll_keep int Optional 10 Maximum number of rolled log files to keep. When the value is less than or equal to 0, the default is 10.
writer.roll_keep_days int Optional 90 Number of days to keep rolled log files. When the value is less than or equal to 0, the default is 90.
level string Optional INFO Log output level, supports DEBUG, INFO, WARN, ERROR, PANIC, and FATAL. Supports system placeholders. Default is INFO.

# Security Configuration Instructions

The security module includes firewall functionality configuration. When the firewall feature is configured, it will intercept access to the HTTP port, HTTPS port, and any ports specified in the hidden configuration that the gateway Server is listening on, meaning access to these ports will be denied. So how can real users access them? There are two ways.

The first method is through the ip_whitelist configuration, which allows access from specified IPs.

The second method is that IDaaS will collect the IPs of users who have logged into the platform and synchronize them with the gateway. Access is allowed from the IPs of these users who are logged in and have an active session.

{
  "security": {
    "firewall": {
      "device": "enps0",
      "hidden_port": [8080],
      "ip_whitelist": ["192.168.152.101","192.168.153.0/24"],
      "use_iptables": true,
      "open_log": false
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
Parameter Type Required Default Description
device string Optional Required only in bpf mode. bpf requires specifying the name of the network interface card to monitor. If the specified NIC name does not exist on the server, the gateway service will fail to start.
hidden_port []int Optional In addition to the HTTP port and HTTPS port that the Server is listening on, additional port numbers that need to be hidden can be added.
ip_whitelist []string Optional Firewall IP whitelist. The parameter supports IPv4 or CIDR format.
use_iptables bool Optional false Use iptables to implement firewall functionality. If false, on Linux kernels > 5.7, bpf technology may be used to implement firewall functionality.
open_log bool Optional true Enable logging. In iptables mode, and provided the server where the gateway is deployed has the relevant configuration added, the gateway will read and record firewall interception logs. Supported in gateway version 24.06.1.0 and above.

# Application Gateway Advanced Configuration

In addition to using basic configuration to complete application proxy settings, access control, and watermark configuration, additional advanced configurations can be applied for advanced features.

After saving the basic page configuration, a JSON-formatted advanced configuration code is ultimately generated. The JSON configuration contains a handle array, where each handler represents a feature name. The JSON configuration must retain the proxy configuration, i.e., the reverse_proxy configuration. Please keep the configuration order unchanged.

Advanced configuration code example:

{
  "handle": [
    {
      "handler": "authentication",
      "providers": {
        "oidc": {
          "domain": "******.bccastle.com",
          "clientId": "FRq******lqA"
        }
      }
    },
    {
      "handler": "script",
      "watermark": {
        "text1": "{user.username}",
        "text2": "{user.mobile_suffix}",
        "color": "#dedede",
        "degree": -30,
        "fontSize": 20,
        "lineSpace": 200,
        "opacity": 0.5
      }
    },
    {
      "handler": "reverse_proxy",
      "upstreams": [
        {
          "dial": "httpbin.org:80"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# Gateway Authentication: authentication

  • This configuration is automatically added when gateway authentication is enabled. The providers configuration contains OIDC configuration parameters. Both domain and clientId are generated by default. Manual modification is not recommended to prevent gateway authentication failure.
  • ignore can be configured to specify URLs to bypass authentication. It is empty by default, meaning all URLs require authentication.
{
      "handler": "authentication",
      "providers": {
        "oidc": {
          "domain": "******.bccastle.com",
          "clientId": "FRq******lqA"
        }
      },
      "ignore": [
        {
          "path": ["/api/*"]
        }
      ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Watermark and Page Control: script

This configuration is added when any access control (except gateway authentication) or watermark functionality is enabled. It includes watermark and control modules, corresponding to watermark and page control configuration parameters.

{
      "handler": "script",
      "watermark": {
        "text1": "{user.username}",
        "text2": "{user.name}",
        "color": "#dedede",
        "degree": -20,
        "fontSize": 20,
        "lineSpace": 200,
        "opacity": 0.2
      },
      "control": {
        "contextmenu": false,
        "selectstart": false,
        "paste": false,
        "copy": false,
        "cut": false
      }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Parameter Type Required Default Description
watermark json Optional Watermark function configuration. If the parameter is empty, the watermark is not enabled.
watermark.text1 string Required First line of watermark text. Supports dynamic parameters when gateway authentication is enabled, using curly braces to enclose parameters.
{user.userId} User ID
{user.username} Username
{user.name} Full Name
{user.email} Email
{user.email_prefix} Email Prefix
{user.mobile} Mobile Number
{user.mobile_suffix} Last 4 digits of mobile number
watermark.text2 string Optional Second line of watermark text
watermark.color string Optional #dedede Font color
watermark.font string Optional Microsoft Yahei Font
watermark.fontSize int Optional 20 Font size, unit: px
watermark.degree int Optional -30 Font rotation angle, range [-90, 90]
watermark.opacity int Optional 1 Font opacity, range [0,1]. For example, 0 is fully transparent, 0.5 is semi-transparent, 1 is opaque.
watermark.lineSpace int Optional 150 Vertical spacing between each line of text, unit: px
control json Optional Page control operation configuration. If the parameter is empty, page control is not enabled.
control.contextmenu bool Optional false false=Disable right-click operation, true=Allow right-click operation
control.selectstart bool Optional false false=Disable selection operation, true=Allow selection operation
control.paste bool Optional false false=Disable paste operation, true=Allow paste operation
control.copy bool Optional false false=Disable copy operation, true=Allow copy operation
control.cut bool Optional false false=Disable cut operation, true=Allow cut operation

# Reverse Proxy: reverse_proxy

{
    "handler": "reverse_proxy",
    "upstreams": [{                             // Multiple addresses can be configured
        "dial": "127.0.0.1:8080",               // The ip:port to be proxied
    }],
    "load_balancing": {                         // Load balancing configuration when there are multiple upstreams
        "selection_policy": {
            "policy" : "random",                // Round-robin policy, default is random policy
        },
        "retries": 3,                           // Number of retries
        "try_duration": "5s",                   // Total time spent on retries; no further retries after exceeding this time
        "try_interval": "100ms"                 // Wait time between each retry. When try_duration >0 && try_interval == 0, try_interval defaults to 250ms
   },
    "transport": {
        "protocol": "http",                     // Fixed value, using HTTP protocol
        "tls":{                                 // In general scenarios, configuring an empty tls is sufficient to enable TLS with reasonable defaults
            "root_ca_pool": [""],               // Optional list of base64-encoded DER-encoded CA certificates to trust. Add trusted root certificate authorities
            "root_ca_pem_files": [""],          // File paths for adding trusted root certificate authorities
            "client_certificate_file": "",      // Path to the certificate file. ClientCertificateKeyFile is required when this parameter is present
            "client_certificate_key_file": "",  // Path to the key file. ClientCertificateFile is required when this parameter is present
            "insecure_skip_verify": true,       // If true, TLS verification of the server certificate will be skipped
            "handshake_timeout": 0,             // Duration allowed for TLS handshake with the server. Default: no timeout.
            "server_name": "",                  // Server name used when verifying the certificate received in the TLS handshake. By default, this uses the host part of the upstream address. Only rewrite this if the upstream address does not match the certificate the upstream might use.
            "renegotiation": "",                // TLS renegotiation level. "never": disable renegotiation; "once": once per connection, allow the remote server to request renegotiation once; "freely": allow the remote server to repeatedly request renegotiation.
            "except_ports": [""]                // Skip TLS ports. Specify a list of upstream ports where TLS will not be attempted even if TLS is configured.
        },
        "keep_alive": {
            "enabled": true,                    // Whether to enable HTTP Keep-Alive. Enabled by default.
            "probe_interval": "30s",            // Interval between keep-alive probes. Default: 30s.
            "max_idle_conns": 0,                // Maximum number of idle connections. Default: 0, meaning unlimited.
            "max_idle_conns_per_host": 32,      // Maximum number of idle connections per host. Default: 32.
            "idle_timeout": "2m"                // How long a connection should stay alive when idle. Default: 2m.
        },
        "compression": true,                    // Whether to enable compression. Enabled by default.
        "max_conns_per_host": 0,                // Maximum number of connections per host. Default: 0 (unlimited).
        "dial_timeout": "3s",                   // Timeout when connecting to the upstream. Default: 3s.
        "dial_fallback_delay": "300ms",
        "response_header_timeout": "10s",       // How long to wait for the server to read the response headers. Default: no timeout.
        "expect_continue_timeout": "10s",
        "max_response_header_size": 100,        // Maximum bytes to read from the response headers.
        "write_buffer_size": 0,                 // Size of the write buffer in bytes.
        "read_buffer_size": 0,                  // Size of the read buffer in bytes.
        "read_timeout": "10s",                  // Maximum time to wait for the next read from the backend.
        "write_timeout": "10s"                  // Maximum time to wait for the next write to the backend.
    },
    "rewrite": {
        "strip_path_prefix": "",                // Strip the given prefix from the beginning of the URI path.
        "strip_path_suffix": "",                // Strip the given suffix from the end of the URI path.
     },
    "headers": {
     "request": {
        "add": {
           "": [""]                             // Add header
         },
        "set": {
           "": [""]                             // Modify header
         },
        "delete": [""],                         // Delete header
        "replace": {                            // Replace header value
            "key": [{                           // The header key to be replaced. Only one of search or search_regexp can be chosen.
                "search": "",                   // Content to be replaced.
                "search_regexp": "",            // Regex to be replaced.
                "replace": ""                   // Replacement content.
            }]
        }
    },
    "response": {                              // The response parameters are the same as request.
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

I understand. Please provide the Markdown content you need translated. I will follow all the rules you have outlined.

Gateway Installation