Authorization policy overview

Unlike a monolithic application that might be running in one place,globally-distributed microservices apps make calls across network boundaries.This means more points of entry into your applications, and more opportunitiesfor malicious attacks. And because Kubernetes pods have transient IPs,traditional IP-based firewall rules aren't adequate to secure access betweenworkloads. In a microservices architecture, a new approach to security isneeded. Building on security features such asKubernetes service accounts and Istio security policies, Cloud Service Meshprovides even more capabilities to help you secure yourapplications.

This page gives application operators an overview of theAuthorizationPolicycustom resource (CR). Authorization policies let you enable access control onworkloads at the application (L7) and transport (L3/4) layers. You configureauthorization policies to specify permissions—what is this service or userallowed to do?

Authorization policies

Requests between services in your mesh (and between end-users and services) areallowed by default. You use theAuthorizationPolicy CR to define granularpolicies for your workloads. After you apply the authorization policies,Cloud Service Mesh distributes them to the sidecar proxies. As requests come into aworkload, the sidecar proxy checks the authorization policies to determine ifthe request should be allowed or denied.

SeeSupported features for details of whichfields of theAuthorizationPolicy CR are supported by platform.

Policy scope

You can apply a policy to the entire service mesh, to a namespace, or to anindividual workload.

• To apply a mesh-wide policy, specify the root namespace,istio-system, inthemetadata:namespace field:

  apiVersion: "security.istio.io/v1beta1"kind: "AuthorizationPolicy"metadata:  name: "mesh-wide"  namespace: istio-systemspec:...

• To apply a policy to a namespace, specify the namespace in themetadata:namespace field:

  apiVersion: "security.istio.io/v1beta1"kind: "AuthorizationPolicy"metadata:  name: "currencyservice"  namespace: currencyservicespec:...

• To restrict a policy to a specific workload, include aselectorfield.

  apiVersion: "security.istio.io/v1beta1"kind: "AuthorizationPolicy"metadata:  name: "frontend"  namespace: demospec:  selector:    matchLabels:      app: frontend   ...

Basic structure

An authorization policy includes the policy scope, anaction, and a list ofrules:

• As described in the previous section, the policy scope can be theentire mesh, a namespace, or a specific workload. If you include it, theselector field specifies the target of the policy.

• Theaction field specifies whether toALLOW orDENY the request.If you don't specify an action, by default, the action is set toALLOW. Forclarity, we recommend that you always specify the action. (Authorizationpolicies also supportAUDIT andCUSTOM actions. TheAUDIT action is only supported on some plaforms. SeeSupported features for details.)

• Therules specify when to trigger the action.

  • Thefrom field in therules specifies thesources of the request.

  • Theto field in therules specifies theoperations of the request.

  • Thewhen field specifies additionalconditions needed to apply the rule.

In the following example:

• The policy is applied to requests to thefrontend service in thedemo namespace.

• Requests are allowed when "hello:world" is in the request header;otherwise, requests are denied.

apiVersion: "security.istio.io/v1beta1"kind: "AuthorizationPolicy"metadata:  name: "hello-world"  namespace: demospec:  selector:    matchLabels:      app: frontend  action: ALLOW  rules:  - when:    - key: request.headers[hello]      values: ["world"]

Access control on request operation

You can control access to specific requestoperations such as HTTP methods or TCP ports by adding ato section underrules.In the following example, only theGET andPOST HTTP methods are allowedto thecurrencyservice in thedemo namespace.

apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata: name: currencyservice namespace: demospec: selector:   matchLabels:     app: currencyservice action: ALLOW rules: - to:   - operation:       methods: ["GET", "POST"]

Access control on authenticated identity

In the previous examples, the policies allow requests from unauthenticatedworkloads. If you haveSTRICT mutual TLS (mTLS) enabled,you can restrict access based on the identity of the workload or namespace thatthe request is from in thesource section.

• Use theprincipals ornotPrincipal field to control access at theworkload level.

• Use thenamespaces ornotNamespaces field to control access at thenamespace level.

All of the preceding fields require that you haveSTRICT mTLS enabled. If you areunable to setSTRICT mTLS, seeReject plaintext requests for an alternativesolution.

Identified workload

In the following example, requests to thecurrencyservice are allowed onlyfrom thefrontend service. Requests to thecurrencyservice from otherworkloads are denied.

apiVersion: "security.istio.io/v1beta1"kind: "AuthorizationPolicy"metadata:  name: "currencyservice"  namespace: demospec:  selector:    matchLabels:      app: currencyservice  action: ALLOW  rules:  - from:    - source:        principals: ["example-project-1234.svc.id.goog/ns/demo/sa/frontend-sa"]

To specify a service account, theprincipals must be in the following format:

principals: ["PROJECT_ID.svc.id.goog/ns/NAMESPACE/sa/SERVICE_ACCOUNT_NAME"]

If you are using in-cluster Cloud Service Mesh with Citadel CA, thencluster.local is the trust domain. In all other cases,PROJECT_ID.svc.id.googis the trust domain for the mesh.

Identified namespace

The following example shows a policy that denies requests if the source is notthefoo namespace:

apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata: name: httpbin-deny namespace: foospec: selector:   matchLabels:     app: httpbin     version: v1 action: DENY rules: - from:   - source:       notNamespaces: ["foo"]

Value matching

Most fields in authorization policies support all the following matchingschemas:

• Exact match: exact string match.
• Wildcard match using the"*" wildcard character:
  • Prefix match: a string with an ending"*". For example,"test.example.*" matches"test.example.com" or"test.example.com.cn".
  • Suffix match: a string with a starting"*". For example,"*.example.com" matches"eng.example.com" or"test.eng.example.com".
• Presence match: To specify that a field must be present and not empty, usethefieldname: ["*"] format. This is different from leaving a fieldunspecified, which means match anything, including empty.

There are a few exceptions. For example, the following fields only supportexact match:

• Thekey field under thewhen section
• TheipBlocks under thesource section
• Theports field under theto section

The following example policy allows access at paths with the/test/* prefixor the*/info suffix:

apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata:  name: tester  namespace: defaultspec:  selector:    matchLabels:      app: products  action: ALLOW  rules:  - to:    - operation:        paths: ["/test/*", "*/info"]

Exclusion matching

To match negative conditions likenotValues in thewhen field,notIpBlocks in thesource field,notPorts in theto field, Cloud Service Meshsupports exclusion matching. The following example requires a valid requestprincipals, which is derived from JWT authentication, if the request path isnot/healthz. Thus, the policy excludes requests to the/healthz path fromthe JWT authentication:

apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata:  name: disable-jwt-for-healthz  namespace: defaultspec:  selector:    matchLabels:      app: products  action: ALLOW  rules:  - to:    - operation:        notPaths: ["/healthz"]    from:    - source:        requestPrincipals: ["*"]

Reject plaintext requests

In Cloud Service Mesh, auto mTLS is enabled by default. With auto mTLS, aclient sidecar proxy automatically detects if the server has a sidecar. Theclient sidecar sends mTLS to workloads with sidecars and sends plaintext toworkloads without sidecars. For the best security, we recommend that youenable STRICT mTLS.

If you are unable to enable mTLS withSTRICT mode for a workload ornamespace, you can:

• create an authorization policy to explicitly allow traffic with non-emptynamespaces or non-emptyprincipals, or
• reject traffic with emptynamespaces orprincipals.

Because thenamespaces andprincipals can only be extracted with a mTLSrequest, these policies effectively reject any plaintext traffic.

The following policy denies the request if the principal in the request isempty (which is the case for plaintext requests). The policy allowsrequests if the principal is non-empty. The["*"] means a non-empty match, andusing withnotPrincipals means matching on empty principal.

apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata:  name: require-mtls  namespace:NAMESPACEspec:  action: DENY  rules:  - from:    - source:        notPrincipals: ["*"]

Authorization policy precedence

You can configure separateALLOW andDENY authorization policies, but youneed to understand the policy precedence and default behavior to make sure thatthe policies do what you want. The following diagram describes the policyprecedence.

The example policies in the following sections illustrate some of the defaultbehavior and the situations where you might find them useful.

Allow nothing

The following example shows anALLOW policy that doesn't match anything. Bydefault, if there are no otherALLOW policies, requests are alwaysdenied.

apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata:  name: allow-nothingspec:  action: ALLOW

It is a good security practice to start with the allow-nothing policy andincrementally add moreALLOW policies to open more access to a workload.

Deny all access

The following example shows aDENY policy that matches everything. BecauseDENY policies are evaluated beforeALLOW policies, all requests are deniedeven if there is anALLOW policy that matches the request.

apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata:  name: deny-allspec:  action: DENY  rules:  - {}

A deny-all policy is useful if you want to temporarily disable all access to aworkload.

Allow all access

The following example shows anALLOW policy that matches everything, andallows full access to a workload. The allow-all policy makes otherALLOWpolicies useless because it always allows the request.

apiVersion:security.istio.io/v1beta1kind:AuthorizationPolicymetadata:name:allow-allspec:action:ALLOWrules:-{}

An allow-all policy is useful if you want to temporarily expose full access toa workload. If there are anyDENY policies, requests could still be deniedsinceDENY policies are evaluated beforeALLOW policies.

Best practices

1. Create a Kubernetes service account for each service, and specify theservice account in the Deployment. For example:

   apiVersion: v1kind: ServiceAccountmetadata:  name: frontend-sa  namespace: demo---apiVersion: apps/v1kind: Deploymentmetadata:  name: frontend  namespace:demospec:  selector:    matchLabels:      app: frontend  template:    metadata:      labels:        app: frontend    spec:      serviceAccountName: frontend-sa    ...

2. Start with anallow-nothing policy and incrementallyadd moreALLOW policies to open more access to workloads.

3. If you are using JWTs for your service:

   1. Create aDENY policy to block unauthenticated requests, for example:

      apiVersion: security.istio.io/v1beta1kind: AuthorizationPolicymetadata:  name: requireJWT  namespace: adminspec:  action: DENY  rules:  -  from:    - source:        notRequestPrincipals: ["*"]

   2. Apply an allow-nothing policy.

   3. DefineALLOW policies for each workload. For examples, seeJWT Token.

What's next

Learn more about Cloud Service Mesh security features:

• Configuring Cloud Service Mesh user authentication
• Configuring audit policies for your services
• Configuring transport security
• Integrating Identity-Aware Proxy with Cloud Service Mesh
• Best Practices for using Cloud Service Mesh egress gateways on GKE clusters

Learn more about authorization policies from the Istio documentation:

• Authorization policy examples
• Authorization policy troubleshooting