The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Voltar aos Guias

Using Proxy Registry

preview

This guide covers:

  • How to configure a global proxy

  • How to configure named proxies

  • How to integrate with a Credentials Provider

Introduction

A proxy acts as an intermediary between an application and external services. Instead of connecting directly to a remote host, the application sends requests through a proxy server. The proxy server then forwards the requests to the destination.

In Java applications, proxies are commonly required in environments where direct outbound network access is restricted. This is typical in corporate networks. This is also common in cloud environments with strict security rules. This is often required in production systems that require traffic inspection and auditing.

Proxies are commonly used to:

  • Control and restrict outbound network access

  • Enforce security and network policies

  • Provide authentication for external connections

  • Monitor and log outgoing traffic

Proxy configuration

Many Java applications rely on JVM system properties or client-specific configuration to enable proxy support. This approach can lead to duplicated configuration. This approach can also lead to inconsistent behavior across clients.

Quarkus provides a centralized way to configure proxies using the Proxy Registry. All proxy configuration is defined under the quarkus.proxy configuration root.

You can configure:

  • A default (global) proxy

  • One or more named proxies that extensions can reference

Some Quarkus extensions already integrate with the Proxy Registry, including:

Configuring a default proxy

To configure a default (global) proxy, add the following properties to application.properties:

quarkus.proxy.host=localhost (1)
quarkus.proxy.port=8443 (2)
quarkus.proxy.type=HTTP (3)

  1. The proxy host

  2. The proxy port

  3. The proxy type. Possible values are HTTP (default), SOCKS4, and SOCKS5.

Extensions that are aware of the Proxy Registry use the default proxy. This happens unless a named proxy is explicitly referenced in the configuration of the extension.

Configuring named proxies

Named proxies allow different clients or extensions to use different proxy configurations.

The following example defines two named proxies:

quarkus.proxy.local.host=localhost
quarkus.proxy.local.port=3333
quarkus.proxy.local.type=SOCKS5

quarkus.proxy.my-proxy.host=localhost
quarkus.proxy.my-proxy.port=8443
quarkus.proxy.my-proxy.type=HTTP
quarkus.proxy.my-proxy.non-proxy-hosts=proxy.mycompany.com,proxy.org.acme (1)

  1. Hostnames or IP addresses that should bypass the proxy

In this example, two named proxies are configured. The proxies are named local and my-proxy. Extensions can reference these proxies by name when required.

Using credentials

Proxy authentication can be configured directly using the username and password properties.

quarkus.proxy.my-proxy.host=localhost
quarkus.proxy.my-proxy.port=8443
quarkus.proxy.my-proxy.type=HTTP
quarkus.proxy.my-proxy.non-proxy-hosts=proxy.mycompany.com,proxy.org.acme

quarkus.proxy.my-proxy.username=${PROXY_USERNAME}
quarkus.proxy.my-proxy.password=${PROXY_PASSWORD}

Credentials can be externalized using environment variables. Credentials can also be externalized using any other supported Quarkus configuration source.

Providing credentials via a Credentials Provider

Instead of defining credentials directly in configuration, you can integrate with a Quarkus Credentials Provider. This allows credentials to be retrieved securely from external systems. Examples include vaults or secret managers.

This feature relies on the Credentials Provider capability.

To configure a credentials provider for proxy authentication, use the following properties:

quarkus.proxy.host=localhost
quarkus.proxy.port=3838

quarkus.proxy.credentials-provider.name=credential
quarkus.proxy.credentials-provider.bean-name=credentialBean
quarkus.proxy.credentials-provider.username-key=userKey
quarkus.proxy.credentials-provider.password-key=passwordKey

The Proxy Registry automatically retrieves the credentials. The credentials are applied to the proxy configuration.

How credentials are applied

When a proxy is configured with a Credentials Provider, the Proxy Registry automatically retrieves the credentials at startup. The retrieved credentials are applied to the proxy configuration.

The behavior is as follows:

  • If username and password are explicitly configured, they are used.

  • Otherwise, if a Credentials Provider is configured, the credentials are retrieved from the provider.

  • If no credentials are configured, the proxy is used without authentication.

If only one of username or password is defined, the application fails at startup. The application also fails if the credentials cannot be retrieved from the provider. In both cases, a configuration error is reported.

This ensures that proxy configuration is validated early. This validation is consistent across all clients and extensions.

Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.proxy.host

Proxy host.

Environment variable: QUARKUS_PROXY_HOST

Show more

string

quarkus.proxy.port

Proxy port

Environment variable: QUARKUS_PROXY_PORT

Show more

int

