update security doc with evaluation order, common patterns, shoter task names and some small updates (#9127)

* update security doc with evaluation order, common patterns, shoter task names and some small updates

* update

* update

* add link

* update

* update

* fix lint

* Apply suggestions from code review

Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

* update

* Apply suggestions from code review

Co-authored-by: John Howard <howardjohn@google.com>

Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>
Co-authored-by: John Howard <howardjohn@google.com>

content/en/docs/concepts/security/index.md

@@ -527,7 +527,8 @@ the following benefits:
 
 ### Authorization architecture
 
-Each Envoy proxy runs an authorization engine that authorizes requests at
+The authorization policy enforces access control to the inbound traffic in the
+server side Envoy proxy. Each Envoy proxy runs an authorization engine that authorizes requests at
 runtime. When a request comes to the proxy, the authorization engine evaluates
 the request context against the current authorization policies, and returns the
 authorization result, either `ALLOW` or `DENY`. Operators specify Istio
@@ -545,11 +546,12 @@ an authorization policy to the workloads to enforce access control.
 For workloads without authorization policies applied, Istio doesn't enforce
 access control allowing all requests.
 
-Authorization policies support both `ALLOW` and `DENY` actions. The deny
-policies take precedence over allow policies. If any allow policies are applied
-to a workload, access to that workload is denied by default, unless explicitly
-allowed by the rule in the policy. When you apply multiple authorization
-policies to the same workload, Istio applies them additively.
+Authorization policies support `ALLOW`, `DENY` and `CUSTOM` actions. The policy precedence is
+`CUSTOM`, `DENY` and `ALLOW`. The following graph shows the policy precedence in detail:
+
+{{< image width="50%" link="./authz-eval.png" caption="Authorization Policy Precedence">}}
+
+When you apply multiple authorization policies to the same workload, Istio applies them additively.
 
 ### Authorization policies
 
@@ -750,34 +752,54 @@ spec:
         notRequestPrincipals: ["*"]
 {{< /text >}}
 
-#### Allow-all and default deny-all authorization policies
+#### `allow-nothing`, `deny-all` and `allow-all` policy
 
-The following example shows a simple `allow-all` authorization policy that
-allows full access to all workloads in the `default` namespace.
+The following example shows an `ALLOW` policy that matches nothing. If there are no other `ALLOW` policies, requests
+will always be denied because of the "deny by default" behavior.
+
+It is a good security practice to start with the `allow-nothing` policy and incrementally add more `ALLOW` policies to open more
+access to the workload.
 
 {{< text yaml >}}
 apiVersion: security.istio.io/v1beta1
 kind: AuthorizationPolicy
 metadata:
-  name: allow-all
-  namespace: default
+  name: allow-nothing
 spec:
-  action: ALLOW
-  rules:
-  - {}
+  # This matches nothing, the action defaults to ALLOW if not specified.
+  {}
 {{< /text >}}
 
-The following example shows a policy that doesn't allow any access to all
-workloads in the `admin` namespace.
+The following example shows a `DENY` policy that explicitly denies all access. It will always deny the request even if
+there is another `ALLOW` policy allowing the request because the `DENY` policy takes precedence over the `ALLOW` policy.
+This is useful if you want to temporarily disable all access to the workload.
 
 {{< text yaml >}}
 apiVersion: security.istio.io/v1beta1
 kind: AuthorizationPolicy
 metadata:
   name: deny-all
-  namespace: admin
 spec:
-  {}
+  action: DENY
+  # This matches everything.
+  rules:
+  - {}
+{{< /text >}}
+
+The following example shows an `ALLOW` policy that allows full access to the workload. It will make other `ALLOW` policies
+useless as it will always allow the request. It might be useful if you want to temporarily expose full access to the
+workload. Note the request could still be denied due to `CUSTOM` and `DENY` policies.
+
+{{< text yaml >}}
+apiVersion: security.istio.io/v1beta1
+kind: AuthorizationPolicy
+metadata:
+  name: allow-all
+spec:
+  action: ALLOW
+  # This matches everything.
+  rules:
+  - {}
 {{< /text >}}
 
 #### Custom conditions
@@ -812,8 +834,7 @@ spec:
      values: ["v1", "v2"]
 {{< /text >}}
 
-The supported `key` values of a condition are listed in the
-[conditions page](/docs/reference/config/security/conditions/).
+The supported `key` values of a condition are listed on the [conditions page](/docs/reference/config/security/conditions/).
 
 #### Authenticated and unauthenticated identity
 
@@ -870,10 +891,8 @@ MongoDB. In this case, you configure the authorization policy in the same way
 you did for the HTTP workloads. The difference is that certain fields and
 conditions are only applicable to HTTP workloads. These fields include:
 
-- The `request_principals` field in the source section of the authorization
-   policy object
-- The `hosts`, `methods` and `paths` fields in the operation section of the
-   authorization policy object
+- The `request_principals` field in the source section of the authorization policy object
+- The `hosts`, `methods` and `paths` fields in the operation section of the authorization policy object
 
 The supported conditions are listed in the
 [conditions page](/docs/reference/config/security/conditions/).
@@ -918,3 +937,16 @@ the authorization policy:
 
 Mutual TLS is not required if you don't use any of the above fields in the
 authorization policy.
+
+## Learn more
+
+After learning the basic concepts, there are more resources to review:
+
+- Try out the security policy by following the [authentication](/docs/tasks/security/authentication/authn-policy)
+  and [authorization](/docs/tasks/security/authorization) tasks.
+
+- Learn some security [policy examples](/docs/ops/configuration/security/security-policy-examples) that could be
+  used to improve security in your mesh.
+
+- Read [common problems](/docs/ops/common-problems/security-issues/) to better troubleshoot security policy issues
+  when something goes wrong.

content/en/docs/ops/common-problems/security-issues/index.md

@@ -140,6 +140,8 @@ authorization policy in effect by running `istioctl x authz check POD-NAME.POD-N
 
 - The `AUDIT` action does not enforce access control and will not deny the request at any cases.
 
+Read [authorization implicit enablement](/docs/concepts/security/#implicit-enablement) for more details of the evaluation order.
+
 ## Ensure Istiod accepts the policies
 
 Istiod converts and distributes your authorization policies to the proxies. The following steps help

content/en/docs/ops/configuration/security/security-policy-examples/index.md

@@ -0,0 +1,160 @@
+---
+title: Security policy examples
+description: Shows common examples of using Istio security policy.
+weight: 60
+owner: istio/wg-security-maintainers
+test: no
+---
+
+## Background
+
+This page shows common patterns of using Istio security policies. You may find them useful in your deployment or use this
+as a quick reference to example policies.
+
+The policies demonstrated here are just examples and and require changes to adapt to your actual environment
+before applying.
+
+Also read the [authentication](/docs/tasks/security/authentication/authn-policy) and
+[authorization](/docs/tasks/security/authorization) tasks for a hands-on tutorial of using the security policy in
+more detail.
+
+### Require different JWT issuer per host
+
+JWT validation is common on the ingress gateway and you may want to require different JWT issuers for different
+hosts. You can use the authorization policy for fine grained JWT validation in addition to the
+[request authentication](/docs/tasks/security/authentication/authn-policy/#end-user-authentication) policy.
+
+Use the following policy if you want to allow access to the given hosts if JWT principal matches. Access to other hosts
+will always be denied.
+
+{{< text yaml >}}
+apiVersion: security.istio.io/v1beta1
+kind: AuthorizationPolicy
+metadata:
+  name: jwt-per-host
+  namespace: istio-system
+spec:
+  selector:
+    matchLabels:
+      istio: ingressgateway
+  action: ALLOW
+  rules:
+  - from:
+    - source:
+        hosts: ["example.com", "*.example.com"]
+        # the JWT token must have issuer with suffix "@example.com"
+        requestPrincipals: ["*@example.com"]
+    - source:
+        hosts: [".another.org", "*.another.org"]
+        # the JWT token must have issuer with suffix "@another.org"
+        requestPrincipals: ["*@another.org"]
+{{< /text >}}
+
+### Namespace isolation
+
+The following policy allows traffic only from the namespace `foo`. In other words, it isolates the namespace `foo` from other
+namespaces. This requires you have already enabled mTLS.
+
+{{< text yaml >}}
+apiVersion: security.istio.io/v1beta1
+kind: AuthorizationPolicy
+metadata:
+  name: foo-isolation
+  namespace: foo
+spec:
+  action: ALLOW
+  rules:
+  - from:
+    - source:
+        namespaces: ["foo"]
+{{< /text >}}
+
+### Namespace isolation with ingress exception
+
+The following policy allows traffic only from the namespace `foo` and also from the ingress gateway. This requires you have already enabled mTLS.
+
+{{< text yaml >}}
+apiVersion: security.istio.io/v1beta1
+kind: AuthorizationPolicy
+metadata:
+  name: ns-isolation-except-ingress
+  namespace: foo
+spec:
+  action: ALLOW
+  rules:
+  - from:
+    - source:
+        namespaces: ["foo"]
+    - source:
+        principals: ["cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"]
+{{< /text >}}
+
+### Require mTLS in authorization layer (defense in depth)
+
+You have configured `PeerAuthentication` to `STRICT` but want to make sure the traffic is indeed protected by mTLS with
+an extra check in the authorization layer, i.e., defense in depth.
+
+The following policy denies the request if the principal is empty. The principal will be empty if plain text is used.
+In other words, the policy allows requests if the principal is non-empty.
+`"*"` means non-empty match and using with `notPrincipals` means matching on empty principal.
+
+{{< text yaml >}}
+apiVersion: security.istio.io/v1beta1
+kind: AuthorizationPolicy
+metadata:
+  name: require-mtls
+  namespace: foo
+spec:
+  action: DENY
+  rules:
+  - from:
+    - source:
+        notPrincipals: ["*"]
+{{< /text >}}
+
+### Require mandatory authorization check with `DENY` policy
+
+You can use the `DENY` policy if you want to require mandatory authorization check that must be satisfied and cannot be
+bypassed by another more permissive `ALLOW` policy. This works because the `DENY` policy takes precedence over the
+`ALLOW` policy and could deny a request early before `ALLOW` policies.
+
+Use the following policy to enforce mandatory JWT validation in addition to the [request authentication](/docs/tasks/security/authentication/authn-policy/#end-user-authentication) policy.
+The policy denies the request if the request principal is empty. The request principal will be empty if JWT validation failed.
+In other words, the policy allows requests if the request principal is non-empty.
+"*" means non-empty match and using with `notRequestPrincipals` means matching on empty request principal.
+
+{{< text yaml >}}
+apiVersion: security.istio.io/v1beta1
+kind: AuthorizationPolicy
+metadata:
+  name: require-jwt
+  namespace: istio-system
+spec:
+  selector:
+    matchLabels:
+      istio: ingressgateway
+  action: DENY
+  rules:
+  - from:
+    - source:
+        notRequestPrincipals: ["*"]
+{{< /text >}}
+
+Similarly, Use the following policy to require mandatory namespace isolation and also allow requests from ingress gateway.
+The policy denies the request if the namespace is not `foo` and the principal is not `cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account`.
+In other words, the policy allows the request only if the namespace is `foo` or the principal is `cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account`.
+
+{{< text yaml >}}
+apiVersion: security.istio.io/v1beta1
+kind: AuthorizationPolicy
+metadata:
+  name: ns-isolation-except-ingress
+  namespace: foo
+spec:
+  action: DENY
+  rules:
+  - from:
+    - source:
+        notNamespaces: ["foo"]
+        notPrincipals: ["cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"]
+{{< /text >}}

content/en/docs/tasks/security/authorization/authz-custom/index.md

@@ -1,5 +1,5 @@
 ---
-title: External authorization with custom action
+title: External Authorization
 description: Shows how to integrate and delegate access control to an external authorization system.
 weight: 35
 keywords: [security,access-control,rbac,authorization,custom, opa, oauth, oauth2-proxy]
@@ -15,7 +15,9 @@ to delegate the access control to an external authorization system. This can be
 
 ## Before you begin
 
-* Read the [authorization concept](/docs/concepts/security/#authorization).
+Before you begin this task, do the following:
+
+* Read the [Istio authorization concepts](/docs/concepts/security/#authorization).
 
 * Follow the [Istio installation guide](/docs/setup/install/istioctl/) to install Istio.
 
@@ -28,8 +30,8 @@ to delegate the access control to an external authorization system. This can be
     {{< text bash >}}
     $ kubectl create ns foo
     $ kubectl label ns foo istio-injection=enabled
-    $ kubectl apply -f samples/httpbin/httpbin.yaml -n foo
-    $ kubectl apply -f samples/sleep/sleep.yaml -n foo
+    $ kubectl apply -f @samples/httpbin/httpbin.yaml@ -n foo
+    $ kubectl apply -f @samples/sleep/sleep.yaml@ -n foo
     {{< /text >}}
 
 * Verify that `sleep` can access `httpbin` with the following command:

content/en/docs/tasks/security/authorization/authz-deny/index.md

@@ -1,5 +1,5 @@
 ---
-title: Authorization policies with a deny action
+title: Explicit Deny
 description: Shows how to set up access control to deny traffic explicitly.
 weight: 40
 keywords: [security,access-control,rbac,authorization,deny]
@@ -7,14 +7,15 @@ owner: istio/wg-security-maintainers
 test: yes
 ---
 
-This task shows you how to set up Istio authorization policy that denies HTTP traffic
-in an Istio mesh. Learn more in our [authorization concept page](/docs/concepts/security/#authorization).
+This task shows you how to set up Istio authorization policy of `DENY` action to explicitly deny traffic in an Istio
+mesh. This is different from the `ALLOW` action because the `DENY` action has higher priority and will not be
+bypassed by any `ALLOW` actions.
 
 ## Before you begin
 
-Before tackling this task you must perform the following actions:
+Before you begin this task, do the following:
 
-* Read the [authorization concept](/docs/concepts/security/#authorization).
+* Read the [Istio authorization concepts](/docs/concepts/security/#authorization).
 
 * Follow the [Istio installation guide](/docs/setup/install/istioctl/) to install Istio.
 
@@ -26,8 +27,8 @@ Before tackling this task you must perform the following actions:
 
     {{< text bash >}}
     $ kubectl create ns foo
-    $ kubectl apply -f <(istioctl kube-inject -f samples/httpbin/httpbin.yaml) -n foo
-    $ kubectl apply -f <(istioctl kube-inject -f samples/sleep/sleep.yaml) -n foo
+    $ kubectl apply -f <(istioctl kube-inject -f @samples/httpbin/httpbin.yaml@) -n foo
+    $ kubectl apply -f <(istioctl kube-inject -f @samples/sleep/sleep.yaml@) -n foo
     {{< /text >}}
 
 * Verify that `sleep` talks to `httpbin` with the following command:

content/en/docs/tasks/security/authorization/authz-http/index.md

@@ -1,5 +1,5 @@
 ---
-title: Authorization for HTTP traffic
+title: HTTP Traffic
 description: Shows how to set up access control for HTTP traffic.
 weight: 10
 keywords: [security,access-control,rbac,authorization]
@@ -10,14 +10,13 @@ owner: istio/wg-security-maintainers
 test: yes
 ---
 
-This task shows you how to set up Istio authorization for HTTP traffic in an Istio mesh.
-Learn more in our [authorization concept page](/docs/concepts/security/#authorization).
+This task shows you how to set up Istio authorization policy of `ALLOW` action for HTTP traffic in an Istio mesh.
 
 ## Before you begin
 
-The activities in this task assume that you:
+Before you begin this task, do the following:
 
-* Read the [authorization concept](/docs/concepts/security/#authorization).
+* Read the [Istio authorization concepts](/docs/concepts/security/#authorization).
 
 * Follow the [Istio installation guide](/docs/setup/install/istioctl/) to install Istio with mutual TLS enabled.
 
@@ -47,10 +46,10 @@ and namespace in the policies.
 
 Using Istio, you can easily setup access control for {{< gloss "workload" >}}workloads{{< /gloss >}}
 in your mesh. This task shows you how to set up access control using Istio authorization.
-First, you configure a simple `deny-all` policy that rejects all requests to the workload,
+First, you configure a simple `allow-nothing` policy that rejects all requests to the workload,
 and then grant more access to the workload gradually and incrementally.
 
-1. Run the following command to create a `deny-all` policy in the `default` namespace.
+1. Run the following command to create a `allow-nothing` policy in the `default` namespace.
    The policy doesn't have a `selector` field, which applies the policy to every workload in the
    `default` namespace. The `spec:` field of the policy has the empty value `{}`.
    That value means that no traffic is permitted, effectively denying all requests.
@@ -60,7 +59,7 @@ and then grant more access to the workload gradually and incrementally.
     apiVersion: security.istio.io/v1beta1
     kind: AuthorizationPolicy
     metadata:
-      name: deny-all
+      name: allow-nothing
       namespace: default
     spec:
       {}
@@ -88,6 +87,7 @@ and then grant more access to the workload gradually and incrementally.
       selector:
         matchLabels:
           app: productpage
+      action: ALLOW
       rules:
       - to:
         - operation:
@@ -121,6 +121,7 @@ and then grant more access to the workload gradually and incrementally.
       selector:
         matchLabels:
           app: details
+      action: ALLOW
       rules:
       - from:
         - source:
@@ -146,6 +147,7 @@ and then grant more access to the workload gradually and incrementally.
       selector:
         matchLabels:
           app: reviews
+      action: ALLOW
       rules:
       - from:
         - source:
@@ -179,6 +181,7 @@ and then grant more access to the workload gradually and incrementally.
       selector:
         matchLabels:
           app: ratings
+      action: ALLOW
       rules:
       - from:
         - source:
@@ -200,7 +203,7 @@ and then grant more access to the workload gradually and incrementally.
 1. Remove all authorization policies from your configuration:
 
     {{< text bash >}}
-    $ kubectl delete authorizationpolicy.security.istio.io/deny-all
+    $ kubectl delete authorizationpolicy.security.istio.io/allow-nothing
     $ kubectl delete authorizationpolicy.security.istio.io/productpage-viewer
     $ kubectl delete authorizationpolicy.security.istio.io/details-viewer
     $ kubectl delete authorizationpolicy.security.istio.io/reviews-viewer

content/en/docs/tasks/security/authorization/authz-http/snips.sh

@@ -25,7 +25,7 @@ kubectl apply -f - <<EOF
 apiVersion: security.istio.io/v1beta1
 kind: AuthorizationPolicy
 metadata:
-  name: deny-all
+  name: allow-nothing
   namespace: default
 spec:
   {}
@@ -43,6 +43,7 @@ spec:
   selector:
     matchLabels:
       app: productpage
+  action: ALLOW
   rules:
   - to:
     - operation:
@@ -61,6 +62,7 @@ spec:
   selector:
     matchLabels:
       app: details
+  action: ALLOW
   rules:
   - from:
     - source:
@@ -82,6 +84,7 @@ spec:
   selector:
     matchLabels:
       app: reviews
+  action: ALLOW
   rules:
   - from:
     - source:
@@ -103,6 +106,7 @@ spec:
   selector:
     matchLabels:
       app: ratings
+  action: ALLOW
   rules:
   - from:
     - source:
@@ -114,7 +118,7 @@ EOF
 }
 
 snip_clean_up_1() {
-kubectl delete authorizationpolicy.security.istio.io/deny-all
+kubectl delete authorizationpolicy.security.istio.io/allow-nothing
 kubectl delete authorizationpolicy.security.istio.io/productpage-viewer
 kubectl delete authorizationpolicy.security.istio.io/details-viewer
 kubectl delete authorizationpolicy.security.istio.io/reviews-viewer

content/en/docs/tasks/security/authorization/authz-http/test.sh

@@ -94,7 +94,7 @@ kubectl apply -f samples/bookinfo/networking/virtual-service-reviews-v3.yaml
 _wait_for_istio virtualservice default reviews
 
 snip_configure_access_control_for_workloads_using_http_traffic_1
-_wait_for_istio authorizationpolicy default deny-all
+_wait_for_istio authorizationpolicy default allow-nothing
 
 # Verify we don't have access.
 verify 403 "RBAC: access denied"

content/en/docs/tasks/security/authorization/authz-ingress/index.md

@@ -1,6 +1,6 @@
 ---
-title: Authorization on Ingress Gateway
-description: How to set up access control on an ingress gateway.
+title: Ingress Gateway
+description: Shows how to set up access control on an ingress gateway.
 weight: 50
 keywords: [security,access-control,rbac,authorization,ingress,ip,allowlist,denylist]
 owner: istio/wg-security-maintainers
@@ -13,7 +13,7 @@ This task shows you how to enforce IP-based access control on an Istio ingress g
 
 Before you begin this task, do the following:
 
-* Read the [Authorization conceptual documentation](/docs/concepts/security/#authorization).
+* Read the [Istio authorization concepts](/docs/concepts/security/#authorization).
 
 * Install Istio using the [Istio installation guide](/docs/setup/install/istioctl/).
 

content/en/docs/tasks/security/authorization/authz-jwt/index.md

@@ -1,6 +1,6 @@
 ---
-title: Authorization with JWT
-description: How to set up access control with JWT in Istio.
+title: JWT Token
+description: Shows how to set up access control for JWT token.
 weight: 30
 keywords: [security,authorization,jwt,claim]
 aliases:
@@ -16,9 +16,11 @@ and list-of-string typed JWT claims.
 
 ## Before you begin
 
-Before you begin this task, perform the following actions:
+Before you begin this task, do the following:
 
-* Read [Authorization](/docs/concepts/security/#authorization) and [Authentication](/docs/concepts/security/#authentication).
+* Complete the [Istio end user authentication task](/docs/tasks/security/authentication/authn-policy/#end-user-authentication).
+
+* Read the [Istio authorization concepts](/docs/concepts/security/#authorization).
 
 * Install Istio using [Istio installation guide](/docs/setup/install/istioctl/).
 

content/en/docs/tasks/security/authorization/authz-tcp/index.md

@@ -1,6 +1,6 @@
 ---
-title: Authorization for TCP traffic
-description: How to set up access control for TCP traffic.
+title: TCP Traffic
+description: Shows how to set up access control for TCP traffic.
 weight: 20
 keywords: [security,access-control,rbac,tcp,authorization]
 aliases:
@@ -9,7 +9,7 @@ owner: istio/wg-security-maintainers
 test: yes
 ---
 
-This task shows you how to set up Istio authorization for TCP traffic in an Istio mesh.
+This task shows you how to set up Istio authorization policy for TCP traffic in an Istio mesh.
 
 ## Before you begin
 

content/en/docs/tasks/security/authorization/authz-td-migration/index.md

@@ -1,5 +1,5 @@
 ---
-title: Authorization Policy Trust Domain Migration
+title: Trust Domain Migration
 description: Shows how to migrate from one trust domain to another without changing authorization policy.
 weight: 60
 keywords: [security,access-control,rbac,authorization,trust domain, migration]
@@ -10,14 +10,16 @@ test: yes
 This task shows you how to migrate from one trust domain to another without changing authorization policy.
 
 In Istio 1.4, we introduce an alpha feature to support {{< gloss >}}trust domain migration{{</ gloss >}} for authorization policy. This means if an
- Istio mesh needs to change its {{< gloss >}}trust domain{{</ gloss >}}, the authorization policy doesn't need to be changed manually.
- In Istio, if a {{< gloss >}}workload{{</ gloss >}} is running in namespace `foo` with the service account `bar`, and the trust domain of the system is `my-td`,
- the identity of said workload is `spiffe://my-td/ns/foo/sa/bar`. By default, the Istio mesh trust domain is `cluster.local`,
- unless you specify it during the installation.
+Istio mesh needs to change its {{< gloss >}}trust domain{{</ gloss >}}, the authorization policy doesn't need to be changed manually.
+In Istio, if a {{< gloss >}}workload{{</ gloss >}} is running in namespace `foo` with the service account `bar`, and the trust domain of the system is `my-td`,
+the identity of said workload is `spiffe://my-td/ns/foo/sa/bar`. By default, the Istio mesh trust domain is `cluster.local`,
+unless you specify it during the installation.
 
 ## Before you begin
 
-1. Read the [authorization concept guide](/docs/concepts/security/#authorization).
+Before you begin this task, do the following:
+
+1. Read the [Istio authorization concepts](/docs/concepts/security/#authorization).
 
 1. Install Istio with a custom trust domain and mutual TLS enabled.