Maven Proxy Configuration

What is Maven?

Maven is a powerful build automation and project management tool primarily used for Java projects. This guide focuses on configuring Maven to work behind corporate proxy servers for dependency downloads.

---

🌐 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.

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

🌙 IDE - Eclipse

Configure proxy in Eclipse.

1. Window → Preferences → Maven → User Settings
2. Point to your settings.xml file
3. 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