Skip to content

ezSign - Initialization

Initializing ezSign for the first time is a short, guided, one-time task an administrator completes in the browser. You work through a six-step setup wizard, then sign in once as an administrator - that sign-in brings ezSign online.

Setup happens in two phases:

  1. Staged - the wizard saves your settings and prepares your organization's authentication key.
  2. Complete - your first successful administrator sign-in finishes setup and brings the operator and administration areas online.

Who does this

This is an administrator task, done once when ezSign is first installed for your organization. Operators - the people who sign documents - never see it. If ezSign has already been set up, you can skip this page.

Before you start

Have these ready. Your {{ product_name }} contact provides anything you were not given at handover.

What {{ product_name }} gives you (from provisioning your tenant):

  • Tenant UUID - identifies your organization, in the form tnt-….
  • DSS module UUID - identifies your signing service instance, in the form mod-….
  • Shared secret - a one-time code that authorizes this proxy on first contact.
  • Connection details - the signing service (signer) address and the DSS-admin address ezSign connects to.

The shared secret is single-use

The shared secret is issued once when your tenant is provisioned and is consumed only on a successful first administrator sign-in. Keep it safe. If it is lost, ask your {{ product_name }} contact to re-issue it - see provision dss.

What you provide on your side:

  • Single sign-on (OIDC) details for administrator sign-in - the issuer URL and a client ID. Operator sign-in is optional and can be added now or later.
  • Email server (SMTP) details, if you want ezSign to send notifications (optional).
  • A forward proxy, only if your network routes outbound traffic through one (optional).

How setup works

flowchart TD
    A["Receive provisioning details<br/>(tenant UUID, module UUID, shared secret, addresses)"] --> B["Open the setup wizard<br/>/admin/init"]
    B --> C["Complete the six steps<br/>(settings staged)"]
    C --> D["Sign in as an administrator"]
    D --> E{"Backend registers<br/>your authentication key?"}
    E -- "Yes" --> F["Setup complete<br/>operator + administration areas online"]
    E -- "No (secret rejected or backend unreachable)" --> G["Re-enter the shared secret and retry"]
    G --> D

Figure: The initialization flow - the wizard stages your settings, and the first successful administrator sign-in completes setup.

Step 1 - Open the setup wizard

