Skip to content

ezSign - Operator OpenID

Operators - the people who sign documents - sign in to the operations area through your organization's single sign-on (OpenID Connect). The Operator page under Settings → OpenID is where an administrator points ezSign at that identity provider, and where they change or remove it later.

This setting is optional. A deployment that never configures it is perfectly healthy: the operations area simply says operations are not yet available, and everything else - the administration console, group management, the signing service connection - carries on as normal. That makes this the page you use to switch operator access on for the first time, long after ezSign was installed.

Open it from the administration area: Settings → OpenID → Operator.

Who does this

This is an administrator task. Operators never configure their own sign-in, and never see this page. Administrator sign-in is configured separately under Settings → OpenID → Admin.

What happens while it is unconfigured

Until a provider is entered here, the page shows a standing notice saying so, and the operations area serves an "Operations not yet available" page to anyone who visits it.

flowchart LR
    A["Operator visits<br/>the operations area"] -->|"not configured"| B["Operations not yet<br/>available page"]
    A -->|"configured"| C["Sign-in at your<br/>identity provider"]
    C --> D["Groups claim decides<br/>what they may sign"]
    E["Administration console"] -->|"always available"| F["Settings · Groups · Audit"]

Figure: Operator sign-in is a separate door from the administration console. Leaving it unconfigured closes that door and affects nothing else.

Fields

Field Required? Description
Issuer URL Required Your provider's realm base URL, e.g. https://idp.example.com/realms/ezsign. The sign-in endpoints are discovered from it - so this is the realm address, not a login endpoint.
Client ID Required The OIDC client registered for the ezSign operations area at your provider.
Groups claim Required The name of the token claim that carries the signed-in person's operator groups, e.g. groups. It must match what your provider sends. The placeholder shows the claim this deployment reads today.
Client secret Optional Only needed when your provider registered this as a confidential client. Stored encrypted and never shown again - see below.
Scopes Optional Requested at sign-in, entered as chips. Your provider must offer each one. openid is always requested and cannot be removed.

Select Save & verify to test and store the change. A saved change applies to new sign-ins straight away; no restart is needed.

Save & verify stays disabled until you change something

Once the stored configuration shows VERIFIED, the button is greyed out on a page you have only read. Edit any field - or type a secret, or arm its trash icon - and it becomes clickable.

While the pill says NOT VERIFIED the button stays clickable on a page you have not touched. That is deliberate: nothing has tested the stored settings yet, and selecting Save & verify without changing anything is how you test them. Settings entered in the setup wizard arrive in exactly this state, because the wizard does not run a login test.

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

The status pill: VERIFIED and NOT VERIFIED

The pill in the card header says whether the stored configuration has ever been proved by a login test, and the timestamp next to Save & verify says when.

Pill What it means
VERIFIED (green) A login test proved these settings at the time they were stored
NOT VERIFIED (amber) Nothing has ever proved the stored settings - including an installation set up by the setup wizard, which runs no login test

Amber is not a fault. It means "not demonstrated", not "broken". Saving the settings again from this page runs the test and turns the pill green.

Green does not mean working right now

Nothing re-tests on a schedule. The pill records that a test once passed, so it stays green even if your provider later rotates the client secret away underneath it.

Why there is no confirmation step here

The admin page puts a change on probation and waits for a real sign-in before storing it. This page does not: it stores a change as soon as the login test passes.

The difference is what a mistake costs. A broken admin provider locks administrators out of the very console they would need to fix it. A broken operator provider cannot do that - the administration console has its own separate sign-in, its own provider and its own configuration, so an administrator can always get in and correct or remove what is here.

Operator sign-in is not proved until someone uses it

The login test reaches your provider and checks the client and the scopes, but it never completes an interactive sign-in - so it cannot see the groups claim or check the redirect URI. After saving, have one operator sign in. If they are refused with a permission error after an otherwise perfect sign-in, the groups claim is the first thing to check.

Removing the configuration

Remove configuration, at the bottom-left of the card, clears the whole stored operator provider: issuer, client ID, client secret, scopes and groups claim. It asks for confirmation first.

Afterwards the page returns to its unconfigured state, and operators see the "Operations not yet available" page again until a provider is entered from scratch. Administrator sign-in and document signing are unaffected.

Removal is not a pause

Nothing is kept back for later - not the issuer, and not the client secret. Setting operator sign-in up again means re-entering every field. If you only want to point operators at a different provider, edit the fields and save instead of removing first.

The client secret is write-only

Where your provider registered a confidential client, the secret is encrypted as soon as you save it and can never be read back - not by you, and not by the page.

What you see What it means What to do
The field shows dots as a placeholder, with a trash icon A secret is on record Leave the field empty to keep it
You click the trash icon Marks the secret for removal Select Save & verify to remove it, or click the icon again to change your mind
You type a new secret Replaces the stored one Select Save & verify to test and store it
The field is greyed out with a note about ALPINE_SIGN_SECRET This deployment has no encryption key configured, so no secret can be stored Ask whoever deployed ezSign to configure the key

Changing the issuer means re-entering the secret

A stored secret belongs to the provider it was issued by. If you change the Issuer URL while a secret is on record, ezSign refuses the save and asks you to re-enter it.

What this page cannot change

Who may sign, and with which keys, is not set here. An operator's access comes from matching a group's configured OIDC claims on the Groups page. This page decides which claim their group membership is read from; the Groups page decides what that membership grants.

So no save on this page can widen who counts as an operator or what they may sign with.

Test the settings before you rely on them

The login test runs inside Save & verify, against the exact values in the form. There is no separate Test button, because the test is a precondition of the save rather than something you can do instead of it. A refusal that belongs to a particular field is shown under that field; everything else appears as a notice at the top of the card. Either way, nothing is stored.

