Maven Proxy Configuration

Snippet Maven

Configure Maven Proxy to download maven dependencies behind organization's proxy.

Proxy - Basic Configuration

Add proxy configuration to ~/.m2/settings.xml.

<settings>
  <proxies>
    <proxy>
      <id>company-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.company.com</host>
      <port>8080</port>
    </proxy>
  </proxies>
</settings>

Proxy - With Authentication

Configure proxy with username and password.

<proxy>
  <id>company-proxy-auth</id>
  <active>true</active>
  <protocol>http</protocol>
  <host>proxy.company.com</host>
  <port>8080</port>
  <username>your-username</username>
  <password>your-password</password>
</proxy>

Security - Encrypted Password

Store passwords securely using Maven’s encryption.

Create Master Password

mvn --encrypt-master-password

Save output to ~/.m2/settings-security.xml:

<settingsSecurity>
  <master>{ENCRYPTED_MASTER_PASSWORD}</master>
</settingsSecurity>

Encrypt Proxy Password

mvn --encrypt-password

Use encrypted password in settings.xml:

<password>{ENCRYPTED_PASSWORD}</password>

Proxy - Exclude Hosts

Bypass proxy for specific hosts (nonProxyHosts).

<proxy>
  <id>company-proxy</id>
  <active>true</active>
  <protocol>http</protocol>
  <host>proxy.company.com</host>
  <port>8080</port>
  <nonProxyHosts>localhost|127.0.0.1|*.internal.com|nexus.company.com</nonProxyHosts>
</proxy>

Common Patterns

Pattern	Matches
`localhost`	localhost only
`127.0.0.1`	Loopback IP
`*.internal.com`	All internal.com subdomains
`10.*`	All 10.x.x.x addresses
`host1\|host2`	Multiple hosts (pipe separator)

Proxy - Multiple Protocols

Configure different proxies for HTTP and HTTPS.

<proxies>
  <!-- HTTP Proxy -->
  <proxy>
    <id>http-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>http-proxy.company.com</host>
    <port>8080</port>
  </proxy>

  <!-- HTTPS Proxy -->
  <proxy>
    <id>https-proxy</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>https-proxy.company.com</host>
    <port>8443</port>
  </proxy>
</proxies>

Corporate - Complete Setup

Common configuration for enterprise environments.

<proxies>
  <proxy>
    <id>corporate-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>proxy.corp.company.com</host>
    <port>8080</port>
    <username>${env.PROXY_USER}</username>
    <password>${env.PROXY_PASS}</password>
    <nonProxyHosts>
      localhost|127.0.0.1|
      *.company.com|
      nexus.company.com|
      artifactory.company.com|
      10.*|172.16.*|192.168.*
    </nonProxyHosts>
  </proxy>
</proxies>

Environment Variables

Set in shell profile:

export PROXY_USER="your-username"
export PROXY_PASS="your-password"

JVM - Proxy Arguments

Pass proxy settings directly to Maven via JVM arguments.

mvn clean install \
  -Dhttp.proxyHost=proxy.company.com \
  -Dhttp.proxyPort=8080 \
  -Dhttp.proxyUser=username \
  -Dhttp.proxyPassword=password \
  -Dhttps.proxyHost=proxy.company.com \
  -Dhttps.proxyPort=8080

JVM - MAVEN_OPTS

Set persistent proxy options via MAVEN_OPTS.

Add to ~/.bashrc or ~/.zshrc:

export MAVEN_OPTS="-Dhttp.proxyHost=proxy.company.com -Dhttp.proxyPort=8080"

Verify - Test Connection

Test proxy setup by downloading a dependency.

mvn dependency:get \
  -Dartifact=org.apache.commons:commons-lang3:3.12.0 \
  -X

Verify - Effective Settings

View final resolved settings including proxy.

mvn help:effective-settings

Verify - Debug Mode

Check if proxy is being used in debug mode.

mvn clean install -X 2>&1 | grep -i proxy

Troubleshoot - Cannot Access Repository

Fix “Unable to access repository” error.

Checklist

Verify proxy host and port
Check if authentication is required
Ensure <active>true</active> is set
Verify nonProxyHosts doesn’t block Maven Central
Check firewall/network access

Test Proxy Manually

curl -x http://proxy.company.com:8080 https://repo.maven.apache.org/maven2/

Troubleshoot - 407 Authentication Required

Fix “407 Proxy Authentication Required” error.

Solution

Add credentials to proxy configuration:

