Security Governance Parameters¶
This page introduces the parameters related to peer authentication, request authentication, and authorization policies.
Peer Authentication¶
When using the graphical wizard mode, peer authentication is divided into basic configuration and authentication settings. The parameters are described as follows.
Basic Configuration¶
UI Item | YAML Field | Description |
---|---|---|
Name | metadata.name | Required. The name of peer authentication, which cannot be duplicated within the same namespace. |
Namespace | metadata.namespace | Required. The namespace to which the peer authentication belongs. When selecting the root namespace of the mesh, a global policy will be created. Only one global policy can be created, so it needs to be checked in the interface to avoid duplicate creation by users. |
Workload Labels | spec.selector | Optional. The labels for selecting workloads to apply the peer authentication policy. Multiple labels can be added without sorting. |
Label Name | spec.selector.matchLabels | Required. Consists of lowercase letters, numbers, hyphens (-), underscores (_), and periods (.). |
Label Value | spec.selector.matchLabels.{label name} | Required. Consists of lowercase letters, numbers, hyphens (-), underscores (_), and periods (.). |
Authentication Settings - mTLS Mode¶
UI Item | YAML Field | Description |
---|---|---|
mTLS Mode | spec.mTLS.mode | Required. Used to set the mTLS mode for the namespace: - UNSET: Inherits the parent option. Otherwise, considered as PERMISSIVE. - PERMISSIVE: plaintext and mTLS connections. - STRICT: mTLS connections only. - DISABLE: plaintext connections only. |
Add mTLS Mode for Specified Ports | spec.portLevelMtls | Optional. Sets the mTLS mode for specified ports. Multiple rules can be added without sorting. - UNSET: Inherits the parent option. Otherwise, considered as PERMISSIVE. - PERMISSIVE: plaintext and mTLS connections. - STRICT: mTLS connections only. - DISABLE: plaintext connections only. |
Request Authentication¶
When using the graphical wizard mode, request authentication is divided into basic configuration and authentication settings. The parameters are described as follows.
Basic Configuration¶
UI Item | YAML Field | Description |
---|---|---|
Name | metadata.name | Required. The name of request authentication, which cannot be duplicated within the same namespace. |
Namespace | metadata.namespace | Required. The namespace to which the request authentication belongs. When selecting the root namespace of the mesh, a global policy will be created. Only one global policy can be created, so it needs to be checked in the interface to avoid duplicate creation by users. In the same namespace, the names of request authentication cannot be duplicated. |
Workload Labels | spec.selector | Optional. The labels for selecting workloads to apply the request authentication policy. Multiple labels can be added without sorting. |
Label Name | spec.selector.matchLabels | Required. Consists of lowercase letters, numbers, hyphens (-), underscores (_), and periods (.). |
Label Value | spec.selector.matchLabels.{label name} | Required. Consists of lowercase letters, numbers, hyphens (-), underscores (_), and periods (.). |
Authentication Settings¶
UI Item | YAML Field | Description |
---|---|---|
Add JWT Rule | spec.jwtRules | Optional. JWT rules for user request authentication. Multiple rules can be added. |
Issuer | spec.jwtRules.issuers | Required. Information about the JSON Web Token (JWT) issuer. |
Audiences | spec.jwtRules.issuers.Audiences | Optional. Configures the list of accessible audiences. If empty, it will access the service name. |
jwksUri | spec.jwtRules.issuers.jwksUri | Optional. The JSON file path for the JSON Web Key (JWK), exclusive with jwks. For example, https://www.googleapis.com/oauth2/v1/certs |
jwks | spec.jwtRules.issuers.jwks | Optional. The content of the JSON Web Key Set (JWKS) file, exclusive with jwksUri. |
For more information, please refer to OpenID Provider Metadata.
Authorization Policies¶
When using the graphical wizard mode, the creation of authorization policies is divided into basic configuration and policy settings. The parameters are described as follows.
Basic Configuration¶
UI Item | YAML Field | Description |
---|---|---|
Name | metadata.name | Required. The name of the authorization policy. |
Namespace | metadata.namespace | Required. The namespace to which the authorization policy belongs. When selecting the root namespace of the mesh, a global policy will be created. Only one global policy can be created, so it needs to be checked in the interface to avoid duplicate creation by users. In the same namespace, request authentication cannot have the same name. |
Workload Labels | spec.selector | Optional. The labels for selecting workloads to apply the authorization policy. Multiple labels can be added without sorting. |
Label Name | spec.selector.matchLabels | Optional. Consists of lowercase letters, numbers, hyphens (-), underscores (_), and periods (.). |
Label Value | spec.selector.matchLabels.{label name} | Optional. Consists of lowercase letters, numbers, hyphens (-), underscores (_), and periods (.). |
Policy Settings¶
UI Item | YAML Field | Description |
---|---|---|
Policy Action | spec.action | Optional. Includes: - allow - deny - audit - custom When selecting custom, an additional provider input item will be displayed. |
Provider | spec.provider.name | Required. Only displayed when Policy Action is selected as custom. |
Request Policies | spec.rules | Optional. Includes request source, request operation, and policy condition. Multiple rules can be added and executed in order. |
Add Request Source | spec.rules.-from | Optional. Defines the request source based on the namespace, IP range, etc. Multiple sources can be added. See the following section Source for parameters. |
Add Request Operation | spec.rules.-to | Optional. Defines the operation to be performed on the filtered requests, such as sending them to a specific port or host. Multiple operations can be added. See the following section Operation for parameters. |
Add Policy Condition | spec.rules.-when | Required. Policy conditions are optional settings that can add restriction conditions like blacklists (values) or whitelists (notValues). Multiple policy conditions can be added. See the following section Condition for parameters. |
Source¶
You can add request sources (Source). Source specifies the identity of the request source and performs logical AND operations on the fields in the request source.
For example, if the Source is:
- Principal is "admin" or "dev"
- Namespace is "prod" or "test"
- IP is not "1.2.3.4"
The matching YAML content would be:
The specific field descriptions are as follows:
Key Field | Type | Description |
---|---|---|
principals | string[] | Optional. Peer identities derived from peer certificates. The format of peer identities is " |
notPrincipals | string[] | Optional. Reverse matching list for peer identities. |
requestPrincipals | string[] | Optional. Request identities derived from JWT. The format of request identities is " |
notRequestPrincipals | string[] | Optional. Reverse matching list for request identities. |
namespaces | string[] | Optional. Namespaces derived from peer certificates. This field requires mTLS to be enabled and is equivalent to the source.namespace property. If not set, it allows all namespaces. |
notNamespaces | string[] | Optional. Reverse matching list for namespaces. |
ipBlocks | string[] | Optional. IP ranges filled based on the source address of IP packets. Supports single IPs (e.g., "1.2.3.4") and CIDR (e.g., "1.2.3.0/24"). This is equivalent to the source.ip property. If not set, it allows all IPs. |
notIpBlocks | string[] | Optional. Reverse matching list for IP ranges. |
remoteIpBlocks | string[] | Optional. IP ranges filled based on the X-Forwarded-For header or proxy protocol. To use this field, you must configure the numTrustedProxies field in meshConfig when installing Istio or when using annotations on the ingress gateway. Supports single IPs (e.g., "1.2.3.4") and CIDR (e.g., "1.2.3.0/24"). This is equivalent to the remote.ip property. If not set, it allows all IPs. |
notRemoteIpBlocks | string[] | Optional. Reverse matching list for remote IP ranges. |
Operation¶
You can add request operations (Operation). Operation specifies the operation of the request and performs logical AND operations on the fields in the operation.
For example, the following operation will match:
- Host suffix is ".example.com"
- Method is "GET" or "HEAD"
- Path does not have the prefix "/admin"
Key Field | Type | Description |
---|---|---|
hosts | string[] | Optional. The list of hosts specified in the HTTP request. Case-insensitive. If not set, it allows all hosts. Only applicable to HTTP. |
notHosts | string[] | Optional. Reverse matching list for hosts specified in the HTTP request. Case-insensitive. |
ports | string[] | Optional. The list of ports specified in the connection. If not set, it allows all ports. |
notPorts | string[] | Optional. Reverse matching list for ports specified in the connection. |
methods | string[] | Optional. The list of methods specified in the HTTP request. For gRPC services, this will always be "POST". If not set, it allows all methods. Only applicable to HTTP. |
notMethods | string[] | Optional. Reverse matching list for methods specified in the HTTP request. |
paths | string[] | Optional. The list of paths specified in the HTTP request. For gRPC services, this will be in the format of "/package.service/method" fully qualified name. If not set, it allows all paths. Only applicable to HTTP. |
notPaths | string[] | Optional. Reverse matching list for paths. |
In actual operations, it is also important to note the addition of some common keys
- request.headers[User-Agent]
- request.auth.claims[iss]
- experimental.envoy.filters.network.mysql_proxy[db.table]
For more information about the configuration parameters of AuthorizationPolicy, please refer to the documentation at https://istio.io/latest/docs/reference/config/security/conditions/.
Condition¶
You can also add policy conditions (Condition). Condition specifies other required attributes.
Key Field | Description | Supported Protocols | Value Example |
---|---|---|---|
request.headers | HTTP request headers, enclosed in [] | HTTP only | ["Mozilla/*"] |
source.ip | Source IP address, supports single IP or CIDR | HTTP and TCP | ["10.1.2.3"] |
remote.ip | Original client IP address determined by the X-Forwarded-For request header or proxy protocol, supports single IP or CIDR | HTTP and TCP | ["10.1.2.3", "10.2.0.0/16"] |
source.namespace | Namespace of the source workload instance, requires bidirectional TLS | HTTP and TCP | ["default"] |
source.principal | Identity of the source workload, requires bidirectional TLS | HTTP and TCP | ["cluster.local/ns/default/sa/productpage"] |
request.auth.principal | Request with authenticated principal | HTTP only | ["accounts.my-svc.com/104958560606"] |
request.auth.audiences | Target subject of this authentication information | HTTP only | ["my-svc.com"] |
request.auth.presenter | Issuer of the certificate | HTTP only | ["123456789012.my-svc.com"] |
request.auth.claims | Claims derived from JWT, enclosed in [] | HTTP only | ["*@foo.com"] |
destination.ip | Destination IP address, supports single IP or CIDR | HTTP and TCP | ["10.1.2.3", "10.2.0.0/16"] |
destination.port | Port on the destination IP address, must be within the range of [0, 65535] | HTTP and TCP | ["80", "443"] |
connection.sni | Server Name Indication, requires bidirectional TLS | HTTP and TCP | ["www.example.com"] |
experimental.envoy.filters.* | Experimental metadata matches for filters, with the value enclosed in [] as a list match | HTTP and TCP | ["[update]"] |
Note
The backward compatibility of experimental.* keys cannot be guaranteed and they may be removed at any time, so be cautious.