Authorization Policy

12 minute read

Istio Authorization Policy enables access control on workloads in the mesh.

Authorization policy supports CUSTOM, DENY and ALLOW actions for access control. When CUSTOM, DENY and ALLOW actions are used for a workload at the same time, the CUSTOM action is evaluated first, then the DENY action, and finally the ALLOW action. The evaluation is determined by the following rules:

If there are any CUSTOM policies that match the request, evaluate and deny the request if the evaluation result is deny.
If there are any DENY policies that match the request, deny the request.
If there are no ALLOW policies for the workload, allow the request.
If any of the ALLOW policies match the request, allow the request.
Deny the request.

Istio Authorization Policy also supports the AUDIT action to decide whether to log requests. AUDIT policies do not affect whether requests are allowed or denied to the workload. Requests will be allowed or denied based solely on CUSTOM, DENY and ALLOW actions.

A request will be internally marked that it should be audited if there is an AUDIT policy on the workload that matches the request. A separate plugin must be configured and enabled to actually fulfill the audit decision and complete the audit behavior. The request will not be audited if there are no such supporting plugins enabled.

Here is an example of Istio Authorization Policy:

It sets the action to ALLOW to create an allow policy. The default action is ALLOW but it is useful to be explicit in the policy.

It allows requests from:

service account cluster.local/ns/default/sa/sleep or
namespace test

to access the workload with:

GET method at paths of prefix /info or,
POST method at path /data.

when the request has a valid JWT token issued by https://accounts.google.com.

Any other requests will be denied.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: httpbin
  namespace: foo
spec:
  action: ALLOW
  rules:
  - from:
    - source:
        principals: ["cluster.local/ns/default/sa/sleep"]
    - source:
        namespaces: ["test"]
    to:
    - operation:
        methods: ["GET"]
        paths: ["/info*"]
    - operation:
        methods: ["POST"]
        paths: ["/data"]
    when:
    - key: request.auth.claims[iss]
      values: ["https://accounts.google.com"]

The following is another example that sets action to DENY to create a deny policy. It denies requests from the dev namespace to the POST method on all workloads in the foo namespace.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: httpbin
  namespace: foo
spec:
  action: DENY
  rules:
  - from:
    - source:
        namespaces: ["dev"]
    to:
    - operation:
        methods: ["POST"]

The following is another example that sets action to DENY to create a deny policy. It denies all the requests with POST method on port 8080 on all workloads in the foo namespace.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: httpbin
  namespace: foo
spec:
  action: DENY
  rules:
  - to:
    - operation:
        methods: ["POST"]
        ports: ["8080"]

When this rule is applied to TCP traffic, the method field (as will all HTTP based attributes) cannot be processed. For a DENY rule, missing attributes are treated as matches. This means all TCP traffic on port 8080 would be denied in the example above. If we were to remove the ports match, all TCP traffic would be denied. As a result, it is recommended to always scope DENY policies to a specific port, especially when using HTTP attributes Authorization Policy for TCP Ports.

The following authorization policy sets the action to AUDIT. It will audit any GET requests to the path with the prefix /user/profile.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  namespace: ns1
  name: anyname
spec:
  selector:
    matchLabels:
      app: myapi
  action: AUDIT
  rules:
  - to:
    - operation:
        methods: ["GET"]
        paths: ["/user/profile/*"]

Authorization Policy scope (target) is determined by “metadata/namespace” and an optional selector.

“metadata/namespace” tells which namespace the policy applies. If set to root namespace, the policy applies to all namespaces in a mesh.
workload selector can be used to further restrict where a policy applies.

For example, the following authorization policy applies to all workloads in namespace foo. It allows nothing and effectively denies all requests to workloads in namespace foo.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
 name: allow-nothing
 namespace: foo
spec:
  {}

The following authorization policy allows all requests to workloads in namespace foo.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
 name: allow-all
 namespace: foo
spec:
 rules:
 - {}

The following authorization policy applies to workloads containing label app: httpbin in namespace bar. It allows nothing and effectively denies all requests to the selected workloads.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: allow-nothing
  namespace: bar
spec:
  selector:
    matchLabels:
      app: httpbin

The following authorization policy applies to workloads containing label version: v1 in all namespaces in the mesh. (Assuming the root namespace is configured to istio-system).

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
 name: allow-nothing
 namespace: istio-system
spec:
 selector:
   matchLabels:
     version: v1

The following example shows you how to set up an authorization policy using an experimental annotation istio.io/dry-run to dry-run the policy without actually enforcing it.

The dry-run annotation allows you to better understand the effect of an authorization policy before applying it to the production traffic. This helps to reduce the risk of breaking the production traffic caused by an incorrect authorization policy. For more information, see dry-run tasks.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: dry-run-example
  annotations:
    "istio.io/dry-run": "true"
spec:
  selector:
    matchLabels:
      app: httpbin
  action: DENY
  rules:
  - to:
    - operation:
        paths: ["/headers"]