To test settings you have already stored, select Save & verify without changing anything. The test runs, the pill turns VERIFIED, and nothing is rewritten - there was nothing to rewrite. This is how you prove settings that were entered in the setup wizard, and how you recover after a refusal: correct the wrong value back to what it was and the button is still there to press.

Result What it means What to check
The issuer answered and this is a public client Everything reachable was checked; there is no secret to test Nothing - have an operator sign in to confirm
The identity provider accepted the client ID and secret Your provider authenticated ezSign Nothing - have an operator sign in to confirm
The identity provider rejected the client secret Your provider answered but refused the credentials Re-enter the secret, and check the client ID belongs to this issuer
The identity provider would not identify this client Either the client is registered as confidential and needs a secret, or that client ID does not exist at this issuer - your provider answers both the same way Check the client ID first, then enter the secret if the client really is confidential
The identity provider does not offer … A requested scope is not advertised by your provider - the message lists the ones that are Remove the scope, or add it at your provider
Could not reach … Nothing answered at that address The URL, and whether this server can reach it - through the forward proxy if one is configured
… is not an OpenID provider Something answered, but not a discovery document A trailing path on the issuer - it is the realm base URL, not a login endpoint
… reports its issuer as … The address works but your provider calls itself something else Use the issuer exactly as your provider states it
The issuer did not finish answering within … Your provider was reachable but too slow The provider's health, and any proxy in between
… gave no usable verdict on the client secret Your provider answered without a clear yes or no Nothing to fix - the settings were stored; have an operator sign in to confirm
Too many login tests are running Several tests are in flight at once Try again in a moment

When the verdict is inconclusive

The credential check needs a direct answer from your provider's token endpoint. When that call cannot be made at all, ezSign reports no usable verdict rather than guessing. Two things cause it: a transient network fault, and an authenticating forward proxy - this one check reaches the token endpoint through the proxy but does not send proxy credentials to it, so behind a proxy that demands a sign-in it has nothing to report. See Proxy settings.

An inconclusive verdict does not block the save. A provider that answers and refuses the client is a different case entirely, and is always reported as a refusal - never as an inconclusive result.

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 operator sign-in and when:

  • a change is recorded naming the fields that changed - issuer, client id, client secret, scopes, groups claim;
  • a change the login test refused is recorded too, even though nothing was stored;
  • a removal is recorded as its own event, noting that operator sign-in is unavailable until it is configured again.

The log records which fields changed, never their values: a new secret appears as client secret and the secret itself never appears anywhere in the log.

Saving without changing anything writes nothing and records nothing.

Setting operator sign-in up during initialization

Operator sign-in can also be configured during first-time setup, as step 2 of the initialization wizard. That step is optional and often skipped, since operator access is frequently arranged after the deployment is running. Whichever way you set it up, this page is where you change it afterwards - and it is also where the scopes and the client secret become editable.

Troubleshooting

Operators see "Operations not yet available"

No operator provider is configured. That is a supported state, not a fault - fill in the fields on this page and save. If you have saved a provider and operators still see that page, check that the save succeeded: a refused login test leaves the previous state untouched.

An operator signs in successfully but is then refused with a permission error

Sign-in worked; their groups did not arrive in a form ezSign could use. Either the Groups claim names a claim your provider does not send, or the groups it sends do not match any group's configured OIDC claims on the Groups page. This is the failure the login test cannot catch, because it never sees a user token.

The login test passed but sign-in redirects fail

The test cannot check the redirect URI, since it never completes an interactive sign-in. Check that your provider has ezSign's operations redirect URI on the client's allow-list.

I removed the configuration by mistake

Nothing is recoverable from the page - removal clears every field, including the client secret. Re-enter the provider details and save. The removal itself is recorded in the event log, which is the only place that will still show it happened.

Saving reports that the client secret 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 secret rather than keep it unprotected. Ask whoever deployed ezSign to set ALPINE_SIGN_SECRET and a unique ALPINE_SIGN_SALT, then save again.

The settings saved but a warning says they are not in use yet

The save succeeded; ezSign could not rebuild its live sign-in configuration straight away. The change takes effect at the next sign-in regardless. If it persists, restart ezSign.

FAQ

Is operator sign-in required?

No. It is optional, and a deployment that never configures it runs normally - the administration console, group management and the signing service connection are all unaffected. Only the operations area is closed.

What do operators see while it is unconfigured?

An "Operations not yet available" page. Nothing is broken and nothing needs restarting; the page becomes the real operations area as soon as a provider is saved here.

Why is there no sign-in confirmation step like the admin page has?

Because a broken operator provider cannot lock anyone out. The administration console has its own separate sign-in, so an administrator can always get in and correct or remove these settings. The admin page needs probation precisely because a mistake there would close the only door back in.

Why is the Save & verify button disabled?

Because the stored configuration is already VERIFIED and nothing on the page has changed yet. Edit any field - or type a client secret, or arm its trash icon - and the button becomes clickable.

If the pill says NOT VERIFIED, the button is not disabled at all: select it without changing anything to run the login test against the settings that are already stored.

What exactly does Remove configuration clear?

The whole stored operator provider: issuer, client ID, client secret, scopes and groups claim. Nothing is kept back, so setting operator sign-in up again means re-entering every field.

Does removing operator sign-in affect administrators or document signing?

No. Administrator sign-in uses its own provider and its own configuration, and signing is unaffected. Only operator access to the operations area stops.

Which groups may sign, and where is that set?

Not here. This page sets which token claim group membership is read from; what a group is allowed to sign with is configured per group on the Groups page.

Do I need to restart ezSign after changing operator sign-in?

No. A stored change applies to new sign-ins immediately. Operators already signed in are unaffected until their session ends.