Skip to content

ezSign - Backend

ezSign does its work on your own network, but it does not work alone. To sign a document it sends the document's hash to a remote signing service, and to manage the keys that do the signing it talks to AlpinePKI over a separate administrative channel. The Backend page holds the two addresses those conversations use.

Those addresses were set once, during first-time setup, in step 5 of the initialization wizard. That wizard closes for good when setup finishes. This page is what makes the same wiring readable and editable for the rest of the installation's life - when the signing service moves to a new hostname, when a certificate authority changes, or when you simply want to check what is configured.

Open it from the administration area: Settings → Backend.

Who does this

This is an administrator task. Operators - the people who sign documents - never see this page. Nothing here changes how documents are signed; it changes only where ezSign goes to sign them.

What the two endpoints do

The two addresses carry very different traffic, which is why they are configured separately.

The DSS signer endpoint is where document signing happens. ezSign sends only the document's hash - a short fingerprint - and receives a signature back. The document itself never leaves this installation.

The DSS-admin gRPC endpoint is the key-management channel. It carries a bearer token that authorises every key operation for your organization, which is why its transport security matters so much.

flowchart LR
    A["ezSign<br/>(your network)"] -->|"document hash only"| B["DSS signer endpoint<br/>https://signer.example.com"]
    A -->|"key management, bearer token"| C["DSS-admin gRPC<br/>grpcs://admin.example.com:443"]
    D["Your documents"] --> A
    A -.->|"never sent"| B

Figure: Only the document hash goes to the signer, over the signer endpoint. Key management travels a separate gRPC channel. The documents themselves stay inside your network.

Fields