AuthorizationPolicy

AuthorizationPolicy enables access control on workloads.

Field	Description
`selector` WorkloadSelector	The selector decides where to apply the authorization policy. The selector will match with workloads in the same namespace as the authorization policy. If the authorization policy is in the root namespace, the selector will additionally match with workloads in all namespaces. If the selector and the targetRef are not set, the selector will match all workloads. At most one of `selector` or `targetRefs` can be set for a given policy.
`targetRefs` PolicyTargetReference[]	The targetRefs specifies a list of resources the policy should be applied to. The targeted resources specified will determine which workloads the policy applies to. Currently, the following resource attachment types are supported: `kind: Gateway` with `group: gateway.networking.k8s.io` in the same namespace. `kind: Service` with `group: ""` or `group: "core"` in the same namespace. This type is only supported for waypoints. If not set, the policy is applied as defined by the selector. At most one of the selector and targetRefs can be set. NOTE: If you are using the `targetRefs` field in a multi-revision environment with Istio versions prior to 1.22, it is highly recommended that you pin the policy to a revision running 1.22+ via the `istio.io/rev` label. This is to prevent proxies connected to older control planes (that don’t know about the `targetRefs` field) from misinterpreting the policy as namespace-wide during the upgrade process. NOTE: Waypoint proxies are required to use this field for policies to apply; `selector` policies will be ignored.
`rules` Rule[]	A list of rules to match the request. A match occurs when at least one rule matches the request. If not set, the match will never occur. This is equivalent to setting a default of deny for the target workloads if the action is ALLOW.
`action` Action	The action to take if the request is matched with the rules. Default is ALLOW if not specified.
`provider` ExtensionProvider (oneof)	Specifies detailed configuration of the CUSTOM action. Must be used only with CUSTOM action.

ExtensionProvider

Field	Description
`name` string	Specifies the name of the extension provider. The list of available providers is defined in the MeshConfig. Note, currently at most 1 extension provider is allowed per workload. Different workloads can use different extension provider.

Action

Action specifies the operation to take.

Name	Description
`ALLOW`	Allow a request only if it matches the rules. This is the default type.
`DENY`	Deny a request if it matches any of the rules.
`AUDIT`	Audit a request if it matches any of the rules.
`CUSTOM`	The CUSTOM action allows an extension to handle the user request if the matching rules evaluate to true. The extension is evaluated independently and before the native ALLOW and DENY actions. When used together, A request is allowed if and only if all the actions return allow, in other words, the extension cannot bypass the authorization decision made by ALLOW and DENY action. Extension behavior is defined by the named providers declared in MeshConfig. The authorization policy refers to the extension by specifying the name of the provider. One example use case of the extension is to integrate with a custom external authorization system to delegate the authorization decision to it. The following authorization policy applies to an ingress gateway and delegates the authorization check to a named extension `my-custom-authz` if the request path has prefix `/admin/`. `apiVersion: security.istio.io/v1 kind: AuthorizationPolicy metadata: name: ext-authz namespace: istio-system spec: selector: matchLabels: app: istio-ingressgateway action: CUSTOM provider: name: "my-custom-authz" rules: - to: - operation: paths: ["/admin/*"]`

Rule

Rule matches requests from a list of sources that perform a list of operations subject to a list of conditions. A match occurs when at least one source, one operation and all conditions matches the request. An empty rule is always matched.

Any string field in the rule supports Exact, Prefix, Suffix and Presence match:

Exact match: abc will match on value abc.
Prefix match: abc* will match on value abc and abcd.
Suffix match: *abc will match on value abc and xabc.
Presence match: * will match when value is not empty.

Field Description

Field	Description
`from` From[]	`from` specifies the source of a request. If not set, any source is allowed.
`to` To[]	`to` specifies the operation of a request. If not set, any operation is allowed.
`when` Condition[]	`when` specifies a list of additional conditions of a request. If not set, any condition is allowed.

from

From[]

from specifies the source of a request.

If not set, any source is allowed.

to

To[]

to specifies the operation of a request.

If not set, any operation is allowed.

when

Condition[]

when specifies a list of additional conditions of a request.

If not set, any condition is allowed.

From

From includes a list of sources.

Field	Description
`source` Source	Source specifies the source of a request.

To

To includes a list of operations.

Field	Description
`operation` Operation	Operation specifies the operation of a request.

Source

Source specifies the source identities of a request. Fields in the source are ANDed together.

For example, the following source matches if the principal is admin or dev and the namespace is prod or test and the ip is not 203.0.113.4.

principals: ["admin", "dev"]
namespaces: ["prod", "test"]
notIpBlocks: ["203.0.113.4"]

