feat(auth): mTLS endpoint for Regional Access Boundaries #13318
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -31,14 +31,19 @@ | |
| package com.google.auth.mtls; | ||
|
|
||
| import com.google.api.core.InternalApi; | ||
| import com.google.auth.http.HttpTransportFactory; | ||
| import com.google.auth.oauth2.EnvironmentProvider; | ||
| import com.google.auth.oauth2.OAuth2Utils; | ||
| import com.google.auth.oauth2.PropertyProvider; | ||
| import com.google.common.base.Strings; | ||
| import java.io.File; | ||
| import java.io.FileInputStream; | ||
| import java.io.IOException; | ||
| import java.io.InputStream; | ||
| import java.security.KeyStore; | ||
| import java.util.Locale; | ||
| import java.util.logging.Logger; | ||
| import javax.annotation.Nullable; | ||
|
|
||
| /** | ||
| * Utility class for mTLS related operations. | ||
|
|
@@ -47,10 +52,27 @@ | |
| */ | ||
| @InternalApi | ||
| public class MtlsUtils { | ||
| private static final Logger LOGGER = Logger.getLogger(MtlsUtils.class.getName()); | ||
|
|
||
| static final String CERTIFICATE_CONFIGURATION_ENV_VARIABLE = "GOOGLE_API_CERTIFICATE_CONFIG"; | ||
| static final String WELL_KNOWN_CERTIFICATE_CONFIG_FILE = "certificate_config.json"; | ||
| static final String CLOUDSDK_CONFIG_DIRECTORY = "gcloud"; | ||
|
|
||
| /** | ||
| * The policy determining when to use mutual TLS (mTLS) endpoints. | ||
| * | ||
| * <p>See <a href="https://google.aip.dev/auth/4114">AIP-4114</a> for the specification on mTLS | ||
| * endpoint usage. | ||
| */ | ||
| public enum MtlsEndpointUsagePolicy { | ||
| /** Always use the mTLS endpoint, and fail if client certificates are not configured. */ | ||
| ALWAYS, | ||
| /** Never use the mTLS endpoint. */ | ||
| NEVER, | ||
| /** Use the mTLS endpoint if client certificates are configured (auto-discovery). */ | ||
| AUTO | ||
| } | ||
|
vverman marked this conversation as resolved.
|
||
|
|
||
| private MtlsUtils() { | ||
| // Prevent instantiation for Utility class | ||
| } | ||
|
|
@@ -76,39 +98,36 @@ public static String getCertificatePath( | |
| } | ||
|
|
||
| /** | ||
| * Resolves and parses the workload certificate configuration. | ||
| * | ||
| * <p>This locates the certificate configuration file via {@link #resolveCertificateConfigFile} | ||
| * and parses its contents into a {@link WorkloadCertificateConfiguration}. | ||
| * | ||
| * @param envProvider the environment provider to use for resolving environment variables | ||
| * @param propProvider the property provider to use for resolving system properties | ||
| * @param certConfigPathOverride optional override path for the configuration file | ||
| * @return the loaded WorkloadCertificateConfiguration | ||
| * @throws IOException if the configuration file cannot be resolved, read, or parsed | ||
| */ | ||
| static WorkloadCertificateConfiguration getWorkloadCertificateConfiguration( | ||
| EnvironmentProvider envProvider, PropertyProvider propProvider, String certConfigPathOverride) | ||
| throws IOException { | ||
| File certConfig = | ||
| resolveCertificateConfigFile(envProvider, propProvider, certConfigPathOverride); | ||
| if (certConfig == null) { | ||
| try { | ||
| File wellKnownConfig = getWellKnownCertificateConfigFile(envProvider, propProvider); | ||
| throw new CertificateSourceUnavailableException( | ||
| "Certificate configuration file does not exist or is not a file: " | ||
| + wellKnownConfig.getAbsolutePath()); | ||
| } catch (IOException e) { | ||
| if (e instanceof CertificateSourceUnavailableException) { | ||
| throw (CertificateSourceUnavailableException) e; | ||
| } | ||
| throw new CertificateSourceUnavailableException( | ||
| "Failed to get well-known certificate config file path", e); | ||
| } | ||
| } | ||
| try (InputStream certConfigStream = new FileInputStream(certConfig)) { | ||
| return WorkloadCertificateConfiguration.fromCertificateConfigurationStream(certConfigStream); | ||
| } | ||
|
|
@@ -137,4 +156,178 @@ private static File getWellKnownCertificateConfigFile( | |
| } | ||
| return new File(cloudConfigPath, WELL_KNOWN_CERTIFICATE_CONFIG_FILE); | ||
| } | ||
|
|
||
| /** | ||
| * Centralized helper method to determine if mutual TLS (mTLS) can be enabled. | ||
| * | ||
| * @param envProvider the environment provider to use for resolving environment variables | ||
| * @param propProvider the property provider to use for resolving system properties | ||
| * @param certConfigPathOverride optional override path for the configuration file | ||
| * @return true if mTLS should be enabled, false otherwise | ||
| * @throws IOException if the configuration file is present but contains missing or malformed | ||
| * files | ||
| */ | ||
| public static boolean canBeEnabled( | ||
| EnvironmentProvider envProvider, PropertyProvider propProvider, String certConfigPathOverride) | ||
| throws IOException { | ||
|
|
||
| // Check if client certificate usage is allowed | ||
| String useClientCertificate = envProvider.getEnv("GOOGLE_API_USE_CLIENT_CERTIFICATE"); | ||
| MtlsEndpointUsagePolicy policy = getMtlsEndpointUsagePolicy(envProvider); | ||
| if ("false".equalsIgnoreCase(useClientCertificate)) { | ||
|
Contributor
There was a problem hiding this comment. AIP-4114 says: "If user specifies an mTLS endpoint override but device certificate is not available, do not fail-fast, but let server return error when connecting." So which endpoint to call, and whether to attach a cert should be evaluated separately. |
||
| if (policy == MtlsEndpointUsagePolicy.ALWAYS) { | ||
| throw new CertificateSourceUnavailableException( | ||
| "mTLS is configured to ALWAYS, but client certificate usage was explicitly disabled via GOOGLE_API_USE_CLIENT_CERTIFICATE=false."); | ||
| } | ||
| return false; | ||
| } | ||
|
|
||
| if (policy == MtlsEndpointUsagePolicy.NEVER) { | ||
| return false; | ||
| } | ||
|
vverman marked this conversation as resolved.
|
||
|
|
||
| if (policy == MtlsEndpointUsagePolicy.ALWAYS) { | ||
| return true; | ||
| } | ||
|
vverman marked this conversation as resolved.
|
||
|
|
||
| File certConfigFile = | ||
| resolveCertificateConfigFile(envProvider, propProvider, certConfigPathOverride); | ||
| return certConfigFile != null; | ||
| } | ||
|
|
||
| /** | ||
| * Resolves the mutual TLS (mTLS) certificate configuration file. | ||
| * | ||
| * <p>The configuration file is resolved in the following order of precedence: | ||
| * | ||
| * <ol> | ||
| * <li>The developer-provided {@code certConfigPathOverride} (if not null). | ||
| * <li>The path specified by the {@code GOOGLE_API_CERTIFICATE_CONFIG} environment variable. | ||
| * <li>The well-known automatic gcloud workload identity provisioning location (via {@link | ||
| * #getWellKnownCertificateConfigFile}). | ||
| * </ol> | ||
| * | ||
| * <p>If an explicit configuration file is specified (via override or environment variable) and it | ||
| * is missing or invalid, an exception is thrown. If no explicit file is specified and the default | ||
| * well-known file is missing, {@code null} is returned. | ||
| * | ||
| * @param envProvider the environment provider to use for resolving environment variables | ||
| * @param propProvider the property provider to use for resolving system properties | ||
| * @param certConfigPathOverride optional override path for the configuration file | ||
| * @return the resolved File object, or null if no configuration was found | ||
| * @throws IOException if an explicit configuration file is missing or malformed | ||
| */ | ||
| @Nullable | ||
| static File resolveCertificateConfigFile( | ||
| EnvironmentProvider envProvider, PropertyProvider propProvider, String certConfigPathOverride) | ||
| throws IOException { | ||
| // 1. Check explicit developer override | ||
| if (certConfigPathOverride != null) { | ||
| File certConfigFile = new File(certConfigPathOverride); | ||
| if (!certConfigFile.isFile()) { | ||
| throw new CertificateSourceUnavailableException( | ||
| "Certificate configuration file does not exist or is not a file: " | ||
| + certConfigFile.getAbsolutePath()); | ||
| } | ||
| return certConfigFile; | ||
| } | ||
|
|
||
| // 2. Check explicit environment variable | ||
| String envPath = envProvider.getEnv(CERTIFICATE_CONFIGURATION_ENV_VARIABLE); | ||
| if (!Strings.isNullOrEmpty(envPath)) { | ||
| File certConfigFile = new File(envPath); | ||
| if (!certConfigFile.isFile()) { | ||
| throw new CertificateSourceUnavailableException( | ||
| "Certificate configuration file does not exist or is not a file: " | ||
| + certConfigFile.getAbsolutePath()); | ||
| } | ||
| return certConfigFile; | ||
| } | ||
|
|
||
| // 3. Check optional well-known automatic provisioning location | ||
| try { | ||
| File wellKnownConfig = getWellKnownCertificateConfigFile(envProvider, propProvider); | ||
| if (wellKnownConfig.isFile()) { | ||
| return wellKnownConfig; | ||
| } | ||
| } catch (IOException e) { | ||
| LOGGER.info( | ||
| "Could not get the mutual TLS (mTLS) client certificate configuration. The library will fall back to making standard non-mTLS requests."); | ||
| } | ||
|
|
||
| return null; | ||
| } | ||
|
|
||
| /** | ||
| * Returns the current mutual TLS endpoint usage policy. | ||
| * | ||
| * @param envProvider the environment provider to use for resolving environment variables | ||
| * @return the MtlsEndpointUsagePolicy enum value | ||
| */ | ||
| public static MtlsEndpointUsagePolicy getMtlsEndpointUsagePolicy( | ||
| EnvironmentProvider envProvider) { | ||
| String mtlsEndpointUsagePolicy = envProvider.getEnv("GOOGLE_API_USE_MTLS_ENDPOINT"); | ||
| if ("never".equalsIgnoreCase(mtlsEndpointUsagePolicy)) { | ||
| return MtlsEndpointUsagePolicy.NEVER; | ||
| } else if ("always".equalsIgnoreCase(mtlsEndpointUsagePolicy)) { | ||
| return MtlsEndpointUsagePolicy.ALWAYS; | ||
| } | ||
| return MtlsEndpointUsagePolicy.AUTO; | ||
| } | ||
|
|
||
| /** | ||
| * Prepares and upgrades the HTTP transport factory for mutual TLS (mTLS) if applicable. | ||
| * | ||
| * @param baseTransportFactory the base HTTP transport factory to upgrade | ||
| * @param envProvider the environment provider to use for resolving environment variables | ||
| * @param propProvider the property provider to use for resolving system properties | ||
| * @param certConfigPathOverride optional override path for the configuration file | ||
| * @return the mTLS-configured HTTP transport factory, or the base factory if mTLS is not enabled | ||
| * @throws IOException if mTLS is required/enabled but certificate initialization fails or an | ||
| * incompatible transport factory was provided | ||
| */ | ||
| public static HttpTransportFactory prepareTransportFactoryIfMtlsEnabled( | ||
| HttpTransportFactory baseTransportFactory, | ||
| EnvironmentProvider envProvider, | ||
| PropertyProvider propProvider, | ||
| String certConfigPathOverride) | ||
| throws IOException { | ||
|
|
||
| if (baseTransportFactory == null) { | ||
| return null; | ||
| } | ||
|
Comment on lines
+296
to
+298
Member
There was a problem hiding this comment. can you check if we still need this null check from the RAB flow? I think refreshRegionalAccessBoundaryIfExpired() does an early return if the transportFactory is null (can we assert that transportFactory will always be non-null)?
Contributor
Author
There was a problem hiding this comment. This is technically a mtls util function which RAB is utilizing. In the future mWLID or bound tokens could also rely on this to get their transporter. Hence I think this null check still remains valid and we should keep it. |
||
|
|
||
| if (baseTransportFactory instanceof MtlsHttpTransportFactory) { | ||
| // A custom MtlsHttpTransportFactory was already pre-configured by the user. | ||
| // Keep using it as-is without re-initializing. | ||
| return baseTransportFactory; | ||
| } | ||
|
|
||
| if (!canBeEnabled(envProvider, propProvider, certConfigPathOverride)) { | ||
| return baseTransportFactory; | ||
| } | ||
|
Contributor
There was a problem hiding this comment. Currently the RAB manager assumes any non-default transport supports mTLS and switches to the mTLS endpoint. I think this is worth a discussion - what are we doing in other languages? At least here we don't know if the custom transport carries a cert.
Contributor
Author
There was a problem hiding this comment. Done! The logic now ensures the library will only switch the endpoint URL to the mTLS variant (MTLS_IAM_ENDPOINT) if the upgraded transport factory is successfully created and is not the standard non-mTLS transport (OAuth2Utils.HTTP_TRANSPORT_FACTORY). |
||
|
|
||
| if (baseTransportFactory != OAuth2Utils.HTTP_TRANSPORT_FACTORY) { | ||
|
vverman marked this conversation as resolved.
|
||
| // A user configured HttpTransportFactory was explicitly injected. | ||
| // Trust the developer's custom factory and return it as-is. | ||
| return baseTransportFactory; | ||
| } | ||
|
|
||
| MtlsEndpointUsagePolicy mtlsPolicy = getMtlsEndpointUsagePolicy(envProvider); | ||
| try { | ||
| // This is the default HttpTransportFactory assigned by credentials. | ||
| // Automatically discover and load client certificates to construct an mTLS factory. | ||
| X509Provider x509Provider = | ||
| new X509Provider(envProvider, propProvider, certConfigPathOverride); | ||
| KeyStore mtlsKeyStore = x509Provider.getKeyStore(); | ||
| return new MtlsHttpTransportFactory(mtlsKeyStore); | ||
| } catch (Exception e) { | ||
| if (mtlsPolicy == MtlsEndpointUsagePolicy.ALWAYS) { | ||
| throw new IOException( | ||
| "mTLS is configured to ALWAYS, but initialization failed: " + e.getMessage(), e); | ||
| } | ||
| // Graceful fallback to standard transport if mTLS initialization fails under AUTO policy | ||
| return baseTransportFactory; | ||
| } | ||
| } | ||
|
vverman marked this conversation as resolved.
|
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.