feat: RFC 8705 mutual-TLS client authentication for CF app instance identity

docs/UAA-Client-Authentication.md

@@ -6,7 +6,7 @@ In [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-2.3.1) the password
 or better the process of checking its possession means the authentication process.
 
 The secrets can be passed to a server in different ways. It can happen through the HTTP header and/or the body. In the case that an Authorization header is used,
-the encoding of the secret needs to be done according to the RFC 6749. UAA fixed this behavior with https://github.com/cloudfoundry/uaa/issues/778.
+the encoding of the secret needs to be done according to the RFC 6749. UAA fixed this behavior with <https://github.com/cloudfoundry/uaa/issues/778>.
 The OIDC standard defines additional authentication mechanisms, see [section 9](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication).
 The usage of secrets via client_secret_basic and client_secret_post is straightforward to set up and to use, however, if system-to-system communication is
 in use, this can be a security problem because it will be hard to change secrets in running systems. The use of many secrets is not
@@ -17,10 +17,12 @@ standards define token-based authentication mechanisms for OAuth2 clients. They
 * tls_client_auth [RFC 8705](https://www.rfc-editor.org/rfc/rfc8705)
 
 ## New methods
+
 The new methods are based on asymmetric trust relation, so that the keys are divided into a private and a public one. The private key should never leave
 the original system, but only the public key should be exchanged.
 
 ### private_key_jwt (Partly finished)
+
 The standard private_key_jwt is similar to the existing JWT bearer flow, but JWT bearer is for user principle propagation, whereas private_key_jwt
 is used for client authentication only. The used technics are similar and therefore the trust model is similar. Both usages are specified in the same
 [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523.txt). The JWT bearer trust is based on parameters tokenKey and/or tokenKeyUrl parameter, part of the
@@ -29,7 +31,7 @@ of public keys, and this set can contain many keys because each key has its own
 a dynamic token key URI. OIDC has defined the parameter jwks_uri for this already. The structure of the keys is defined with [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).
 UAA provides its own jwks_uri with endpoint /token_keys. The content of this endpoint is [JWKS](https://datatracker.ietf.org/doc/html/rfc7517#section-5).
 
-The content of the JWT (parameter client_assertion) can be different. The standards define the difference. The [OIDC core standard](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) 
+The content of the JWT (parameter client_assertion) can be different. The standards define the difference. The [OIDC core standard](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
  simplifies the structure so that issuer and subject are the client_id of the authenticated OAuth2 client. The key rotation is supported with
 jwks_uri, which retrieves the JWK. You can only have one JWKS_URI by the client. For the [RFC 7523 from OAuth2 standard](https://www.rfc-editor.org/info/rfc7523) the
 structure is more complex, but with seperated issuer and subject there can be more than one entry of federated credential.
@@ -45,11 +47,131 @@ The new parameter for federated Credentials in UAA clients is (Work in progress
 
 * jwt_creds
 
-### tls_client_auth (Planned Feature)
-Not yet defined a release date.
+### tls_client_auth ([RFC 8705](https://www.rfc-editor.org/rfc/rfc8705))
+
+Mutual-TLS client authentication: a client presents an X.509 certificate at the TLS layer
+instead of a `client_secret` or a signed JWT assertion. UAA validates the certificate against
+a per-client trusted CA and, optionally, derives JWT claims from the certificate's subject
+fields (e.g. mapping a Cloud Foundry app instance identity certificate to `app_guid`/
+`space_guid`/`org_guid` claims).
+
+The client is authenticated on the fixed dedicated endpoint, `/oauth/mtls/token`, rather than
+the regular `/oauth/token`. A nonblank `tls-client-auth-ca` is the sole inbound mTLS selector
+for a client. This dedicated endpoint routing is what's scoped: only requests to
+`/oauth/mtls/token` attempt to authenticate the caller via a presented client certificate --
+requests to `/oauth/token` are never affected by this.
+
+The underlying TLS-layer change, however, is **connector-wide, not per-endpoint**: enabling
+this feature (`uaa.mtls-enabled`) reconfigures the whole embedded Tomcat connector to request a
+client certificate on *every* TLS handshake to this UAA instance (`certificateVerification=
+optionalNoCA`; see `MtlsClientAuthTomcatCustomizer`), regardless of which path the request is
+ultimately routed to. Any TLS client connecting to any UAA endpoint will therefore be prompted
+for a certificate during the handshake -- well-behaved clients (including Go's `crypto/tls`)
+simply respond with an empty `Certificate` message if they have no certificate matching the
+connector's advertised acceptable-issuer list, so this doesn't outright break other endpoints,
+but it is a deployment-wide TLS-layer change, not one isolated to `/oauth/mtls/token`.
+
+#### Deployment topology
+
+UAA itself only ever sees the certificate presented by its *immediate* TLS peer -- whatever
+that happens to be depends on how UAA is deployed:
+
+* **Behind a Gorouter** with `forwarded_client_cert: sanitize_set` (the typical Cloud
+  Foundry deployment): the Gorouter terminates the client's TLS connection, validates it, and
+  forwards the client's certificate to UAA in the `X-Forwarded-Client-Cert` header over its own
+  backend mTLS connection. Here, UAA's immediate TLS peer is the Gorouter itself, not the
+  original client.
+* **Direct connections**, e.g. an app connecting straight to UAA over BOSH DNS
+  (`uaa.service.cf.internal`) where Application Security Groups permit it, bypassing the
+  Gorouter entirely: UAA's immediate TLS peer *is* the original client.
+
+`tls-client-auth-trusted-proxy-ca` determines which of the two topologies a *given client* uses --
+the two are mutually exclusive per client, not two ways of satisfying the same requirement:
+
+* **Not configured:** the client is direct-connection-only. UAA always authenticates it using the
+  certificate its immediate TLS peer actually presented during the handshake, and never consults
+  the `X-Forwarded-Client-Cert` header at all (even if one happens to be present -- e.g. noise
+  from an unrelated proxy in the network path).
+* **Configured:** the client is proxy-only. UAA requires the `X-Forwarded-Client-Cert` header to
+  actually be present, and the genuine TLS peer that presented it to validate against this CA,
+  before trusting the header-derived certificate. A direct connection (no header) is always
+  rejected for this client, even if its own certificate happens to validate against the configured
+  CA.
+
+An operator who needs both a Gorouter-fronted access pattern and a direct-connection access
+pattern for what is conceptually "the same" workload registers **two separate UAA clients** -- one
+with `tls-client-auth-trusted-proxy-ca` set (proxy path) and one without it (direct path) -- rather
+than expecting one client to accept either.
+
+#### Scoping a client to a specific org/space/app
+
+Because Cloud Foundry's Diego instance-identity CA is shared across every app instance in a
+foundation, any two clients configured with the same `tls-client-auth-ca` can otherwise
+authenticate each other's certificates -- PKIX chain validation alone only proves a certificate
+was issued by the configured CA, not that it belongs to *this* client specifically. Configure
+`tls-client-auth-required-claims` to close this gap for a client that should only be reachable by
+a specific subset of apps:
+
+```yaml
+tls-client-auth-claim-mappings:
+  - field: subject_ou
+    pattern: "space:(.+)"
+    claim: space_guid
+tls-client-auth-required-claims:
+  space_guid: <specific-space-guid>
+```
+
+An operator who needs both a broadly-scoped client (e.g. the generic `instance-identity` client,
+accepting any app in the foundation) and a narrowly-scoped one (e.g. limited to a single space)
+registers them as two separate UAA clients, only the latter configuring
+`tls-client-auth-required-claims`.
+
+#### Configuration
+
+Per-client properties (set via the client-admin API, `oauth.clients` bootstrap, or the client
+admin UI, alongside the client's other properties such as `authorized-grant-types`):
+
+The mTLS token endpoint is fixed at `/oauth/mtls/token`; it is not configurable. A client opts
+into mTLS by configuring a nonblank `tls-client-auth-ca`. The client must use that endpoint and
+present a certificate whose chain validates to the configured CA; no separate
+`token-endpoint-auth-method` property is used or supported.
+
+| Property | Required | Description |
+|----------|----------|--------------|
+| `tls-client-auth-ca` | yes | PEM-encoded CA certificate. This is the per-client mTLS selector: requests to the fixed `/oauth/mtls/token` endpoint authenticate with a presented leaf certificate only when it chains to this CA. |
+| `tls-client-auth-trusted-proxy-ca` | conditional | PEM-encoded CA certificate the Gorouter's own backend mTLS certificate must chain to. Configuring this switches the client to the Gorouter/XFCC-forwarding-only topology (requiring the `X-Forwarded-Client-Cert` header) -- see "Deployment topology" above. Leave unset for a direct-connection-only client. |
+| `tls-client-auth-required-claims` | no | Map of `claimName -> requiredValue`, checked against the values already produced by `tls-client-auth-claim-mappings`. When configured, authentication fails unless every entry matches exactly -- e.g. `{space_guid: "<specific-space-guid>"}` scopes this client to a single CF space, even if other clients share the same `tls-client-auth-ca`. |
+| `tls-client-auth-claim-mappings` | no | List of `{field, pattern, claim}` mappings from certificate subject fields (`subject_cn`, `subject_ou`, `subject_o`) to JWT claim names. `subject_cn` and `subject_o` map their values directly; `pattern` is supported only for `subject_ou`, where it extracts a capture group. Patterns are UAA administrator-controlled configuration and are evaluated on every mTLS authentication request; use efficient Java regular expressions and avoid patterns with catastrophic backtracking. |
+| `tls-client-auth-sub-template` | no | Template string rendered (using the mapped claim values) to produce the JWT `sub` claim. |
+| `tls-client-auth-aud-templates` | no | List of template strings rendered to produce the JWT `aud` claim. |
+
+Example (Gorouter-fronted; a Cloud Foundry app instance identity certificate mapped to
+`cf_instance_guid`/`app_guid`/`space_guid`/`org_guid` claims):
+
+```yaml
+tls-client-auth-ca: <instance-identity CA certificate PEM>
+tls-client-auth-trusted-proxy-ca: <Gorouter backend mTLS CA certificate PEM, e.g. service_cf_internal_ca>
+tls-client-auth-claim-mappings:
+  - field: subject_cn
+    claim: cf_instance_guid
+  - field: subject_ou
+    pattern: "app:(.+)"
+    claim: app_guid
+  - field: subject_ou
+    pattern: "space:(.+)"
+    claim: space_guid
+  - field: subject_ou
+    pattern: "organization:(.+)"
+    claim: org_guid
+```
+
+For the direct-connection topology described above, omit `tls-client-auth-trusted-proxy-ca`
+entirely rather than setting it -- configuring it at all switches this client to proxy-only.
 
 ## Configs
+
 Here is a brief example of the `clients` section:
+
 ```yaml
 oauth:
   clients:
@@ -78,9 +200,11 @@ oauth:
           ]
         }
 ```
+
 The example configuration above with jwks_uri enables continuous trust to a running UAA.
 
 Here is a brief example of the oauth providers section, where UAA is acting as a client.
+
 ```yaml
 login:
   oauth:
@@ -99,12 +223,13 @@ login:
 The option jwtClientAuthentication creates during the proxy flow a client assertion which is based on OIDC private_key_jwt.
 
 ### Developer implementation
+
 As a developer, you should use the [UAA documentation](https://docs.cloudfoundry.org/api/uaa/version/77.18.0/index.html#token). There is a description
-about the new parameters client_assertion and client_assertion_type. In addition, you can check in the retrieved access_token tokens for the existence 
-of claim client_auth_method with value private_key_jwt, (client_auth_method=private_key). This claim should guarantee the used method of client 
-authentication. Tokens without this claim are authenticated with secrets. There might be use-cases where a stronger authentication mechanism is 
+about the new parameters client_assertion and client_assertion_type. In addition, you can check in the retrieved access_token tokens for the existence
+of claim client_auth_method with value private_key_jwt, (client_auth_method=private_key). This claim should guarantee the used method of client
+authentication. Tokens without this claim are authenticated with secrets. There might be use-cases where a stronger authentication mechanism is
 required.
 
 ### Production use
 
-The support of private_key_jwt (according to OIDC) for a production system is given with the end of Q4/2024. 
+The support of private_key_jwt (according to OIDC) for a production system is given with the end of Q4/2024.

docs/UAA-Configuration-Reference.md

@@ -126,6 +126,7 @@ or `$CLOUDFOUNDRY_CONFIG_PATH/uaa.yml`.
 | <a href="#oauthclientautoapprove"><img src="images/click-me.png" width="14" height="14"/></a> `oauth.client.autoapprove` | `[]`| Clients auto-approved for all scopes|
 | <a href="#oauthuserauthorities"><img src="images/click-me.png" width="14" height="14"/></a> `oauth.user.authorities` | (see details)| Default authorities for new users|
 | <a href="#clientmaxcount"><img src="images/click-me.png" width="14" height="14"/></a> `clientMaxCount` | `500`| Max clients returned by list endpoint|
+| <a href="#uaamtls-enabled"><img src="images/click-me.png" width="14" height="14"/></a> `uaa.mtls-enabled` | `false`| Enables RFC 8705 mutual-TLS client authentication|
 
 ### Password Policy
 
@@ -1221,6 +1222,39 @@ client admin API (`/oauth/clients`).
 
 ---
 
+### `uaa.mtls-enabled`
+
+**Default:** `false`
+**Source:** `@Value("${uaa.mtls-enabled:false}")` in [`SpringServletXmlBeansConfiguration`](../server/src/main/java/org/cloudfoundry/identity/uaa/SpringServletXmlBeansConfiguration.java), [`ClientAdminBootstrap`](../server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminBootstrap.java), [`ZoneEndpointsClientDetailsValidator`](../server/src/main/java/org/cloudfoundry/identity/uaa/zone/ZoneEndpointsClientDetailsValidator.java), [`MtlsClientAuthTomcatCustomizer`](../server/src/main/java/org/cloudfoundry/identity/uaa/web/tomcat/MtlsClientAuthTomcatCustomizer.java)
+**Type:** `boolean`
+
+Master switch enabling RFC 8705 mutual-TLS client authentication (`tls_client_auth`)
+deployment-wide. This is **connector-wide**: it affects every TLS connection to this UAA
+instance, not just requests to the mTLS token endpoint (`/oauth/mtls/token`).
+[`SpringServletXmlBeansConfiguration`](../server/src/main/java/org/cloudfoundry/identity/uaa/SpringServletXmlBeansConfiguration.java)
+also uses this value to wire
+[`ClientAdminEndpointsValidator`](../server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java)'s
+`mtlsEnabled` constructor argument.
+
+When `true`, the embedded Tomcat connector is reconfigured to request a client certificate
+during every TLS handshake (`certificateVerification=optionalNoCA`), without validating it
+against any CA at the transport layer -- the trust decision is deferred entirely to per-client
+application logic (see [`docs/UAA-Client-Authentication.md`](UAA-Client-Authentication.md) for
+the per-client `tls-client-auth-*` properties). Enabling this also switches the connector to the
+FIPS BouncyCastle JSSE provider, required for TLS 1.3 client-certificate support (OpenJDK's JSSE
+does not implement server-side TLS 1.3 post-handshake client-certificate requests).
+
+When `false` (the default), no client certificate is requested at the TLS layer at all, and any
+client configured with a `tls-client-auth-ca` property fails validation at creation/update time.
+
+```yaml
+uaa.mtls-enabled: true
+```
+
+[Back to table](#oauth-clients--users)
+
+---
+
 ### `password.policy.global.minLength`
 
 **Default:** `0`

gradle/libs.versions.toml

@@ -17,6 +17,7 @@ jacoco = "4.0.2"
 jackson = "3.1.5"
 jackson2 = "2.21.5"
 jacocoAgent = "0.8.15"
+javaBuildpackClientCertificateMapper = "2.0.1"
 nimbusJwt = "10.9.1"
 opensaml = "5.2.3"
 orgJson = "20260814"
@@ -70,6 +71,9 @@ bouncyCastlePkixFips = { module = "org.bouncycastle:bcpkix-fips", version.ref =
 bouncyCastleTlsFips = { module = "org.bouncycastle:bctls-fips", version.ref = "bouncyCastleTls" }
 bouncyCastleUtilFips = { module = "org.bouncycastle:bcutil-fips", version.ref = "bouncyCastleUtil" }
 
+# CloudFoundry
+javaBuildpackClientCertificateMapper = { module = "org.cloudfoundry:java-buildpack-client-certificate-mapper-jakarta", version.ref = "javaBuildpackClientCertificateMapper" }
+
 # Eclipse JGit
 eclipseJgit = { module = "org.eclipse.jgit:org.eclipse.jgit", version.ref = "eclipseJgit" }
 
@@ -164,6 +168,7 @@ springBootStarterMail = { module = "org.springframework.boot:spring-boot-starter
 springBootStarterTest = { module = "org.springframework.boot:spring-boot-starter-test" }
 springBootStarterTomcatRuntime = { module = "org.springframework.boot:spring-boot-starter-tomcat-runtime" }
 springBootStarterWeb = { module = "org.springframework.boot:spring-boot-starter-web" }
+springBootTomcat = { module = "org.springframework.boot:spring-boot-tomcat" }
 springBootTransaction = { module = "org.springframework.boot:spring-boot-transaction" }
 
 # Spring Data

model/src/main/java/org/cloudfoundry/identity/uaa/account/OpenIdConfiguration.java

@@ -1,10 +1,14 @@
 package org.cloudfoundry.identity.uaa.account;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 import org.cloudfoundry.identity.uaa.constants.ClientAuthentication;
 
+import java.util.Arrays;
+import java.util.Map;
+
 @Data
 @NoArgsConstructor
 public class OpenIdConfiguration {
@@ -19,7 +23,7 @@ public class OpenIdConfiguration {
     private String tokenUrl;
 
     @JsonProperty("token_endpoint_auth_methods_supported")
-    private String[] tokenAMR = new String[]{ClientAuthentication.CLIENT_SECRET_BASIC, ClientAuthentication.CLIENT_SECRET_POST, ClientAuthentication.PRIVATE_KEY_JWT};
+    private String[] tokenAMR = new String[]{ClientAuthentication.CLIENT_SECRET_BASIC, ClientAuthentication.CLIENT_SECRET_POST, ClientAuthentication.PRIVATE_KEY_JWT, ClientAuthentication.TLS_CLIENT_AUTH};
 
     @JsonProperty("token_endpoint_auth_signing_alg_values_supported")
     private String[] tokenEndpointAuthSigningValues = new String[]{"RS256", "HS256"};
@@ -67,12 +71,25 @@ public class OpenIdConfiguration {
     @JsonProperty("code_challenge_methods_supported")
     private String[] codeChallengeMethodsSupported = new String[]{"S256", "plain"};
 
+    @JsonProperty("mtls_endpoint_aliases")
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    private Map<String, String> mtlsEndpointAliases;
+
     public OpenIdConfiguration(final String contextPath, final String issuer) {
+        this(contextPath, issuer, true);
+    }
+
+    public OpenIdConfiguration(final String contextPath, final String issuer, final boolean mtlsEnabled) {
         this.issuer = issuer;
         this.authUrl = contextPath + "/oauth/authorize";
         this.tokenUrl = contextPath + "/oauth/token";
         this.userInfoUrl = contextPath + "/userinfo";
         this.jwksUri = contextPath + "/token_keys";
         this.logoutEndpoint = contextPath + "/logout.do";
+        if (!mtlsEnabled) {
+            this.tokenAMR = Arrays.stream(this.tokenAMR)
+                    .filter(method -> !ClientAuthentication.TLS_CLIENT_AUTH.equals(method))
+                    .toArray(String[]::new);
+        }
     }
 }