Field Required? Description
DSS signer endpoint Required The signing service's base address, e.g. https://signer.example.com.
DSS-admin gRPC Required The key-management address as a single target, e.g. grpcs://admin.example.com:443. The scheme selects transport security - see below. Both a host and a port are required.
Override SSL settings Optional Leave off for standard server-side TLS. Turn it on to verify the DSS-admin server with a private certificate authority, to present a client certificate, or both. Switching it on reveals the three fields below.
Trusted certificate chain One of these two, when the override is on The CA-chain file used to verify the DSS-admin server. Accepted formats: .pem, .crt, .cer.
Client key (PKCS#12) One of these two, when the override is on A .p12 or .pfx file holding the client certificate and private key ezSign presents to the server.
PKCS#12 password With a client key The passphrase that opens the client key file.

Select Save to apply. No restart is needed.

Changes take effect immediately

The updated endpoints are used from the next backend call onwards. ezSign keeps its backend connections open rather than re-dialling for every call, so saving closes the old ones - and a signing job that happens to be talking to the backend at that exact moment may fail and need retrying. Save during a quiet period if you can.

These fields re-address the same backend

This is the one thing on this page worth reading twice.

Your installation has an identity at the backend: a tenant, a signing-service instance, and an authentication key that ezSign generated during setup and enrolled with the backend on your first administrator sign-in. Saving on this page carries all of that across untouched. The fields correct where the backend lives - not which backend it is.

A different backend will accept the connection and reject every call

Point these fields at a genuinely different backend and everything this page can check will pass. The save succeeds, the pill reads CONFIGURED, and Test backend reachability can even answer REACHABLE - because a network handshake proves only that something is listening, never that the far end recognises this installation's enrolled key. Every real call then fails as unauthenticated. There is no way to recover from that on this page: moving an installation to another backend means provisioning it there and enrolling its key again.

So: a signer that moved to a new hostname, a gRPC endpoint on a new port, a certificate authority that changed - all fine. A move to a different backend is not a settings change.

Transport security on the admin channel

The DSS-admin gRPC field's scheme decides how the channel is protected:

Scheme What it means
grpcs:// The channel is encrypted with TLS. Use this.
grpc:// The channel is not encrypted. Intended for local development installs only.

Saving a grpc:// endpoint asks for confirmation

The admin channel carries a bearer token that authorises every key operation for your organization. Unencrypted, that token can be captured and replayed for as long as it stays valid. Saving an endpoint that starts with grpc:// therefore raises a confirmation dialog - Save an unencrypted admin channel? - which you must accept before the save goes through.

Mutual TLS with the SSL override

Leave Override SSL settings off and ezSign verifies the DSS-admin server the ordinary way, against the certificate authorities the system already trusts. Turn it on when that is not enough:

  • the DSS-admin server presents a certificate from a private certificate authority the system does not trust - upload that CA's chain as the Trusted certificate chain;
  • the server requires a client certificate - upload it, with its private key, as the Client key (PKCS#12) and supply the PKCS#12 password.

You can provide either one or both, but the override cannot be switched on with neither.

The three TLS values are write-only

The certificate chain, the client key and the passphrase are sealed as soon as you save them and can never be read back - not by you, and not by the page. A browser also never re-sends a file you chose on an earlier visit. Together those two facts give the fields one simple rule:

What you see What it means What to do
The file picker reads Chain on record or Client key on record A file is stored Leave it alone to keep it, or choose a file to replace it
The password hint says a passphrase is on record A passphrase is stored Leave the field empty to keep it
Nothing on record The override has never been configured Choose the files and enter the passphrase

Unticking the override deletes all three, permanently

Saving with Override SSL settings switched off clears the stored chain, client key and passphrase together. They are sealed, so they cannot be shown to you again - restoring them means uploading the files afresh, and you may no longer have them. A confirmation dialog - Clear the mutual-TLS material? - guards this whenever something is actually on record.

Clearing does not switch the channel back to plain TLS. It leaves the channel trusting only the certificate authorities the system already trusts, so if the DSS-admin server uses a private CA, the channel stops connecting until a chain is uploaded again.

Test the connection before you rely on it

Test backend reachability probes both endpoints, right now, using the values currently in the form - including any files you have just chosen. Nothing is saved, so you can check before committing. The button stays disabled until both endpoint fields have something in them, since a probe with no target can only tell you it has no target.

The probe is not a formality. For a grpcs:// target it performs a real TLS handshake with the materials the live channel would use, so a missing CA chain or a required client certificate shows up here rather than in the middle of a signing job. A grpc:// target is only checked for a listening port, there being no handshake to make.

Result What it means What to check
Backend is reachable Every endpoint you supplied answered Nothing - you are good to save
signer endpoint is unreachable Nothing answered at the signer address The hostname, the port, and whether a firewall or the outbound proxy is in the way
signer endpoint is not a valid URL The address could not be read as a URL The scheme and the spelling - it needs the full https://host form
gRPC admin target is unreachable Nothing answered at the DSS-admin address The hostname and port; remember gRPC often uses a port of its own, such as 443
the backend requires a client certificate The server answered but wants ezSign to identify itself Turn on Override SSL settings and upload a client PKCS#12
the backend TLS certificate is not trusted The server answered but its certificate is signed by an authority this system does not know Upload that authority's chain under Override SSL settings
the TLS handshake with the gRPC admin target failed The connection was made but the two sides could not agree on TLS The chain and the client key, and that the address really is the gRPC endpoint
the SSL-override materials are invalid The uploaded files could not be used to build a TLS context That the chain is a certificate file and the PKCS#12 opens with the passphrase you gave

When more than one endpoint fails, the verdicts are shown together, separated by semicolons.

What the status pill tells you

The pill beside the card title shows one of four words, and the page is careful never to claim more than it knows.

Pill When you see it What it proves
CONFIGURED On any ordinary page load, when an endpoint is stored Only that wiring exists. Nothing about whether it answers
NOT CONFIGURED On any ordinary page load, when nothing is stored The backend has never been wired up here
REACHABLE Only just after a probe you ran Every endpoint answered, a moment ago, with the values then in the form
UNREACHABLE Only just after a probe you ran At least one endpoint did not answer

A page load never blocks on a remote handshake to draw its own header, which is why loading the page can only ever show the first two. And because a green REACHABLE is a statement about the values that were probed, editing any field takes it away again - the pill returns to what it read on load and the verdict line clears. That is deliberate: a green claim must not outlive the values that earned it.

CONFIGURED is a fact about the past, not the present

CONFIGURED and REACHABLE are both green, and they mean different things. Because saving requires a passing test, CONFIGURED does tell you the wiring worked at the moment it was saved - but that may have been months ago, and nothing since has re-checked it. A backend that went away yesterday still shows CONFIGURED today. Only a REACHABLE verdict you have just produced with Test backend reachability speaks for right now.

Save is disabled until a connection test passes

Save stays disabled - with a note next to the button explaining why - until both endpoints are filled in and Test backend reachability succeeds for the values currently in the form. This is required again on every visit, even for wiring that already works, and again after any change to either endpoint, the SSL override, the uploaded files or the passphrase. It exists so a typo cannot leave the installation pointing at a backend nobody checked was actually there.

The lock is in place from the moment the page appears, so there is no brief window on a fresh load in which Save can be pressed before it greys out.

A successful save re-locks the button, so a second save needs a second test. That is intentional: the values may have been edited in between, and the earlier verdict says nothing about the new ones.

Every change is recorded

Each accepted change is written to the event log (Audit → Events) as an administrative event, so there is a record of who changed the path to the backend and when. The entry names the fields that changed: DSS signer endpoint, DSS-admin gRPC endpoint, DSS-admin gRPC transport security, or mutual-TLS material.

Running Test backend reachability is recorded too, with the two endpoints that were probed.

The log records which fields changed, never their values. A replaced certificate chain or passphrase appears only as mutual-TLS material, and the material itself never appears anywhere in the log.

Saving without changing anything writes nothing and records nothing - the page simply tells you there were No changes to save.

Setting the backend up during initialization

The same two endpoints, and the same SSL override, are configured as step 5 of the initialization wizard when ezSign is first set up. That step is required - ezSign cannot sign anything without it. Whichever way it was set up, this page is where you change it afterwards.

Troubleshooting

Signing and key management suddenly stopped working, with no obvious cause

Check this page first, and press Test backend reachability.

The wiring was proven reachable when it was saved - that is what the save gate guarantees - but nothing re-checks it afterwards. A backend that has since moved, gone down, or had its certificate replaced shows no symptom at all until something needs it. Operators then see signing fail, administrators see key operations fail, and both appear as a general "the request could not be completed" error that names no cause. A green CONFIGURED pill here does not rule this out - it reports the last save, not today.

The probe is what turns that guesswork into an answer: it contacts both endpoints and says which one is not answering, and why. If it comes back Backend is reachable, the problem is somewhere else and you can stop suspecting the wiring.

If the endpoints were changed recently, check the event log (Audit → Events) for who changed them and when - a failure that started right after a backend change is rarely a coincidence.

The test says the backend is reachable, but every signing job fails

Reachability and authorisation are different questions. The probe proves something is listening and, for a grpcs:// target, that TLS succeeds. It cannot prove that the far end recognises this installation.

If the endpoints were changed to point at a different backend rather than at a new address for the same one, that is exactly the symptom: the connection works and the calls are rejected. The identity of this installation - its tenant, its signing-service instance, its enrolled key - is not carried by these fields. Moving to another backend means provisioning this installation there and enrolling its key again.

The test reports that the backend requires a client certificate

The DSS-admin server is configured for mutual TLS: it wants ezSign to identify itself with a certificate of its own. Turn on Override SSL settings, upload the Client key (PKCS#12) your administrator issued for this installation, and enter its PKCS#12 password. Then test again.

The test reports that the backend certificate is not trusted

The DSS-admin server's certificate was issued by a certificate authority this system does not know about - typically a private CA inside your organization. Turn on Override SSL settings and upload that authority's chain as the Trusted certificate chain. A public CA would already be trusted, so this almost always means a private one.

Saving reports that the mutual-TLS material cannot be stored

ezSign seals stored secrets with a key supplied at deployment time. If that key is not configured, it refuses to store the chain, client key and passphrase rather than keep them unprotected. Ask whoever deployed ezSign to configure the sealing key, then save again. The two endpoint fields are unaffected and can still be saved on their own.

Saving reports that the uploaded file could not be read

The upload did not arrive intact - most often an interrupted request or a file that changed on disk mid-upload. Choose the file again and retry. Nothing was stored, so the material already on record is untouched.

The admin channel stopped connecting after I turned the SSL override off

Turning the override off deletes the stored CA chain. If the DSS-admin server uses a private certificate authority, that chain was what made the channel trust it - without it, the channel trusts only the authorities the system already knows, and the server's certificate is no longer among them. Turn the override back on and upload the chain again. It cannot be recovered from ezSign, since sealed material is never readable back.

FAQ

Why is the Save button disabled?

Because either both endpoints are not filled in yet, or Test backend reachability has not succeeded for the values currently in the form. A note next to the button says which. Fill in both endpoints, select Test backend reachability, and once it passes, Save becomes clickable.

Editing anything afterward - either endpoint, the SSL override, the uploaded files or the passphrase - requires testing again, because a verdict earned by the old values proves nothing about the new ones.

Why do I have to test again after saving?

Saving reloads the form, and the fresh form arrives untested, so Save locks again. This is intentional rather than an oversight: between one save and the next the values may have changed, and the earlier verdict would no longer be about what you are saving. If you are saving the same values twice over, simply press Test backend reachability again first - it takes a moment and writes nothing.

How would I know if the backend stopped being reachable?

You would not, until something needs it. Saving proved the wiring reachable at the time, but nothing re-checks it afterwards: ezSign does not poll the backend or raise an alert, and this page does not contact it when it loads - so a backend that went away yesterday still shows CONFIGURED today. The first sign is an operator unable to sign or an administrator unable to manage a key.

If you want certainty, press Test backend reachability. That is the only action in ezSign that checks, and it is safe to run at any time: it writes nothing, changes nothing, and needs no restart.

Why do the file pickers say something is on record instead of showing the file?

The certificate chain, client key and passphrase are sealed when saved and cannot be read back, so there is nothing to show you. The "on record" wording is how the page tells you something is stored. Leave the controls alone to keep it, or choose a new file to replace it.

Can I point ezSign at a different backend from this page?

No. These fields re-address the same backend - they correct where it lives. Your installation's identity and its enrolled authentication key stay as they are, so a genuinely different backend will accept the connection and then reject every call. Moving to another backend requires provisioning this installation there and enrolling its key again.

Do I need to restart ezSign after changing the backend?

No. A saved change applies from the next backend call. Existing connections are closed when you save, which is the one visible side effect: a signing job that was mid-call at that instant may fail and need retrying.

What happens if I untick Override SSL settings and save?

The stored certificate chain, client key and passphrase are all deleted, permanently - a confirmation dialog asks first whenever something is on record. The channel does not fall back to unencrypted TLS; it falls back to trusting only the certificate authorities the system already trusts. If the server uses a private CA, the channel will stop connecting until a chain is uploaded again.

Why is the DSS-admin address one field instead of a host, a port and a TLS setting?

Because the scheme already carries the TLS setting. grpcs://admin.example.com:443 says host, port and transport security in one line that can be copied straight from your provisioning details, with nothing to get out of step. grpcs:// means encrypted, grpc:// means not.

Is grpc:// ever acceptable?

Only on a local development install. The admin channel carries a bearer token authorising every key operation for your organization, and unencrypted it can be captured and replayed while it remains valid. Saving a grpc:// endpoint raises a confirmation dialog for exactly that reason.

Is a backend change recorded anywhere?

Yes. Every accepted change is written to the event log under Audit → Events, naming the fields that changed - the signer endpoint, the gRPC endpoint, its transport security, or the mutual-TLS material. Reachability probes are recorded as well. Values are never recorded, so a replaced certificate or passphrase appears only as the field name.