After you deploy, you must register the identity-aware domain in
+<%= vars.app_runtime_abbr %> with cf create-shared-domain … --enforce-route-policies
+(see Register the domain). Developers then map routes
+on that domain and manage route policies.
+$ bosh -e YOUR-ENV -d cf deploy cf-deployment/cf-deployment.yml \ + -o cf-deployment/operations/enable-identity-aware-routing.yml \ + --vars-store deployment-vars.yml \ + -v system_domain=YOUR-SYSTEM-DOMAIN ++ +The ops file generates new credentials into your vars-store on deploy, so no manual +certificate creation is required for the default `*.apps.identity` domain. For more +information, see [Certificates and certificate authorities](#certificates). + +Two companion ops files extend this configuration: + +* To trust the generated CA on the cflinuxfs5 stack, see +[Trusting the CA in cflinuxfs5](#cflinuxfs5). + +* To use a domain other than `*.apps.identity`, see +[Use an operator-provided domain](#custom-domain). + +You can view the ops file in the `cf-deployment` repository: +[enable-identity-aware-routing.yml](https://github.com/cloudfoundry/cf-deployment/blob/master/operations/enable-identity-aware-routing.yml). + +## What the ops file configures + +The ops file applies the following changes to your deployment manifest: + +
| Configures | +Details | +
|---|---|
| BOSH DNS alias | +Resolves the *.apps.identity wildcard to the Gorouter instances
+(alias label _.apps.identity, the BOSH DNS wildcard form). |
+
Gorouter router.domains |
+Adds *.apps.identity as an mTLS domain that validates caller
+certificates against diego_instance_identity_ca, with forwarding mode
+sanitize_set and XFCC format envoy. |
+
| Gorouter server (SNI) certificate | +Appends a *.apps.identity server certificate to
+router.tls_pem (variable apps_identity_router_tls), served
+through SNI. |
+
| CA trust | +Injects apps_identity_ca into the cflinuxfs4 rootfs trust store and
+the Diego rep, so app containers trust the Gorouter's server certificate
+on the domain. |
+
| Certificate / CA | +Role | +
|---|---|
diego_instance_identity_ca (existing) |
+Validates the caller's client certificate at the Gorouter. The ops file sets it
+as the domain's ca_certs. This CA already exists in <%= vars.app_runtime_abbr %>;
+the ops file does not generate it. |
+
apps_identity_ca (generated) |
+Signs the Gorouter's server certificate for *.apps.identity. It is
+trusted inside app containers and the Diego rep. |
+
apps_identity_router_tls (generated) |
+The Gorouter's server (SNI) certificate and key for *.apps.identity,
+signed by apps_identity_ca and appended to router.tls_pem. |
+
The ops file generates apps_identity_ca and
+apps_identity_router_tls into the vars-store on deploy. Back up the
+vars-store as you would for any other generated credential.
| Field | +Description | +Values (default) | +
|---|---|---|
name |
+The domain to require mTLS on. The wildcard must be the leftmost label
+(for example, *.apps.identity) and matches any single label; a
+non-wildcard domain must match the request host exactly. |
+Domain string | +
ca_certs |
+PEM CA bundle used to validate caller (client) certificates on the domain. | +PEM | +
forwarded_client_cert |
+How the Gorouter forwards the client certificate in the
+X-Forwarded-Client-Cert (XFCC) header. |
+always_forward (default), forward,
+sanitize_set |
+
xfcc_format |
+Format of the XFCC header: raw is the full base64-encoded
+certificate (~1.5 KB); envoy is the compact
+Hash=<sha256>;Subject="<DN>" format (~300 bytes). |
+raw (default), envoy |
+
A domain listed in router.domains always requires a valid
+client certificate signed by the domain's configured CA, regardless of the global
+router.client_cert_validation setting.
+$ bosh -e YOUR-ENV -d cf deploy cf-deployment/cf-deployment.yml \ + -o cf-deployment/operations/experimental/add-cflinuxfs5.yml \ + -o cf-deployment/operations/enable-identity-aware-routing.yml \ + -o cf-deployment/operations/enable-identity-aware-routing-cflinuxfs5.yml \ + --vars-store deployment-vars.yml ++ +
This ops file requires add-cflinuxfs5.yml to be
+applied first. Applying it on a foundation without the cflinuxfs5 stack fails the
+deploy by design, signaling that the stack ops file is missing.
+$ bosh -e YOUR-ENV -d cf deploy cf-deployment/cf-deployment.yml \ + -o cf-deployment/operations/enable-identity-aware-routing.yml \ + -o cf-deployment/operations/use-operator-provided-identity-routing-domain.yml \ + -v identity_routing_domain=apps.example.com \ + --vars-store deployment-vars.yml ++ +This override applies to the BOSH DNS alias, the Gorouter domain name, and the +generated server certificate's common name and subject alternative name. The +`cf-deployment` repository ships an example vars file you can adapt: +`cf-deployment/operations/example-vars-files/vars-use-operator-provided-identity-routing-domain.yml`. + +Whatever domain you choose, you register that same domain in +<%= vars.app_runtime_abbr %> in the next section. + +## Register the domain in <%= vars.app_runtime_abbr %> + +After the deploy succeeds, register the identity-aware domain in +<%= vars.app_runtime_abbr %> so that developers can map routes and add policies on it. +The domain name must match the one configured in the ops file (`apps.identity` by +default): + +
+$ cf create-shared-domain apps.identity --enforce-route-policies ++ +The `--enforce-route-policies` flag turns on default-deny route-policy enforcement for +the domain and is immutable once set. You can optionally add `--scope (any|org|space)` +to narrow who may be named as a policy source; `--scope` is valid only together with +`--enforce-route-policies`. + +Once the domain exists, developers map routes on it and manage route policies. See +Configuring identity-aware routing. + +## Related reading + +* Identity-aware routing—how +identity-aware routing works. + +* Configuring identity-aware routing—the +developer how-to for mapping routes and managing route policies. + +* Deploying Cloud Foundry. + +* The `cf-deployment` ops files: +[operations](https://github.com/cloudfoundry/cf-deployment/tree/master/operations). + +* RFC-0055: +[Identity-Aware Routing for Gorouter](https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0055-identity-aware-routing-for-gorouter.md).