Docs: identity-aware routing concepts (RFC-0055)

http-routing.html.md.erb

@@ -228,6 +228,10 @@ data path must trust that the back-end component has not allowed the header to b
 If you configure the load balancer to terminate TLS and set the XFCC header from the received client certificate, you must also configure the load balancer to
 strip this header if it is present in client requests. This configuration is required to prevent spoofing of the client certificate.
 
+<p class="note">
+To require and validate client certificates on a <strong>per-domain</strong> basis and enforce identity-based route policies, see <a href="identity-aware-routing.html">Identity-aware routing</a>.
+</p>
+
 The following sections describe supported deployment configurations.
 
 <% if vars.platform_code == 'CF' %>

images/identity-aware-routing-arch.mmd

@@ -0,0 +1,14 @@
+flowchart LR
+    A["App A<br/>presents client<br/>identity cert"]
+    GR["GoRouter<br/>per-domain mTLS<br/>on *.apps.identity"]
+    V{"Validate and<br/>authorize"}
+    B["App B<br/>route: my-api.apps.identity"]
+    D[("Diego<br/>instance identity CA")]
+    CC[("Cloud Controller<br/>route policies")]
+
+    A -->|"1 - HTTPS plus client identity cert"| GR
+    GR --> V
+    D -.->|"trust: instance identity CA"| V
+    CC -.->|"sync: route policies, default-deny"| V
+    V -->|"2 - cert valid, OU app/space/org allowed; forward plus XFCC"| B
+    V -.->|"denied: 403"| A

images/identity-aware-routing-policy.mmd

@@ -0,0 +1,8 @@
+flowchart LR
+    A["App A"]
+    B["App B<br/>billing.apps.identity"]
+    C["App C<br/>reports.apps.identity"]
+
+    A -->|"allowed: policy A to B"| B
+    A -->|"allowed: policy A to C"| C
+    B -.->|"denied by default"| C