Feature Request: Certificate Alias Selection for MicroProfile Rest Client TLS

[OndroMih]

Feature Request: Certificate Alias Selection for MicroProfile Rest Client TLS

Summary

Add support to select a specific client certificate alias for MicroProfile Rest Client outbound TLS connections.

Reference implementation idea from Payara:

• payara/Payara@2bf8d03

Why This Should Be Added to GlassFish

In environments with multiple certificates in the same keystore, applications need deterministic alias selection for outbound mTLS.

Relying on default key manager alias selection can choose the wrong certificate and break:

• service-to-service authentication,
• certificate rotation rollouts,
• multi-tenant or multi-endpoint integrations.

Current Status in GlassFish (2026-06-18)

Not implemented for MP Rest Client in GlassFish source.

Verification notes:

• MP Rest Client integration in GlassFish is currently minimal (sniffer/enablement and Jersey dependency wiring).
• No MP Rest Client-specific config key or implementation path exists for certificate alias selection.
• Existing SSL alias handling in other admin/security code paths is not exposed as an MP Rest Client feature.

Proposed Behavior

• Introduce MP Rest Client configuration property support for client certificate alias selection
• Apply alias selection to outbound TLS handshakes created for MP Rest Client instances.
• Keep existing behavior unchanged when alias is not configured.
• Resolve configuration using a clear fallback order:
  • specific client setting,
  • application-wide MP Rest Client default,
  • server-wide MP Rest Client default.

Suggested Configuration Shape

The exact property name can be finalized during implementation, but should follow MP Rest Client config conventions, e.g. per-client and/or global style:

• <client-interface-or-config-key>/mp-rest/... for a specific interface

Suggested key (final name to be confirmed):

• certificateAlias

Suggested precedence (highest to lowest):

1. Per-client: <client-interface-or-config-key>/mp-rest/certificateAlias
2. Application-wide default: mp-rest/certificateAlias
3. Server-wide default: org.glassfish.mp-rest.certificateAlias

Behavior:

• If per-client value is present, use it.
• If per-client value is absent, use application-wide value.
• If application-wide value is absent, use server-wide value.
• If none are set, preserve existing TLS key-manager alias behavior.

Example:

• com.example.InventoryClient/mp-rest/certificateAlias=inventory-cert
• mp-rest/certificateAlias=default-app-cert
• org.glassfish.mp-rest.certificateAlias=default-server-cert

In this example, InventoryClient uses inventory-cert; all other MP Rest Clients in the app use default-app-cert; if app-level value is not defined, they use default-server-cert.

Acceptance Criteria

• Application can configure a certificate alias for an MP Rest Client.
• Application can define a default alias for all MP Rest Clients in the application.
• Server can define a default alias used when application-level configuration is absent.
• Outbound TLS uses the configured alias when multiple private keys exist in the keystore.
• If alias is missing/invalid, behavior is clear and diagnosable (explicit log/error).
• Existing MP Rest Client TCK still passes.
• Add integration tests covering:
  • per-client overrides application default,
  • application default overrides server default,
  • server default used when both client and app settings are absent,
  • multiple cert aliases in keystore,
  • successful alias pinning,
  • invalid alias handling.

Candidate Implementation Areas

• org.eclipse.microprofile.rest.client.spi.RestClientListener (SPI)
  • Payara uses this SPI to hook MP Rest Client construction and apply certificate-alias behavior.
  • GlassFish can add the same hook by implementing a RestClientListener and registering it via META-INF/services/org.eclipse.microprofile.rest.client.spi.RestClientListener, then applying alias resolution (client -> app -> server fallback) before the client is built.
• appserver/microprofile/connectors/src/main/java/org/glassfish/microprofile/connector/RestClientSniffer.java
  • handles(DeploymentContext) and getAnnotationTypes() are current MP Rest Client integration entry points; this module is a practical place to register a new MP Rest Client TLS alias integration service/initializer.
• nucleus/security/core/src/main/java/com/sun/enterprise/security/ssl/SSLUtils.java
  • getKeyManagers(String algorithm) to obtain baseline key managers.
  • isTokenKeyAlias(String certNickname) to validate configured aliases before use.
  • getSSLContext(String protocol, String algorithm, String trustAlgorithm) already applies outbound alias wrapping via HTTPS_OUTBOUND_KEY_ALIAS; this is the closest existing outbound TLS alias behavior to reuse/adapt.
• nucleus/security/core/src/main/java/com/sun/enterprise/security/ssl/J2EEKeyManager.java
  • chooseClientAlias(...) is the concrete alias-selection mechanism currently used after wrapping X509KeyManager; MP Rest Client alias selection should use this class (or equivalent behavior) for deterministic client cert choice.
• appserver/security/ejb.security/src/main/java/com/sun/enterprise/iiop/security/IIOPSSLUtilImpl.java
  • getKeyManagers(String alias) demonstrates GlassFish alias validation + wrapping pattern (validate via sslUtils.isTokenKeyAlias(...), then wrap managers with J2EEKeyManager) and can be mirrored for MP Rest Client.
• appserver/security/webintegration/src/main/java/com/sun/web/security/SSLSocketFactory.java
  • initStoresAtStartup() shows existing outbound HTTPS alias wiring (SSLUtils.HTTPS_OUTBOUND_KEY_ALIAS) and can serve as reference for server-wide fallback behavior and logging/error semantics.