<proxy>
  <username>your-username</username>
  <password>your-password</password>
</proxy>

NTLM Authentication

For Windows domains:

<proxy>
  <username>DOMAIN\username</username>
  <password>password</password>
</proxy>

Troubleshoot - SSL Certificate Error

Fix “PKIX path building failed” SSL certificate error.

Temporary Fix (Development Only)

mvn clean install -Dmaven.wagon.http.ssl.insecure=true \
  -Dmaven.wagon.http.ssl.allowall=true

Proper Fix - Import Certificate

keytool -import \
  -alias company-proxy \
  -file proxy-cert.crt \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit

Docker - Proxy Configuration

Pass proxy settings to Maven in Docker container.

Dockerfile

FROM maven:3.9-openjdk-17

# Set proxy environment variables
ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080
ENV NO_PROXY=localhost,127.0.0.1

# Or configure in settings.xml
COPY settings.xml /root/.m2/settings.xml

Build Args

docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  -t my-maven-app .

IDE - IntelliJ IDEA

Configure proxy in IntelliJ IDEA.

File → Settings → Build → Build Tools → Maven
Set User settings file to your settings.xml
Verify proxy settings are loaded

IDE - Eclipse

Configure proxy in Eclipse.

Window → Preferences → Maven → User Settings
Point to your settings.xml file
Click Update Settings

IDE - VS Code

Configure Maven settings in VS Code.

Add to .vscode/settings.json:

{
  "maven.executable.path": "/usr/local/bin/mvn",
  "maven.settingsFile": "/Users/username/.m2/settings.xml"
}

Settings - File Locations

Maven settings file locations by OS.

OS	Path
Linux/Mac	`~/.m2/settings.xml`
Windows	`C:\Users\YourName\.m2\settings.xml`
Global	`${maven.home}/conf/settings.xml`

Create Directory

mkdir -p ~/.m2
touch ~/.m2/settings.xml

Testing - Proxy Test Script

Test script to verify proxy configuration.

Save as test-maven-proxy.sh:

#!/bin/bash

echo "Testing Maven proxy configuration..."

# Test proxy connectivity
echo -n "1. Testing proxy connection: "
nc -zv proxy.company.com 8080 2>&1 | grep succeeded && echo "✓" || echo "✗"

# Test Maven Central via proxy
echo -n "2. Testing Maven Central via proxy: "
curl -s -x http://proxy.company.com:8080 https://repo.maven.apache.org/maven2/ > /dev/null && echo "✓" || echo "✗"

# Check settings.xml
echo -n "3. Checking settings.xml: "
[ -f ~/.m2/settings.xml ] && echo "✓" || echo "✗ (not found)"

# Test dependency download
echo "4. Testing dependency download:"
mvn dependency:get -Dartifact=org.apache.commons:commons-lang3:3.12.0 -q && echo "✓" || echo "✗"

Complete Example

Full settings.xml with proxy, mirrors, and repositories.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">

  <!-- Proxy Configuration -->
  <proxies>
    <proxy>
      <id>corporate-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.company.com</host>
      <port>8080</port>
      <username>${env.PROXY_USER}</username>
      <password>${env.PROXY_PASS}</password>
      <nonProxyHosts>localhost|127.0.0.1|*.company.com</nonProxyHosts>
    </proxy>
  </proxies>

  <!-- Mirror to internal Nexus -->
  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://nexus.company.com/repository/maven-public/</url>
    </mirror>
  </mirrors>

  <!-- Server Authentication -->
  <servers>
    <server>
      <id>nexus</id>
      <username>${env.NEXUS_USER}</username>
      <password>${env.NEXUS_PASS}</password>
    </server>
  </servers>

</settings>

Debug - Enable Logging

Enable debug logging for troubleshooting.

mvn clean install -X > maven-debug.log 2>&1

Debug - Test Connection

Test HTTP and HTTPS connections through proxy.

# Test HTTP
curl -v -x http://proxy.company.com:8080 http://repo.maven.apache.org/maven2/

# Test HTTPS
curl -v -x http://proxy.company.com:8080 https://repo.maven.apache.org/maven2/

Debug - Verify Active Settings

Check if proxy settings are active.

mvn help:effective-settings | grep -A 10 "<proxy>"

Common Issues

Frequent proxy configuration problems.

Proxy host/port incorrect
Missing authentication credentials
Certificate trust issues
Blocked by firewall
Wrong protocol (http vs https)
nonProxyHosts blocking required hosts