Skip to content

proxy-support.adoc

Latest commit

 

History

History
121 lines (98 loc) · 6.73 KB

proxy-support.adoc

File metadata and controls

121 lines (98 loc) · 6.73 KB
Table of Contents

Proxy support

In order to be usable and acceptable world-wide and in enterprise contexts, it is required that IDEasy provides support for network proxies. In case you are working in a company and can only access the Internet via an HTTP proxy, we support your use-case and this page gives details how to make it work.

Configuring Proxy Settings

To enable automatic proxy recognition, users need to set the appropriate environment variables in their system, or check if they are already set. These variables should be formatted as follows, lowercase or uppercase:

# example values for a proxy configuration
http_proxy=http://proxy.host.com:8888
https_proxy=https://proxy.host.com:8443
no_proxy=.domain.com,localhost

Many famous tools like wget, curl, etc. honor these variables and work behind a proxy this way. This also applies for IDEasy so in a standard case, it will work for you out of the box. However, in case it is not working, please read on to find solutions to configure IDEasy to your needs.

Advanced Proxy Configuration

To support advanced proxy configuration, we introduced the variable IDE_OPTIONS that you can set on OS level or e.g. in your ~/.bashrc. It allows to set arbitrary JVM options like proxy settings as well as truststore settings (see also Java system properties).

E.g. if you do not want to rely on the proxy environment variables above, you can also make this explicitly:

export IDE_OPTIONS="-Dhttps.proxyHost=proxy.host.com -Dhttps.proxyPort=8443"

Authentication

In some cases your network proxy may require authentication. Then you need to manually configure your account details like in the following example:

export IDE_OPTIONS="-Dhttps.proxyUser=$USERNAME -Dhttps.proxyPassword=«password»"

TLS Certificate issues

Some strange VPN tools have the bad habit to break up and sniff TLS encrypted connections. Therefore, they create their own TLS connection with a self-made certificate that is typically installed into the certificate trust store of the OS during installation (and also to Firefox, etc.). This way the VPN tool can hide this hack and that it is breaking your end-to-end encryption. You may want to carefully observe the certificate in your browser from clicking on the lock icon. If that certificate belongs to your VPN tool and not to the website you are browsing, then you are affected by this problem.

In IDEasy (or Eclipse Marketplace) you may therefore end up with the following error:

javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This is not a bug of IDEasy but actually showing that it is working correct and keeping you safe. You may also want to visit https://badssl.com/ while your VPN tool is active and click the certificate tests like pinning-test. If you then do not get an error in your browser (like "Secure connection failed") but a red warning page, your VPN tools is putting you at risk with breaking your TLS connections.

However, if you are forced by your company to use such VPN tool and cannot exit from the VPN connection, you are entirely blocked. From IDEasy we want to still support you and not leave you alone in the rain with this problem even though this is actually a problem of your VPN tool and your company is rather putting you at risk than keeping you safe. Therefore, we provide you with a workaround so you can use IDEasy even in your environment.

Truststore

So if you are affected by TLS cerificate validation errors as described above, you need to do the following things:

  1. Open the failing HTTPS URL in your browser (e.g. from an error such as java.lang.IllegalStateException: Failed to fetch XML metadata from https://repo1.maven.org/maven2/com/devonfw/tools/IDEasy/ide-cli/maven-metadata.xml …​ PKIX path building failed)

  2. Click on the lock icon left to the URL address bar.

  3. Depending on your browser, you need to click different things to get to the popup showing the TLS certificate details (see cross-browser documentation or for Firefox, or for CLI geeks).

  4. Export the entire certificate chain (or at least the root CA) to $IDE_HOME/settings/myvpn.cer.

  5. Open a bash terminal and ensure you are in your project home directory ($IDE_HOME).

    icd -p «name-of-your-project»

  6. Ensure you have (a recent version of) Java installed in your project

    ide install java

  7. Copy the Java truststore to your settings:

    cp software/java/lib/security/cacerts settings/truststore.p12

  8. Import the exported certificate from step 4. into the new truststore:

    keytool -alias myvpn -import -keystore settings/truststore.p12 -storepass changeit -file settings/myvpn.cer

  9. Configure this truststore for IDEasy:

    export IDE_OPTIONS="-Djavax.net.ssl.trustStore=$IDE_HOME/settings/truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit"

  10. Verify that the TLS issues are resolved:

    ide status

    This should not cause errors but say that you are online and tell you if updates of IDEasy are available or you are up-to-date.

  11. If that is now working fine, make this setting persistent:

    touch ~/.ide/ide.properties
echo 'export IDE_OPTIONS="-Djavax.net.ssl.trustStore=$IDE_HOME/settings/truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit"' >> ~/.ide/ide.properties

  12. Open a new shell and try if ide commands (like ide status) are still working.

  13. You are now all set. Commit and push the truststore.p12 file to your settings git repo to share it with your team.

  14. Provide a wiki page for your team with only step 11. and share it.

  15. If everybody in your team is affected by this VPN/TLS issue, you can even add the line directly to the conf/ide.properties template in your settings repo.

Sorry, that we cannot support you automatically in this scenario. Ask your VPN tool vendor for support and why this is all required. In general encryption should be end-to-end and your data should be protected. But if you are not in a sane environment we have provided you with a nice workaround.