Skip to content

ezSign - Proxy

Many networks do not let servers reach the internet directly; outbound traffic has to go through a forward proxy (also called an egress proxy). The Proxy page under Settings is where an administrator points ezSign at that proxy - and where they change it later, without any downtime or a restart.

Open it from the administration area: Settings → Proxy.

Who does this

This is an administrator task. Operators - the people who sign documents - never see this page. If your network reaches the internet directly, leave the proxy switched off and there is nothing to do here.

What the proxy covers

When the proxy is switched on, ezSign sends all of its outbound traffic through it:

  • the connection to the signing service (the backend gRPC channel),
  • single sign-on (OIDC) calls to your identity provider,
  • every other outbound HTTP call ezSign makes.

One OpenID check does not use the proxy credentials

The login test on the Admin OpenID and Operator OpenID pages asks your identity provider whether it accepts ezSign's client. That one call is routed through the proxy like everything else, but it does not send the proxy username and password - it has to be able to hear your provider say no, and a proxy sign-in prompt is indistinguishable from that refusal. Behind an authenticating proxy the check therefore reports no usable verdict instead of a result, which does not block the save. Sign-in itself is unaffected and uses the proxy credentials normally.

Outbound email (SMTP) is the one exception - notification email always goes straight to your mail server, never through the proxy. Configure that under Settings → Mail.

flowchart LR
    A["ezSign"] -->|"enabled"| B["Forward proxy<br/>proxy.example.com:8080"]
    B --> C["Signing service · identity provider · internet"]
    A -->|"host on the no-proxy list"| C
    A -->|"outbound email, always direct"| D["Mail server (SMTP)"]

Figure: With the proxy enabled, outbound traffic routes through it - except hosts on the no-proxy list, and outbound email, which is always direct.

Fields

Field Required? Description
Route all outbound traffic through a forward proxy - The on/off switch. Switching it on reveals the fields below; switching it off hides them but keeps them.
Proxy host Required when on The proxy's hostname or address, e.g. proxy.example.com.
Port Required when on The proxy's port, e.g. 8080. Must be between 1 and 65535.
No-proxy hosts Optional Addresses ezSign should reach directly, separated by commas or spaces. Exact names (localhost, 127.0.0.1) or a whole domain with a wildcard (*.internal).
Username Optional Only if the proxy requires a sign-in. Leaving it empty means ezSign connects to the proxy without credentials.
Password Optional The password for that user. Stored encrypted and never shown again - see below.

Select Save to apply. Changes take effect on new connections straight away; no restart is needed.

Save is disabled until a connection test passes

While the proxy is switched on, Save stays disabled - with a note explaining why, next to the button - until you fill in the host and port and a Test connection succeeds for the values currently in the form. This is required again on every visit to the page, even for a configuration that already works, and again after any change to the host, port, no-proxy hosts, username or password. It exists so a typo cannot lock outbound traffic (and with it, single sign-on) behind a proxy nobody checked was actually reachable. Switching the proxy off removes this requirement immediately - there is nothing to verify when you are turning it off.

A successful save shows a brief confirmation notification in the corner of the screen.

Switching the proxy off keeps the configuration

Switching the proxy off does not erase it. The host, port, no-proxy list and credentials all stay on record - ezSign simply stops using them and connects directly.

That means you can:

  • turn the proxy off during a proxy outage or a network change, and
  • turn it back on afterwards without re-typing anything - not even the password.

Testing a network change

Because switching off is reversible with no re-entry, it is a safe first step when you are diagnosing whether the proxy is the cause of a connection problem.

The password is write-only

The proxy password is encrypted as soon as you save it and can never be read back - not by you, and not by the page. So the password field behaves a little differently from the others:

What you see What it means What to do
The field shows dots as a placeholder, with a trash icon A password is on record Leave the field empty to keep it
You click the trash icon Marks the password for removal - the icon becomes an undo arrow and a note appears Select Save to remove it, or click the icon again (or just start typing) to change your mind
You type a new password An eye icon appears so you can check what you typed Select Save to store it
You clear the username ezSign stops authenticating to the proxy at all The password is removed with it

An empty password field alone changes nothing

Emptying the password field on its own keeps the stored password - an empty field means "no change", not "clear it". To remove just the password and keep the username (some proxies accept a known user with no password), click the trash icon shown next to the field whenever one is on record - it marks the password for removal without touching the username. Clearing the username also removes the password, since there is then no user left to authenticate as.

Test the connection before you rely on it

