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

[rkoster]

Summary

Implements RFC 8705 mutual-TLS client
authentication for Cloud Foundry app instance identity, enabling workload identity
federation with AWS, GCP, Azure, and any OIDC-aware service.

CF app instances already receive a short-lived X.509 certificate from the Diego
Cell (instance.crt / instance.key). This change lets an app exchange that cert
for a UAA JWT containing verified app_guid, space_guid, org_guid, and
cf_instance_guid claims — without secrets or user credentials.

How it works

CF app ──cert──▶ Gorouter (sanitize_set) ──XFCC──▶ UAA /oauth/mtls/token
                                                         │
                                            ClientCertificateMapper
                                            (XFCC → X509Certificate attr)
                                                         │
                                            ClientDetailsAuthenticationProvider
                                            (tls_client_auth: PKIX chain validation)
                                                         │
                                            MtlsClaimsEnhancer
                                            (cert OU → app/space/org_guid claims)
                                                         │
                                            ◀── JWT with CF identity claims ──

Changes (this PR — 18 commits)

Model layer:

• ClientAuthentication: add tls_client_auth constant
• TokenConstants: add CLIENT_AUTH_TLS_CLIENT_AUTH
• TlsClientAuthConfiguration: per-client CA PEM + claim-mapping model
• UaaClientDetails: add tlsClientAuthConfiguration field
• OpenIdConfiguration: add mtls_endpoint_aliases to OIDC discovery

Server layer:

• ClientDetailsAuthenticationProvider: isTlsClientAuth(), validateTlsClientAuth(), getTlsClientAuthConfiguration() — handles in-memory, Map (Jackson), and flat String PEM (BOSH) config forms
• TlsClientAuthentication: PKIX cert chain validation against per-client CA
• ClientCertificateMapper registration: SpringServletXmlFiltersConfiguration registers the java-buildpack-client-certificate-mapper-jakarta filter for /oauth/mtls/* to materialise X-Forwarded-Client-Cert as a jakarta.servlet.request.X509Certificate attribute
• ClientCredentialsTokenGranter: allow tls_client_auth alongside client_secret
• MtlsClaimsEnhancer: UaaTokenEnhancer that reads cert subject OU fields and maps them to JWT claims per per-client configuration; handles DB-loaded clients (reads additionalInformation directly) and Diego multi-valued RDNs
• FilterChainOrder.OAUTH_11 + mtlsTokenEndpointSecurity: dedicated security filter chain for /oauth/mtls/token with CSRF disabled
• UaaTokenEndpoint: add /oauth/mtls/token to @RequestMapping
• OIDC discovery: expose mtls_endpoint_aliases

Deployment notes

Requires the Gorouter to be configured with forwarded_client_cert: sanitize_set
so it validates the TLS session cert and injects it as X-Forwarded-Client-Cert.

The UAA client for an app must be configured with:

token-endpoint-auth-method: tls_client_auth
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

tls-client-auth-trusted-proxy-ca switches this client to the Gorouter/XFCC-forwarding-only
topology: UAA then requires the X-Forwarded-Client-Cert header to actually be present and its
immediate TLS peer to have presented a certificate signed by that CA during the handshake --
preventing a direct caller (bypassing the Gorouter) from replaying a harvested certificate it
doesn't hold the private key for, or a direct connection from being silently accepted instead.
For a client that connects to UAA directly (e.g. permitted by Application Security Group
configuration, bypassing the Gorouter), omit this property entirely -- configuring it at all
makes the client reject direct connections. See
docs/UAA-Client-Authentication.md
for both cases; two separate UAA clients are needed to support both patterns for the same
workload.

Proof of concept

End-to-end verified on a real CF deployment: a Go app pushes its Diego instance cert
to POST /oauth/mtls/token, and the returned JWT contains:

{
  "app_guid":         "b0bff1c2-a258-4060-981d-601f22e6bcf8",
  "space_guid":       "02700fa7-8db7-4598-b015-9a5fc73d4656",
  "org_guid":         "8deb6c47-8460-4501-8a86-246b774d97e4",
  "cf_instance_guid": "86bf36e4-af79-4d7a-6484-0d89",
  "client_auth_method": "tls_client_auth",
  "cnf": { "x5t#S256": "rk4P4d0DXNJDpZeOotKRUzmoaomqSqPQn8OzyKQhMuw" }
}

All GUIDs verified against cf app, cf org, and cf space --guid.

Related

• RFC: UAA-RFC8705-001 (design doc)
• uaa-release PR: see companion PR in cloudfoundry/uaa-release
• RFC 8705: https://www.rfc-editor.org/rfc/rfc8705

[Copilot]

Pull request overview

This PR adds RFC 8705 mutual-TLS client authentication support for Cloud Foundry app instance identity by introducing a dedicated /oauth/mtls/token endpoint, validating instance certificates against per-client CA configuration, and enriching issued JWTs with CF identity claims derived from certificate subject fields. It also updates OIDC discovery to advertise mTLS endpoint aliases and tls_client_auth as a supported token endpoint authentication method.

Changes:

• Introduces /oauth/mtls/token with a dedicated Spring Security filter chain and request-to-certificate mapping via ClientCertificateMapper.
• Adds TLS client certificate validation (TlsClientAuthentication) and a token enhancer (MtlsClaimsEnhancer) to emit cnf.x5t#S256 plus configured subject-derived claims.
• Extends client auth method support across model/constants and OIDC discovery metadata (tls_client_auth, mtls_endpoint_aliases).

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
server/src/test/java/org/cloudfoundry/identity/uaa/oauth/tls/TlsClientAuthenticationTest.java	Adds unit coverage for null inputs and malformed CA handling in TLS cert validation.
server/src/test/java/org/cloudfoundry/identity/uaa/oauth/tls/MtlsClaimsEnhancerTest.java	Verifies OU/CN claim extraction and cnf.x5t#S256 behavior for mTLS tokens.
server/src/test/java/org/cloudfoundry/identity/uaa/oauth/tls/ClientCertificateMapperFilterTest.java	Confirms servlet filter registration for mapping XFCC to request X509Certificate attribute on /oauth/mtls/*.
server/src/test/java/org/cloudfoundry/identity/uaa/oauth/provider/client/ClientCredentialsTokenGranterTests.java	Ensures tls_client_auth is allowed for client_credentials.
server/src/test/java/org/cloudfoundry/identity/uaa/authentication/UaaClientAuthenticationProviderTest.java	Updates provider wiring to include TlsClientAuthentication.
server/src/test/java/org/cloudfoundry/identity/uaa/authentication/ClientDetailsAuthenticationProviderTests.java	Adds tests for mtls path detection and TLS config deserialization behavior.
server/src/test/java/org/cloudfoundry/identity/uaa/account/OpenIdConnectEndpointsTest.java	Validates discovery document includes mtls_endpoint_aliases.token_endpoint.
server/src/main/java/org/cloudfoundry/identity/uaa/web/FilterChainOrder.java	Adds a new security chain order slot (OAUTH_11) for the mTLS token endpoint chain.
server/src/main/java/org/cloudfoundry/identity/uaa/SpringServletXmlFiltersConfiguration.java	Registers ClientCertificateMapper filter for /oauth/mtls/*.
server/src/main/java/org/cloudfoundry/identity/uaa/oauth/token/UaaTokenEndpoint.java	Expands token endpoint mapping to include /oauth/mtls/token.
server/src/main/java/org/cloudfoundry/identity/uaa/oauth/tls/TlsClientAuthentication.java	Adds per-client CA-based PKIX validation and request certificate extraction helper.
server/src/main/java/org/cloudfoundry/identity/uaa/oauth/tls/MtlsClaimsEnhancer.java	Implements JWT enrichment from cert subject + cnf.x5t#S256 for the mTLS flow.
server/src/main/java/org/cloudfoundry/identity/uaa/oauth/provider/client/ClientCredentialsTokenGranter.java	Allows tls_client_auth as a valid auth method for client credentials.
server/src/main/java/org/cloudfoundry/identity/uaa/oauth/beans/OauthEndpointSecurityConfiguration.java	Adds dedicated security filter chain for /oauth/mtls/token (stateless + CSRF disabled).
server/src/main/java/org/cloudfoundry/identity/uaa/oauth/beans/OauthEndpointBeanConfiguration.java	Wires TlsClientAuthentication into ClientDetailsAuthenticationProvider bean construction.
server/src/main/java/org/cloudfoundry/identity/uaa/authentication/ClientDetailsAuthenticationProvider.java	Detects mTLS path, validates certs, and parses per-client TLS configuration from additional info.
server/src/main/java/org/cloudfoundry/identity/uaa/account/OpenIdConnectEndpoints.java	Populates mtls_endpoint_aliases in OIDC discovery.
server/build.gradle.kts	Adds dependency on the Gorouter client certificate mapper (Jakarta).
model/src/test/resources/org/cloudfoundry/identity/uaa/account/OpenIdConfiguration.json	Updates fixture to include tls_client_auth in supported auth methods.
model/src/test/java/org/cloudfoundry/identity/uaa/constants/ClientAuthenticationTest.java	Adds tests for tls_client_auth support, secret requirements, and validity rules.
model/src/test/java/org/cloudfoundry/identity/uaa/client/UaaClientDetailsTest.java	Adds JSON round-trip test for TLS client auth config and adjusts hashCode assertion.
model/src/test/java/org/cloudfoundry/identity/uaa/client/TlsClientAuthConfigurationTest.java	Adds unit tests for TLS auth config JSON round-tripping and equality semantics.
model/src/test/java/org/cloudfoundry/identity/uaa/account/OpenIdConfigurationTests.java	Updates supported auth methods expectations and adds tests for mTLS aliases field.
model/src/main/java/org/cloudfoundry/identity/uaa/oauth/token/TokenConstants.java	Exposes CLIENT_AUTH_TLS_CLIENT_AUTH constant.
model/src/main/java/org/cloudfoundry/identity/uaa/constants/ClientAuthentication.java	Adds TLS_CLIENT_AUTH constant and updates supported/valid method logic and calculation.
model/src/main/java/org/cloudfoundry/identity/uaa/client/UaaClientDetails.java	Introduces tlsClientAuthConfiguration field and includes it in equals/hashCode.
model/src/main/java/org/cloudfoundry/identity/uaa/client/TlsClientAuthConfiguration.java	Adds model for trusted CA PEM + claim mapping configuration.
model/src/main/java/org/cloudfoundry/identity/uaa/account/OpenIdConfiguration.java	Adds mtls_endpoint_aliases and includes tls_client_auth in supported methods.

[Copilot]

Pull request overview

Copilot reviewed 32 out of 32 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 59 out of 59 changed files in this pull request and generated 1 comment.

Suppressed comments (11)

server/src/main/java/org/cloudfoundry/identity/uaa/account/OpenIdConnectEndpoints.java:40

• The mTLS alias is emitted even when uaa.mtls-enabled is false (the default), while that setting prevents mTLS client configuration and leaves Tomcat unable to request peer certificates. Discovery will therefore claim tls_client_auth support on deployments where it cannot work. Gate both this alias and token_endpoint_auth_methods_supported on the feature flag.

        String contextPath = getServerContextPath(request);
        OpenIdConfiguration conf = new OpenIdConfiguration(contextPath, getTokenEndpoint());
        conf.setMtlsEndpointAliases(Map.of("token_endpoint", contextPath + mtlsEndpointPath));

server/src/main/java/org/cloudfoundry/identity/uaa/oauth/tls/TlsClientAuthentication.java:457

• Rdn.toAttributes() represents repeated attributes in one multi-valued RDN (for example OU=app:x+OU=space:y) as one Attribute with multiple values, but attr.get() returns only one of them. Consequently extractOus loses the remaining OU values despite this helper claiming multi-valued-RDN support. Iterate attr.getAll() when collecting OUs.

                Attribute attr = attrs.next();
                if (attr.getID().equalsIgnoreCase(type)) {
                    Object value = attr.get();
                    return value == null ? null : value.toString();

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:444

• Compilation alone is insufficient because matchFirstOu only emits group(1). A valid pattern with no capture group is accepted here but can never produce its configured claim, potentially making required-claim authentication fail permanently. Reject patterns whose matcher has fewer than one capture group.

                try {
                    Pattern.compile(pattern);

server/src/main/java/org/cloudfoundry/identity/uaa/account/OpenIdConnectEndpoints.java:23

• mtls.endpoint only changes discovery metadata; the controller mapping and security matcher remain hard-coded to /oauth/mtls/token. Any override therefore advertises a non-existent endpoint. Remove this configurability or use the same setting for routing/security as well.

This issue also appears on line 38 of the same file.

    @Value("${mtls.endpoint:/oauth/mtls/token}")
    private String mtlsEndpointPath = "/oauth/mtls/token";

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminBootstrap.java:223

• Bootstrapped clients only run the feature-gate check, so malformed claim mappings/templates accepted here bypass the new validation used by the admin and zone APIs. For example, an invalid regex is persisted and later throws during token issuance. Invoke validateTlsClientAuthClaimConfig before persisting bootstrap clients too.

            client.setAdditionalInformation(info);
            ClientAdminEndpointsValidator.checkMtlsClientConfigAllowed(client.getAdditionalInformation(), mtlsEnabled, clientId);

server/src/main/java/org/cloudfoundry/identity/uaa/zone/ZoneEndpointsClientDetailsValidator.java:60

• A mere key presence is treated as a usable TLS credential. A null/blank tls-client-auth-ca therefore bypasses the required-secret check, but later TlsClientAuthConfiguration.isConfigured rejects it, creating a secretless client that can never authenticate. Base this decision on a parsed, nonblank CA configuration.
  server/src/main/java/org/cloudfoundry/identity/uaa/oauth/tls/TlsClientAuthentication.java:236
• pattern is accepted for all three fields, but extraction applies it only to subject_ou; patterns configured for subject_cn or subject_o are silently ignored and the unfiltered value is emitted. Apply the pattern consistently to all supported subject fields (or reject it for fields where it is unsupported).

This issue also appears on line 454 of the same file.

            String value = switch (mapping.getField()) {
                case "subject_cn" -> cn;
                case "subject_ou" -> matchFirstOu(ous, mapping.getPattern());
                case "subject_o"  -> extractRdnValue(dn, "O");
                default -> null;

server/src/main/java/org/cloudfoundry/identity/uaa/web/tomcat/MtlsClientAuthTomcatCustomizer.java:109

• If a provider named BCJSSE is already registered in non-FIPS mode, this method silently reuses it, despite the connector and repository requiring the FIPS provider. Validate the existing provider's type and isFipsMode() value and fail fast rather than serving TLS through a non-FIPS implementation.
  docs/UAA-Client-Authentication.md:121
• The setup instructions omit the required deployment-wide uaa.mtls-enabled: true switch. With the documented steps as written, the default is false and the validators reject every client containing these mTLS properties. Document the switch here and add it to docs/UAA-Configuration-Reference.md as required for new configuration properties.

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`):

docs/UAA-Client-Authentication.md:125

• token-endpoint-auth-method is documented as required, but no client model, validator, bootstrap path, or authentication provider consumes this property; repository search finds it only in this document. Following the example merely stores an unused additional-information entry. Remove it from the required configuration or implement and validate the registration metadata.

| `token-endpoint-auth-method: tls_client_auth` | yes | Selects mTLS client authentication for this client. |

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:399

• Returning whenever the mappings key is absent skips validation of the other three properties. For example, tls-client-auth-required-claims without mappings is accepted even though none of its keys can ever be extracted, so every authentication for that client fails. Continue with an empty declared-claims set and validate any templates/required claims that are present.

This issue also appears on line 443 of the same file.

    public static void validateTlsClientAuthClaimConfig(Map<String, Object> additionalInfo, String clientId) {
        if (additionalInfo == null
                || !additionalInfo.containsKey(TlsClientAuthConfiguration.TLS_CLIENT_AUTH_CLAIM_MAPPINGS)) {
            return;

[Copilot]

Pull request overview

Copilot reviewed 59 out of 59 changed files in this pull request and generated 3 comments.

Suppressed comments (6)

Previously missed (3) — in code that hasn't changed since the last review.

server/src/main/java/org/cloudfoundry/identity/uaa/account/OpenIdConnectEndpoints.java:40

• The discovery response advertises tls_client_auth and an mTLS alias even when uaa.mtls-enabled is at its default false. In that state Tomcat never requests a peer certificate and validators reject mTLS client configuration, so consumers are told an unusable authentication method is supported. Gate both this alias and token_endpoint_auth_methods_supported on the feature flag.

        conf.setMtlsEndpointAliases(Map.of("token_endpoint", contextPath + mtlsEndpointPath));

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminBootstrap.java:223

• Bootstrap clients bypass validateTlsClientAuthClaimConfig, so malformed mappings such as an invalid regex are persisted and later throw during token issuance. The documentation explicitly supports oauth.clients bootstrap configuration; run the same validation used by the admin and zone APIs before registering the client.

            ClientAdminEndpointsValidator.checkMtlsClientConfigAllowed(client.getAdditionalInformation(), mtlsEnabled, clientId);

docs/UAA-Client-Authentication.md:61

• This explanation says the dedicated path avoids changing other clients, but MtlsClientAuthTomcatCustomizer sets optionalNoCA on every SSL host config of the connector. TLS happens before an HTTP path is known, so enabling the feature requests an optional client certificate on every HTTPS connection; only application-level processing is path-scoped. Document that connector-wide operational effect.

The client is authenticated on a dedicated endpoint, `/oauth/mtls/token`, rather than the
regular `/oauth/token`. This lets the endpoint be given a servlet-container TLS configuration
that requests a client certificate ("mutual TLS"), without changing behavior for every other
client on `/oauth/token`.

server/src/main/java/org/cloudfoundry/identity/uaa/oauth/tls/TlsClientAuthentication.java:235

• pattern is accepted for every mapping field, but it is ignored for subject_cn and subject_o; additionally, an OU pattern with no capture group is accepted by validation yet silently emits no claim. Apply consistent pattern extraction to all supported fields (or reject patterns for unsupported fields) and require a capture group when a pattern is configured.

            String value = switch (mapping.getField()) {
                case "subject_cn" -> cn;
                case "subject_ou" -> matchFirstOu(ous, mapping.getPattern());
                case "subject_o"  -> extractRdnValue(dn, "O");

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:413

• Returning immediately when the mappings key is absent also skips validation of dependent settings. A client can therefore persist tls-client-auth-required-claims with no mappings (making authentication permanently fail), or templates with unresolved placeholders (silently dropping sub/aud). Continue validation with an empty declared-claims set so literal templates remain valid while unresolved dependencies are rejected.

    public static void validateTlsClientAuthClaimConfig(Map<String, Object> additionalInfo, String clientId) {
        if (additionalInfo == null
                || !additionalInfo.containsKey(TlsClientAuthConfiguration.TLS_CLIENT_AUTH_CLAIM_MAPPINGS)) {
            return;

server/src/main/java/org/cloudfoundry/identity/uaa/zone/ZoneEndpointsClientDetailsValidator.java:60

• Checking only containsKey treats a null or blank tls-client-auth-ca as a usable alternative credential. Such input bypasses the zone API's client_secret requirement, but TlsClientAuthConfiguration.isConfigured later rejects it, leaving an unusable secretless client. Base this decision on a nonblank/configured CA value instead of key presence.

[Copilot]

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated 5 comments.

Suppressed comments (9)

Previously missed (8) — in code that hasn't changed since the last review.

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminBootstrap.java:223

• The documented oauth.clients bootstrap path bypasses validateTlsClientAuthClaimConfig. It can therefore persist invalid fields, regexes, templates, or required-claim references that the admin APIs reject; those values later produce missing claims or token-time failures. Apply the same validation before registering the client.

            ClientAdminEndpointsValidator.checkMtlsClientConfigAllowed(client.getAdditionalInformation(), mtlsEnabled, clientId);

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:413

• This early return also accepts tls-client-auth-sub-template, tls-client-auth-aud-templates, or tls-client-auth-required-claims when no mappings key exists. Such templates can never resolve, while required claims make every authentication fail. Reject dependent claim settings unless mappings are present; only a configuration with none of these keys should be a no-op.

        if (additionalInfo == null
                || !additionalInfo.containsKey(TlsClientAuthConfiguration.TLS_CLIENT_AUTH_CLAIM_MAPPINGS)) {
            return;

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:458

• A regex with no capture group is accepted here, but matchFirstOu emits a value only when groupCount() >= 1 and then reads group 1. Thus a syntactically valid pattern such as ^app:.*$ is accepted at registration yet silently produces no claim. Either reject patterns without a capture group here or define runtime semantics that use the full match.

                    Pattern.compile(pattern);

server/src/main/java/org/cloudfoundry/identity/uaa/oauth/tls/TlsClientAuthentication.java:249

• pattern is applied only to subject_ou; mappings for subject_cn and subject_o ignore a supplied pattern and copy the complete value. The validator and documentation allow a pattern on every mapping, so accepted CN/O configurations can emit a different claim than configured (and fail required-claim checks). Apply the same matching semantics to all supported fields, or reject patterns for fields where they are unsupported.

            String value = switch (mapping.getField()) {
                case "subject_cn" -> cn;
                case "subject_ou" -> matchFirstOu(ous, mapping.getPattern());
                case "subject_o"  -> extractRdnValue(dn, "O");
                default -> null;

server/src/main/java/org/cloudfoundry/identity/uaa/account/OpenIdConnectEndpoints.java:23

• mtls.endpoint only changes the URL published in discovery; the MVC mapping, security matcher, and servlet-filter path guards remain hard-coded to /oauth/mtls/token. Any non-default value therefore advertises a nonexistent endpoint. Remove this configurability or wire one validated path through every route/matcher.

    @Value("${mtls.endpoint:/oauth/mtls/token}")
    private String mtlsEndpointPath = "/oauth/mtls/token";

docs/UAA-Client-Authentication.md:125

• This documents token-endpoint-auth-method as required and as selecting mTLS, but the repository has no code that reads this client property; bootstrap merely leaves it as unused additional information, and authentication is selected from the request path plus CA presence. Either implement persistence/enforcement of this metadata or remove the property from the required configuration so operators are not relying on a no-op.

| `token-endpoint-auth-method: tls_client_auth` | yes | Selects mTLS client authentication for this client. |

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:497

• Null and blank audience templates are silently accepted here, but MtlsClaimsEnhancer calls renderTemplate(template, ...) unconditionally; a null element throws at template.length(), while a blank element can produce an invalid empty aud value. Reject null/blank list entries during client validation.

                for (String template : audTemplates) {
                    if (template != null && !template.isBlank()) {
                        checkTemplateLength(template, TlsClientAuthConfiguration.TLS_CLIENT_AUTH_AUD_TEMPLATES, clientId);
                        validateTemplatePlaceholders(template, declaredClaims,
                                TlsClientAuthConfiguration.TLS_CLIENT_AUTH_AUD_TEMPLATES, clientId);
                    }

docs/UAA-Client-Authentication.md:129

• The field list omits the supported subject_o value, even though validation and extraction accept it. Operators following this table cannot discover or correctly configure organization-subject mappings; include subject_o in the documented set.

| `tls-client-auth-claim-mappings` | no | List of `{field, pattern, claim}` mappings from certificate subject fields (`subject_cn`, `subject_ou`) to JWT claim names, optionally extracting a capture group via `pattern`. |

model/src/main/java/org/cloudfoundry/identity/uaa/client/UaaClientDetails.java:110

• The copy constructor deletes a flat mTLS CA received through the client-admin API. Because the typed field is @JsonIgnore, deserialization leaves it null and stores tls-client-auth-ca in additionalInformation; line 107 copies that map, then this null setter removes the key. ClientAdminEndpointsValidator constructs this copy before persisting it, so API-created mTLS clients lose their CA configuration. Preserve the copied map when the typed field is null.

            this.setTlsClientAuthConfiguration(uaa.getTlsClientAuthConfiguration());

[Copilot]

Pull request overview

Copilot reviewed 63 out of 63 changed files in this pull request and generated 4 comments.

Suppressed comments (4)

Previously missed (3) — in code that hasn't changed since the last review.

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminBootstrap.java:223

• Bootstrapped oauth.clients bypass the two validators that call validateTlsClientAuthClaimConfig. This path only checks the feature flag, so an invalid regex or null mapping is persisted and later fails token issuance inside certificate-claim extraction. Validate the claim configuration here before registering the client.

            client.setAdditionalInformation(info);
            ClientAdminEndpointsValidator.checkMtlsClientConfigAllowed(client.getAdditionalInformation(), mtlsEnabled, clientId);

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:413

• This early return also skips validation when tls-client-auth-required-claims is configured without any claim mappings. Such a client is accepted but can never authenticate because extraction always yields an empty map, so every required claim fails. Treat missing mappings as an empty declaration set and continue validating dependent properties.

    public static void validateTlsClientAuthClaimConfig(Map<String, Object> additionalInfo, String clientId) {
        if (additionalInfo == null
                || !additionalInfo.containsKey(TlsClientAuthConfiguration.TLS_CLIENT_AUTH_CLAIM_MAPPINGS)) {
            return;

server/src/main/java/org/cloudfoundry/identity/uaa/zone/ZoneEndpointsClientDetailsValidator.java:60

• Presence of the map key is not equivalent to a configured CA. A blank/null tls-client-auth-ca currently bypasses the required-secret check, so the zone API accepts a secretless client that can never pass TlsClientAuthConfiguration.isConfigured during authentication. Base this decision on a nonblank, valid CA configuration instead.

server/src/main/java/org/cloudfoundry/identity/uaa/client/ClientAdminEndpointsValidator.java:463

• A syntactically valid pattern with no capture group is accepted here, but matchFirstOu only emits group(1). For example, ^app:.*$ saves successfully yet silently produces no claim (and can make required-claim authentication permanently fail). Reject patterns that do not declare at least one capture group.

            String pattern = mapping.getPattern();
            if (pattern != null && !pattern.isBlank()) {
                try {
                    Pattern.compile(pattern);
                } catch (PatternSyntaxException e) {
                    throw new InvalidClientDetailsException(
                            "tls-client-auth-claim-mappings entry has an invalid pattern '" + pattern
                                    + "' for client_id=" + clientId + ": " + e.getMessage(), e);
                }