Field	Description
`principals` string[]	A list of peer identities derived from the peer certificate. The peer identity is in the format of `"<TRUST_DOMAIN>/ns/<NAMESPACE>/sa/<SERVICE_ACCOUNT>"`, for example, `"cluster.local/ns/default/sa/productpage"`. This field requires mTLS enabled and is the same as the `source.principal` attribute. Usage of `serviceAccounts` is typically simpler and offers the same functionality. If not set, any principal is allowed.
`notPrincipals` string[]	A list of negative match of peer identities.
`requestPrincipals` string[]	A list of request identities derived from the JWT. The request identity is in the format of `"<ISS>/<SUB>"`, for example, `"example.com/sub-1"`. This field requires request authentication enabled and is the same as the `request.auth.principal` attribute. If not set, any request principal is allowed.
`notRequestPrincipals` string[]	A list of negative match of request identities.
`namespaces` string[]	A list of namespaces derived from the peer certificate. This field requires mTLS enabled and is the same as the `source.namespace` attribute. If not set, any namespace is allowed.
`notNamespaces` string[]	A list of negative match of namespaces.
`serviceAccounts` string[]	A list of Kubernetes service accounts derived from the peer certificate. This field requires mTLS enabled and is the same as the `source.serviceaccount` attribute. This takes the format `<namespace>/<serviceaccount>`. If not set, any service account is allowed. No form of wildcard (`*`) is allowed. Cannot be set with `principals` or `namespaces`.
`notServiceAccounts` string[]	A list of negative match of Kubernetes service accounts. This takes the format `<namespace>/<serviceaccount>`. No form of wildcard (`*`) is allowed.
`ipBlocks` string[]	A list of IP blocks, populated from the source address of the IP packet. Single IP (e.g. `203.0.113.4`) and CIDR (e.g. `203.0.113.0/24`) are supported. This is the same as the `source.ip` attribute. If not set, any IP is allowed.
`notIpBlocks` string[]	A list of negative match of IP blocks.
`remoteIpBlocks` string[]	A list of IP blocks, populated from `X-Forwarded-For` header or proxy protocol. To make use of this field, you must configure the `numTrustedProxies` field of the `gatewayTopology` under the `meshConfig` when you install Istio or using an annotation on the ingress gateway. See the documentation here: Configuring Gateway Network Topology. Single IP (e.g. `203.0.113.4`) and CIDR (e.g. `203.0.113.0/24`) are supported. This is the same as the `remote.ip` attribute. If not set, any IP is allowed.
`notRemoteIpBlocks` string[]	A list of negative match of remote IP blocks.

Operation

Operation specifies the operations of a request. Fields in the operation are ANDed together.

For example, the following operation matches if the host has suffix .example.com and the method is GET or HEAD and the path doesn’t have prefix /admin.

hosts: ["*.example.com"]
methods: ["GET", "HEAD"]
notPaths: ["/admin*"]

Field	Description
`hosts` string[]	A list of hosts as specified in the HTTP request. The match is case-insensitive. See the security best practices for recommended usage of this field. If not set, any host is allowed. Must be used only with HTTP.
`notHosts` string[]	A list of negative match of hosts as specified in the HTTP request. The match is case-insensitive.
`ports` string[]	A list of ports as specified in the connection. If not set, any port is allowed.
`notPorts` string[]	A list of negative match of ports as specified in the connection.
`methods` string[]	A list of methods as specified in the HTTP request. For gRPC service, this will always be `POST`. If not set, any method is allowed. Must be used only with HTTP.
`notMethods` string[]	A list of negative match of methods as specified in the HTTP request.
`paths` string[]	A list of paths as specified in the HTTP request. See the Authorization Policy Normalization for details of the path normalization. For gRPC service, this will be the fully-qualified name in the form of `/package.service/method`. If a path in the list contains the `{}` or `{}` path template operator, it will be interpreted as an Envoy Uri Template. To be a valid path template, the path must not contain ``, `{`, or `}` outside of a supported operator. No other characters are allowed in the path segment with the path template operator. `{}` matches a single glob that cannot extend beyond a path segment. `{}` matches zero or more globs. If a path contains `{}`, it must be the last operator. Examples: `/foo/{}` matches `/foo/bar` but not `/foo/bar/baz` `/foo/{*}/` matches `/foo/bar/`, `/foo/bar/baz.txt`, and `/foo//` but not `/foo/bar` `/foo/{}/bar/{*}` matches `/foo/buzz/bar/` and `/foo/buzz/bar/baz` `//baz/{}` is not a valid path template since it includes `` outside of a supported operator `/*/baz/{}` is not a valid path template since it includes `` outside of a supported operator `/{}/foo/{}` is not a valid path template since `{}` is not the last operator `/foo/{}.txt` is invalid since there are characters other than `{*}` in the path segment If not set, any path is allowed. Must be used only with HTTP.
`notPaths` string[]	A list of negative match of paths.

Condition

Condition specifies additional required attributes.

Field	Description
`key` string Required	The name of an Istio attribute. See the full list of supported attributes.
`values` string[]	A list of allowed values for the attribute. Note: at least one of `values` or `notValues` must be set.
`notValues` string[]	A list of negative match of values for the attribute. Note: at least one of `values` or `notValues` must be set.