quarkus.proxy.credentials-provider.name

Name of the credential bucket to retrieve from the CredentialsProvider. If not set, the credentials provider will not be used.

A credentials provider offers a way to retrieve the key store password as well as alias password. Note that the credentials provider is only used if the username and password are not set in the configuration.

Environment variable: QUARKUS_PROXY_CREDENTIALS_PROVIDER_NAME

Show more

string

quarkus.proxy.credentials-provider.bean-name

Name of the bean providing the credentials provider.

The name is used to select the credentials provider to use. The credentials provider must be exposed as a CDI bean and with the @Named annotation set to the configured name to be selected.

If not set, the default credentials provider is used.

Environment variable: QUARKUS_PROXY_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

quarkus.proxy.credentials-provider.username-key

The key used to retrieve the username from the credentials provider.

If username, password or both cannot be retrieved from the credentials provider, an exception is thrown.

Environment variable: QUARKUS_PROXY_CREDENTIALS_PROVIDER_USERNAME_KEY

Show more

string

user

quarkus.proxy.credentials-provider.password-key

The key used to retrieve the password from the credentials provider.

If username, password or both cannot be retrieved from the credentials provider, an exception is thrown.

Environment variable: QUARKUS_PROXY_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

quarkus.proxy.username

Proxy username.

See also credentials-provider

Environment variable: QUARKUS_PROXY_USERNAME

Show more

string

quarkus.proxy.password

Proxy password

See also credentials-provider

Environment variable: QUARKUS_PROXY_PASSWORD

Show more

string

quarkus.proxy.non-proxy-hosts

Hostnames or IP addresses to exclude from proxying

Environment variable: QUARKUS_PROXY_NON_PROXY_HOSTS

Show more

list of string

quarkus.proxy.proxy-connect-timeout

Proxy connection timeout.

Environment variable: QUARKUS_PROXY_PROXY_CONNECT_TIMEOUT

Show more

Duration 

10s

quarkus.proxy.type

The proxy type. Possible values are: HTTP (default), SOCKS4 and SOCKS5.

Environment variable: QUARKUS_PROXY_TYPE

Show more

http, socks4, socks5

http

quarkus.proxy."named-proxy-configs".host

Proxy host.

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__HOST

Show more

string

quarkus.proxy."named-proxy-configs".port

Proxy port

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__PORT

Show more

int

quarkus.proxy."named-proxy-configs".credentials-provider.name

Name of the credential bucket to retrieve from the CredentialsProvider. If not set, the credentials provider will not be used.

A credentials provider offers a way to retrieve the key store password as well as alias password. Note that the credentials provider is only used if the username and password are not set in the configuration.

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__CREDENTIALS_PROVIDER_NAME

Show more

string

quarkus.proxy."named-proxy-configs".credentials-provider.bean-name

Name of the bean providing the credentials provider.

The name is used to select the credentials provider to use. The credentials provider must be exposed as a CDI bean and with the @Named annotation set to the configured name to be selected.

If not set, the default credentials provider is used.

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

quarkus.proxy."named-proxy-configs".credentials-provider.username-key

The key used to retrieve the username from the credentials provider.

If username, password or both cannot be retrieved from the credentials provider, an exception is thrown.

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__CREDENTIALS_PROVIDER_USERNAME_KEY

Show more

string

user

quarkus.proxy."named-proxy-configs".credentials-provider.password-key

The key used to retrieve the password from the credentials provider.

If username, password or both cannot be retrieved from the credentials provider, an exception is thrown.

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

quarkus.proxy."named-proxy-configs".username

Proxy username.

See also credentials-provider

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__USERNAME

Show more

string

quarkus.proxy."named-proxy-configs".password

Proxy password

See also credentials-provider

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__PASSWORD

Show more

string

quarkus.proxy."named-proxy-configs".non-proxy-hosts

Hostnames or IP addresses to exclude from proxying

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__NON_PROXY_HOSTS

Show more

list of string

quarkus.proxy."named-proxy-configs".proxy-connect-timeout

Proxy connection timeout.

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__PROXY_CONNECT_TIMEOUT

Show more

Duration 

10s

quarkus.proxy."named-proxy-configs".type

The proxy type. Possible values are: HTTP (default), SOCKS4 and SOCKS5.

Environment variable: QUARKUS_PROXY__NAMED_PROXY_CONFIGS__TYPE

Show more

http, socks4, socks5

http
About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

Conteúdo Relacionado

Nos mesmos tópicos

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license. CC by 3.0

This website was built with Jekyll, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

Navigation
Follow Us
Get Help
Languages
Quarkus is made of community projects
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.