Open the ezSign administration address in your browser (for example https://admin.ezsign.<your-company>). Until setup is complete, the administration address takes you straight to the wizard at /admin/init - there is no separate unlock screen.

The wizard has six steps. Only steps you can complete right now are required; the rest are optional and can be set later from the administration area.

Step What it configures Required?
1. Admin OIDC How administrators sign in Required
2. Operator OIDC How operators sign in Optional (now or later)
3. Mail Notification email Optional
4. Proxy Outbound network routing Optional (now or later)
5. Backend Connection to the signing service Required
6. Provisioning Your tenant identity and shared secret Required

Step-by-step

Each step validates what you enter before it lets you continue. Nothing is saved until you finish the final step, so you can move back and forth freely.

Step 1 - Admin OIDC (required)

How administrators sign in, via your organization's single sign-on (OpenID Connect).

Field Required? Description
Issuer URL Required Your identity provider's issuer address, e.g. https://id.example.com/realms/sign. ezSign discovers the sign-in endpoints from it automatically.
Client ID Required The OIDC client ID registered for ezSign administration, e.g. alpine-sign-admin.

Who counts as an administrator is set at install time

There is no admin-group field here. Administrator access is granted by a fixed, deployment-defined group list (set when ezSign is installed), so a wizard mistake can never widen or close the admin gate.

The wizard asks only for the issuer and client ID, and runs no login test. The scopes, the client secret and the groups claim become editable afterwards on the Admin OpenID page, which is also where you change any of this later - safely, because a change there has to be proved by a real sign-in before it is stored.

Step 2 - Operator OIDC (optional)

How operators - the people who sign documents - sign in. This step is optional - configure it now, or add it later from the administration area.

Field Required? Description
Issuer URL Optional* Operator identity provider issuer, e.g. https://id.example.com/realms/sign.
Client ID Optional* The OIDC client ID for the operator area, e.g. alpine-sign-app.
Group claim Optional Name of the token claim that carries group membership. Defaults to groups.

*If you fill in any operator field, the issuer URL and client ID become required together.

You can add operator sign-in later

If you leave this step blank, the operator area shows an "operations not yet available" message until an administrator configures it from the administration area - on the Operator OpenID page, which is also where you change or remove it later.

Step 3 - Mail (optional)

An email server so ezSign can send notifications. Leave the host blank to run without email.

Field Required? Description
SMTP host Optional Mail server hostname, e.g. smtp.example.com. Blank leaves email unconfigured.
Port Required if host set Mail server port, e.g. 587.
Security - Connection security: STARTTLS, TLS, or None.
From address Optional Sender shown on notifications, e.g. no-reply@example.com. A plain address only - a display name such as ezSign <no-reply@example.com> is rejected.
Username Optional Sign-in user for the mail server. Leaving it blank uses an unauthenticated relay; a non-blank username turns authentication on.
Password Optional Password for the mail user. Stored encrypted.

Use Test connection to check the mail settings before you continue. ezSign also verifies the connection when you submit the wizard.

Step 4 - Proxy (optional)

A forward (egress) proxy for ezSign's outbound connections. It starts switched off - leave it that way if your network reaches the internet directly, and select Continue. Switching it on reveals the fields.

Field Required? Description
Enabled - Route all outbound traffic through a forward proxy.
Proxy host Required if enabled Forward proxy hostname, e.g. proxy.example.com.
Port Required if enabled Forward proxy port, e.g. 8080.
No-proxy hosts Optional Comma-separated addresses to reach directly, e.g. localhost,127.0.0.1,*.internal.
Username / Password Optional Credentials if the proxy requires authentication. The password is stored encrypted.

One proxy for all outbound traffic

When enabled, the proxy is used for every outbound connection - the signing service and single sign-on included. Outbound email (SMTP) is the exception and always goes directly to your mail server. Use Test connection to check it.

Continue is disabled until a connection test passes

Once you switch the proxy on, Continue stays disabled - with a note next to the button explaining why - until the host and port are filled in and Test connection succeeds for the values currently in the form. Editing the host, port, no-proxy hosts, username or password afterward requires testing again. This prevents finishing setup with a proxy address that was never actually confirmed reachable. Switching it back off removes the requirement immediately.

You can change this later

The proxy is not a one-time decision. After setup, an administrator can add, change, or switch it off at any time under Settings → Proxy - see Proxy settings.

Step 5 - Backend (required)

The connection to the central signing service.

Field Required? Description
DSS signer endpoint Required The signing service base address, e.g. https://signer.example.com.
DSS-admin gRPC Required The DSS-admin address as a single target, e.g. grpcs://admin.example.com:443. The scheme selects transport security: grpcs:// uses TLS, grpc:// is plaintext.
Override SSL settings Optional Leave off for standard server-side TLS. Turn on to set up mutual TLS on the admin channel with a private certificate authority and/or a client certificate.

When Override SSL settings is on, you must provide a trusted certificate chain, a client key, or both - the override cannot be enabled with neither:

Field Required? Description
Trusted certificate chain One of these two CA-chain file (.pem, .crt, .cer) used to verify the DSS-admin server.
Client key (PKCS#12) One of these two A .p12/.pfx file holding the client certificate and private key ezSign presents to the server.
PKCS#12 password With a client key Passphrase that opens the client key file.

Continue is disabled until a connection test passes

Continue 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. Editing any of them afterward, including the SSL override and its files, requires testing again. Unlike the proxy step there is no way to switch this requirement off: ezSign cannot sign anything without a backend it has actually reached, so finishing setup with an address nobody confirmed would leave the installation unusable.

You can change this later

The backend addresses are not a one-time decision. After setup, an administrator can view and change them at any time under Settings → Backend - see Backend settings.

Step 6 - Provisioning (required)

The identity and secret {{ product_name }} issued for your tenant. These come from the provisioning output you received - see provision dss.

Field Required? Description
Tenant UUID Required Your tenant identifier, in the form tnt-….
DSS module UUID Required Your signing service instance identifier, in the form mod-….
Shared secret Required The one-time provisioning secret. It is verified by the backend at your first admin sign-in; a wrong secret is never consumed, so a mistake here is safe to retry.

ezSign creates your authentication key automatically

When you finish this step, ezSign generates your organization's authentication key (an EC key) and stages your configuration. Its public key is registered with the backend on your first administrator sign-in - you do not create or upload any key yourself.

Select Provision & finish to stage the configuration and go to administrator sign-in.

Complete setup - sign in as an administrator

After the wizard stages your settings, sign in with an account in your organization's administrator group.

sequenceDiagram
    participant Admin as Administrator
    participant ezSign as ezSign proxy
    participant Backend as Signing backend
    Admin->>ezSign: Sign in (administrator)
    ezSign->>Backend: Register authentication key (with shared secret)
    alt Secret accepted and backend reachable
        Backend-->>ezSign: Registration confirmed
        ezSign-->>Admin: Setup complete - areas online
    else Secret rejected or backend unreachable
        Backend-->>ezSign: Registration failed
        ezSign-->>Admin: Re-enter shared secret and retry
    end

Figure: The first administrator sign-in completes setup by registering ezSign's authentication key with the backend.

That first successful sign-in completes setup: ezSign registers its authentication key with the backend using your shared secret, and both the operator and administration areas come online.

You can't lock yourself out

Until an administrator has signed in successfully, the wizard stays available, so a wrong setting can't leave you stuck. If the shared secret is rejected or the backend can't be reached, ezSign takes you to a page to re-enter the secret and try again - a wrong secret is never consumed.

After setup

  • Operators (the people who sign documents) go to the operator area to upload, track, and download signed documents.
  • Administrators use the administration area to manage who can sign and with which key profile.
  • To change sign-in, email, network, or signing-service settings later, an administrator updates them from the administration area.

Troubleshooting

The shared secret is rejected on sign-in

Check that the tenant UUID, DSS module UUID, and shared secret match the provisioning output exactly. A wrong secret is never consumed, so you can re-enter it and retry. If the secret is lost, ask your {{ product_name }} contact to re-issue it.

"Test backend reachability" fails

Confirm the signer endpoint and DSS-admin gRPC address, and whether transport security should be grpcs:// (TLS) or grpc:// (plaintext). If your network uses a forward proxy, configure it in Step 4 - Proxy. If the server uses a private certificate authority, enable Override SSL settings in Step 5 and supply the trusted certificate chain.

The email test fails

Verify the SMTP host, port, and security setting (STARTTLS, TLS, or None). For an authenticated relay, provide a username and password; leave both blank for an unauthenticated relay. Email is optional - leave the host blank to finish setup without it.

The operator area shows "operations not yet available"

Operator sign-in (Step 2) has not been configured yet. An administrator can add it later from the administration area; it does not block completing setup.

FAQ

How long does setup take?

A few minutes. It is a six-step wizard followed by one administrator sign-in.

What if I lose the shared secret?

The shared secret is issued once when your tenant is provisioned. If it is lost, ask your {{ product_name }} contact to re-issue it; the previous secret then stops working.

Where are the settings I enter stored?

They are saved by ezSign in its database - not in plain files - and sensitive values (passwords, keys, and the shared secret) are encrypted at rest. You enter them once through the wizard.

Can I change these settings later?

Yes. After setup, an administrator can update sign-in, email, network, and signing-service settings from the administration area.

Can a wrong setting lock me out?

No. The wizard stays open until the first successful administrator sign-in, and who counts as an administrator is fixed at install time - not a wizard field - so a mistake can't close the admin gate.