Test connection asks the proxy to open a tunnel, right now, using the values currently in the form - including the stored password if you have not typed a new one, unless you have just marked it for removal with the trash icon, in which case the test reflects that too. Nothing is saved, so you can test before committing. While the proxy is switched on, this is also what unlocks Save - see above.

Result What it means What to check
Reached the proxy … and opened a tunnel The proxy is reachable, speaks the proxy protocol, and accepted the credentials Nothing - you are good to save
The proxy … rejected the credentials The proxy answered, but refused the username and password The username and password; some proxies also restrict which users may reach which destinations
Reached the proxy … but it could not open a tunnel The proxy is working, but will not let this traffic out The proxy's own egress rules - it is refusing the destination, not ezSign
… responded but is not an HTTP proxy Something is listening on that port, but it is not a forward proxy The port number - this is usually a different service
Could not reach the proxy … Nothing answered The hostname and port, and whether a firewall is in the way

Every change is recorded

Each change is written to the event log (Audit → Events) as an administrative event, so there is a record of who changed the network path and when:

  • switching the proxy on or off is recorded as its own event, with the proxy's address;
  • editing the configuration is recorded as a separate event naming the fields that changed - host, port, no-proxy hosts, credentials.

The log records which fields changed, never their values: a password change appears as credentials and the password itself never appears anywhere in the log.

Saving without changing anything writes nothing and records nothing.

Setting the proxy up during initialization

The proxy can also be configured during first-time setup, as step 4 of the initialization wizard. That step is optional and starts switched off. Whichever way you set it up, this page is where you change it afterwards.

Troubleshooting

Sign-in stopped working right after I enabled the proxy

Single sign-on goes through the proxy too. If your identity provider is inside your network, the proxy may not be able to reach it - add it to No-proxy hosts (for example *.internal) so ezSign contacts it directly.

The connection test succeeds, but ezSign still cannot reach the signing service

Test connection proves the proxy accepts ezSign and will open a tunnel. It does not prove the proxy is allowed to reach that particular destination. Check the proxy's egress rules for the signing service address, which you can see under Settings → Backend.

I changed the proxy but the old one still seems to be in use

A saved change applies to new connections. A connection already open continues on the old path until it closes. If you need the change to apply everywhere immediately, restart ezSign.

Saving reports that the password cannot be stored

ezSign encrypts stored secrets with a key supplied at deployment time. If that key is not configured, it refuses to store a password rather than keep it unprotected. Ask whoever deployed ezSign to configure the encryption key, then save again.

FAQ

Why is the Save button disabled?

Because the proxy is switched on and either the host/port are not filled in yet, or Test connection has not succeeded for the values currently in the form. A note next to the button explains which. Fill in the host and port, then select Test connection; once it succeeds, Save becomes clickable. Editing any field afterward - including the host, port, no-proxy hosts, username or password - requires testing again before you can save. This does not apply while the proxy is switched off.

Does the proxy apply to email as well?

No. Outbound email (SMTP) always goes directly to your mail server. Everything else ezSign sends outbound goes through the proxy while it is enabled.

Does the OpenID login test use the proxy credentials?

All but one of its calls do. The check that asks your identity provider whether it accepts ezSign's client is routed through the proxy but sends no proxy username or password, because it has to be able to hear the provider say no and a proxy sign-in prompt cannot be told apart from that refusal. Behind an authenticating proxy that one check reports no usable verdict, which does not block the save. Sign-in itself uses the proxy credentials normally.

If I switch the proxy off, do I lose its settings?

No. The host, port, no-proxy hosts and credentials are all kept. Switching the proxy back on needs nothing re-entered, including the password.

Why does the password field look empty when a password is stored?

The stored password is encrypted and cannot be read back, so it is never displayed. The dots are a placeholder telling you one is on record. Leave the field empty to keep it.

How do I remove just the proxy password, keeping the username?

Click the trash icon next to the password field - it appears whenever a password is on record - then save. Emptying only the password field on its own keeps the stored password, because an empty field means "no change"; the trash icon is the explicit way to say "delete it". Changed your mind? Click it again, or just start typing a new password, and the removal is cancelled.

How do I remove all the proxy credentials?

Clear the username and save. With no user to sign in as, the stored password is removed along with it.

Do I need to restart ezSign after changing the proxy?

No. A saved change applies to new outbound connections immediately. Connections already open finish on the old path.

Is a proxy change recorded anywhere?

Yes. Every change is written to the event log under Audit → Events - switching the proxy on or off as one event, and edits to the configuration as another that names the changed fields. Values of credentials are never recorded.