Support Docker configuration authentication including helper support

Add `DockerRegistryAuthentication` implementation that uses standard
Docker config to authenticate requests.

Prior to this commit, we only supported username/password and token
based authentication. This commit allows authentication based on
the contents of the Docker configuration file, including support
for executing credential helpers.

See gh-45269

Signed-off-by: Dmytro Nosan <[email protected]>
Co-authored-by: Phillip Webb <[email protected]>

Author: nosan

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/Builder.java

@@ -246,13 +246,13 @@ private void pushImages(ImageReference name, List<ImageReference> tags) throws I
 	private void pushImage(ImageReference reference) throws IOException {
 		Consumer<TotalProgressEvent> progressConsumer = this.log.pushingImage(reference);
 		TotalProgressPushListener listener = new TotalProgressPushListener(progressConsumer);
-		String authHeader = authHeader(this.dockerConfiguration.publishRegistryAuthentication());
+		String authHeader = authHeader(this.dockerConfiguration.publishRegistryAuthentication(), reference);
 		this.docker.image().push(reference, listener, authHeader);
 		this.log.pushedImage(reference);
 	}
 
-	private static String authHeader(DockerRegistryAuthentication authentication) {
-		return (authentication != null) ? authentication.getAuthHeader() : null;
+	private static String authHeader(DockerRegistryAuthentication authentication, ImageReference reference) {
+		return (authentication != null) ? authentication.getAuthHeader(reference) : null;
 	}
 
 	/**
@@ -279,7 +279,7 @@ private class ImageFetcher {
 		Image fetchImage(ImageType type, ImageReference reference) throws IOException {
 			Assert.notNull(type, "'type' must not be null");
 			Assert.notNull(reference, "'reference' must not be null");
-			String authHeader = authHeader(this.registryAuthentication);
+			String authHeader = authHeader(this.registryAuthentication, reference);
 			Assert.state(authHeader == null || reference.getDomain().equals(this.domain),
 					() -> String.format("%s '%s' must be pulled from the '%s' authenticated registry",
 							StringUtils.capitalize(type.getDescription()), reference, this.domain));
@@ -300,7 +300,7 @@ Image fetchImage(ImageType type, ImageReference reference) throws IOException {
 		private Image pullImage(ImageReference reference, ImageType imageType) throws IOException {
 			TotalProgressPullListener listener = new TotalProgressPullListener(
 					Builder.this.log.pullingImage(reference, this.defaultPlatform, imageType));
-			String authHeader = authHeader(this.registryAuthentication);
+			String authHeader = authHeader(this.registryAuthentication, reference);
 			Image image = Builder.this.docker.image().pull(reference, this.defaultPlatform, listener, authHeader);
 			Builder.this.log.pulledImage(image, imageType);
 			if (this.defaultPlatform == null) {

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/configuration/Credential.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.buildpack.platform.docker.configuration;
+
+import java.lang.invoke.MethodHandles;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import org.springframework.boot.buildpack.platform.json.MappedObject;
+
+/**
+ * A class that represents credentials for a server as returned from a
+ * {@link CredentialHelper}.
+ *
+ * @author Dmytro Nosan
+ */
+class Credential extends MappedObject {
+
+	/**
+	 * If the secret being stored is an identity token, the username should be set to
+	 * {@code <token>}.
+	 */
+	private static final String TOKEN_USERNAME = "<token>";
+
+	private final String username;
+
+	private final String secret;
+
+	private String serverUrl;
+
+	Credential(JsonNode node) {
+		super(node, MethodHandles.lookup());
+		this.username = valueAt("/Username", String.class);
+		this.secret = valueAt("/Secret", String.class);
+		this.serverUrl = valueAt("/ServerURL", String.class);
+	}
+
+	String getUsername() {
+		return this.username;
+	}
+
+	String getSecret() {
+		return this.secret;
+	}
+
+	String getServerUrl() {
+		return this.serverUrl;
+	}
+
+	boolean isIdentityToken() {
+		return TOKEN_USERNAME.equals(this.username);
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/configuration/CredentialHelper.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.buildpack.platform.docker.configuration;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+
+import com.sun.jna.Platform;
+
+import org.springframework.boot.buildpack.platform.json.SharedObjectMapper;
+
+/**
+ * Invokes a Docker credential helper executable that can be used to get {@link Credential
+ * credentials}.
+ *
+ * @author Dmytro Nosan
+ * @author Phillip Webb
+ */
+class CredentialHelper {
+
+	private static final String USR_LOCAL_BIN = "/usr/local/bin/";
+
+	Set<String> CREDENTIAL_NOT_FOUND_MESSAGES = Set.of("credentials not found in native keychain",
+			"no credentials server URL", "no credentials username");
+
+	private final String executable;
+
+	CredentialHelper(String executable) {
+		this.executable = executable;
+	}
+
+	Credential get(String serverUrl) throws IOException {
+		ProcessBuilder processBuilder = processBuilder("get");
+		Process process = start(processBuilder);
+		try (OutputStream request = process.getOutputStream()) {
+			request.write(serverUrl.getBytes(StandardCharsets.UTF_8));
+		}
+		try {
+			int exitCode = process.waitFor();
+			try (InputStream response = process.getInputStream()) {
+				if (exitCode == 0) {
+					return new Credential(SharedObjectMapper.get().readTree(response));
+				}
+				String errorMessage = new String(response.readAllBytes(), StandardCharsets.UTF_8);
+				if (!isCredentialsNotFoundError(errorMessage)) {
+					throw new IOException("%s' exited with code %d: %s".formatted(process, exitCode, errorMessage));
+				}
+				return null;
+			}
+		}
+		catch (InterruptedException ex) {
+			Thread.currentThread().interrupt();
+			return null;
+		}
+	}
+
+	private ProcessBuilder processBuilder(String string) {
+		ProcessBuilder processBuilder = new ProcessBuilder().redirectErrorStream(true);
+		if (Platform.isWindows()) {
+			processBuilder.command("cmd", "/c");
+		}
+		processBuilder.command(this.executable, string);
+		return processBuilder;
+	}
+
+	private Process start(ProcessBuilder processBuilder) throws IOException {
+		try {
+			return processBuilder.start();
+		}
+		catch (IOException ex) {
+			if (!Platform.isMac()) {
+				throw ex;
+			}
+			List<String> command = new ArrayList<>(processBuilder.command());
+			command.set(0, USR_LOCAL_BIN + command.get(0));
+			return processBuilder.command(command).start();
+		}
+	}
+
+	private boolean isCredentialsNotFoundError(String message) {
+		return this.CREDENTIAL_NOT_FOUND_MESSAGES.contains(message.trim());
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/configuration/DockerConfigurationMetadata.java

@@ -63,6 +63,8 @@ final class DockerConfigurationMetadata {
 
 	private static final String CONTEXT_FILE_NAME = "meta.json";
 
+	private static volatile DockerConfigurationMetadata systemEnvironmentConfigurationMetadata;
+
 	private final String configLocation;
 
 	private final DockerConfig config;
@@ -88,11 +90,24 @@ DockerContext forContext(String context) {
 	}
 
 	static DockerConfigurationMetadata from(Environment environment) {
-		String configLocation = (environment.get(DOCKER_CONFIG) != null) ? environment.get(DOCKER_CONFIG)
-				: Path.of(System.getProperty("user.home"), CONFIG_DIR).toString();
+		DockerConfigurationMetadata dockerConfigurationMetadata = (environment == Environment.SYSTEM)
+				? DockerConfigurationMetadata.systemEnvironmentConfigurationMetadata : null;
+		if (dockerConfigurationMetadata != null) {
+			return dockerConfigurationMetadata;
+		}
+		String configLocation = environment.get(DOCKER_CONFIG);
+		configLocation = (configLocation != null) ? configLocation : getUserHomeConfigLocation();
 		DockerConfig dockerConfig = createDockerConfig(configLocation);
 		DockerContext dockerContext = createDockerContext(configLocation, dockerConfig.getCurrentContext());
-		return new DockerConfigurationMetadata(configLocation, dockerConfig, dockerContext);
+		dockerConfigurationMetadata = new DockerConfigurationMetadata(configLocation, dockerConfig, dockerContext);
+		if (environment == Environment.SYSTEM) {
+			DockerConfigurationMetadata.systemEnvironmentConfigurationMetadata = dockerConfigurationMetadata;
+		}
+		return dockerConfigurationMetadata;
+	}
+
+	private static String getUserHomeConfigLocation() {
+		return Path.of(System.getProperty("user.home"), CONFIG_DIR).toString();
 	}
 
 	private static DockerConfig createDockerConfig(String configLocation) {

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/configuration/DockerRegistryAuthentication.java

@@ -16,12 +16,17 @@
 
 package org.springframework.boot.buildpack.platform.docker.configuration;
 
+import java.util.function.BiConsumer;
+
+import org.springframework.boot.buildpack.platform.docker.type.ImageReference;
+
 /**
  * Docker registry authentication configuration.
  *
  * @author Scott Frederick
  * @since 2.4.0
  */
+@FunctionalInterface
 public interface DockerRegistryAuthentication {
 
 	/**
@@ -30,6 +35,17 @@ public interface DockerRegistryAuthentication {
 	 */
 	DockerRegistryAuthentication EMPTY_USER = DockerRegistryAuthentication.user("", "", "", "");
 
+	/**
+	 * Returns the auth header that should be used for docker authentication for the given
+	 * image reference.
+	 * @param imageReference the image reference or {@code null}
+	 * @return the auth header
+	 * @since 3.5.0
+	 */
+	default String getAuthHeader(ImageReference imageReference) {
+		return getAuthHeader();
+	}
+
 	/**
 	 * Returns the auth header that should be used for docker authentication.
 	 * @return the auth header
@@ -63,4 +79,33 @@ static DockerRegistryAuthentication user(String username, String password, Strin
 		return new DockerRegistryUserAuthentication(username, password, serverAddress, email);
 	}
 
+	/**
+	 * Factory method that returns a new {@link DockerRegistryAuthentication} instance
+	 * that uses the standard docker JSON config (including support for credential
+	 * helpers) to generate auth headers.
+	 * @param fallback the fallback authentication to use if no suitable config is found
+	 * @return a new {@link DockerRegistryAuthentication} instance
+	 * @since 3.5.0
+	 * @see #configuration(DockerRegistryAuthentication, BiConsumer)
+	 */
+	static DockerRegistryAuthentication configuration(DockerRegistryAuthentication fallback) {
+		return configuration(fallback, (message, ex) -> System.out.println(message));
+	}
+
+	/**
+	 * Factory method that returns a new {@link DockerRegistryAuthentication} instance
+	 * that uses the standard docker JSON config (including support for credential
+	 * helpers) to generate auth headers.
+	 * @param fallback the fallback authentication to use if no suitable config is found
+	 * @param credentialHelperExceptionHandler callback that should handle credential
+	 * helper exceptions
+	 * @return a new {@link DockerRegistryAuthentication} instance
+	 * @since 3.5.0
+	 * @see #configuration(DockerRegistryAuthentication, BiConsumer)
+	 */
+	static DockerRegistryAuthentication configuration(DockerRegistryAuthentication fallback,
+			BiConsumer<String, Exception> credentialHelperExceptionHandler) {
+		return new DockerRegistryConfigAuthentication(fallback, credentialHelperExceptionHandler);
+	}
+
 }