Skip to content

ezSign - Admin OpenID

Administrators sign in to the ezSign administration area through your organization's single sign-on (OpenID Connect). The Admin page under Settings → OpenID is where an administrator points ezSign at that identity provider, and where they change it later.

This is the one configuration on the whole console that can lock every administrator out - including out of this page, which is the only place the mistake could be undone. So it does not save the way other settings pages do: a change has to pass a live login test, and then be proved by a real sign-in, before ezSign stores it. Until that happens your previous settings stay on record and are put back automatically.

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

Who does this

This is an administrator task. Operators - the people who sign documents - never see this page, and their own sign-in is configured separately under Settings → OpenID → Operator.

How a change is proved

Save & verify does not simply write what you typed. It runs a login test, then puts the change into use for sign-in while leaving your stored settings untouched. Only a completed administrator sign-in promotes it to the stored configuration.

flowchart LR
    A["Save & verify"] --> B["Login test<br/>issuer · client · scopes"]
    B -->|"refused"| C["Nothing stored<br/>your settings unchanged"]
    B -->|"passed"| D["In use for sign-in,<br/>not stored yet"]
    D -->|"an admin signs in"| E["Stored<br/>VERIFIED"]
    D -->|"nobody signs in in time"| C

Figure: A change is tested, then used for sign-in on probation. Only a real sign-in stores it; anything else lands back on the settings that already worked.

The reason for the second step is that the login test cannot see everything. It reaches your provider, checks the client and checks the scopes - but it never completes an interactive sign-in, so it never sees a user token. Two things pass the test and still break sign-in: a groups claim your provider does not actually send, and a redirect URI your provider does not have on the client's allow-list. Both fail at the next sign-in, which is exactly when the page that could undo them is out of reach.

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 administration area at your provider, e.g. alpine-dss-admin.
Groups claim Required The name of the token claim that carries the signed-in person's admin 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 stage the change. A saved change applies to new sign-ins straight away; no restart is needed.

Save & verify stays disabled until you change something

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. It also stays clickable while a change is awaiting confirmation, which is how you reopen the sign-in prompt after dismissing it.

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, and the timestamp next to Save & verify says when.

Pill What it means
VERIFIED (green) An administrator has signed in with these exact settings, or a login test proved them at the time they were stored
NOT VERIFIED (amber) Nothing has ever proved the stored settings - including every installation set up by the setup wizard, which runs no login test

Amber is not a fault. It means "not demonstrated", not "broken" - a deployment can run perfectly well on settings that simply predate the check. It turns green the next time an administrator signs in.

Green does not mean working right now

Nothing re-tests on a schedule. The pill records that a sign-in once succeeded, so it stays green even if your provider later rotates the client secret away underneath it. When that happens, the failure is recorded in the event log as a rejected admin client credential.

Confirming a change with a sign-in

A save that passes the login test opens a prompt: Sign in again to keep this change. It has three exits, and they do different things.

What you choose What happens
Relogin to Save Signs you out and back through your provider. A successful sign-in stores the change and the pill turns green.
Add more change Closes the prompt and leaves the change in use, still unstored, so you can edit another field first. One sign-in confirms everything you saved up to that point.
✕, Esc, or clicking outside Takes this save back. Whatever you saved before it stays in use.

While a change is awaiting confirmation the card shows an amber banner saying so, with the deadline. The values on the page are the ones being tried - not the ones on record.

Batch your edits, then sign in once

There is no need to confirm field by field. Choose Add more change, make the rest of your edits, and one sign-in at the end confirms the lot.

Nobody signs in: the change discards itself

An unconfirmed change is given five minutes by default. If no administrator signs in inside that window, ezSign throws the change away and carries on with your stored settings - no intervention needed. The banner on the card names both the window and the exact deadline.

Five minutes is enough to sign out and work through a provider's login and consent screens. A provider with a slow step-up - a hardware token or an MFA push, say - may need longer, which whoever deployed ezSign can set with alpine.sign.oidc.recovery.confirm-window. Setting it to zero switches the automatic discard off; even then nothing is lost, because your stored settings were never overwritten - you just have to clear the change by hand.

Two other things clear an unconfirmed change immediately:

  • Discard this change, the button at the bottom-left of the card while something is pending. It drops the change and puts your stored settings back in use for sign-in.
  • A sign-in that actually fails against it. If someone tries the new settings and your provider refuses them, or they arrive without an admin group, ezSign discards the change there and then.

You cannot lock yourself out

The recovery story is worth stating plainly, because it is what makes this page safe to use on a live deployment: the settings that last worked are never overwritten by an unproved change. They sit in the database untouched while the candidate is on probation, and every failure path - a refused login test, a failed sign-in, an elapsed window, a discard, even a restart mid-window - lands back on them.

The sign-in failure page says the same thing, so an administrator who has just been bounced out of a save does not have to take it on trust. Under If you just changed the sign-in settings it states that the previous settings were never overwritten, that an unproved change is discarded on its own with nobody signed in, and what to do when retrying keeps returning to the same page. Every sentence there is static on purpose: the page is unauthenticated, so it names no configuration and reads nothing from the database - which means it still reads correctly when an unreachable database is itself the reason sign-in failed.

If you do somehow arrive at an administration area you cannot sign in to, there is a break-glass lever that needs no sign-in at all. Whoever deployed ezSign can set:

alpine.sign.oidc.recovery.discard-pending=true

On the next start ezSign drops any unconfirmed change, before it serves a single request, and touches nothing else. Unset it again afterwards. It is an environment variable rather than a setting on this page on purpose: reaching it needs access to the host, and that is the privilege boundary that makes a no-sign-in recovery path safe to ship.

First-time configuration is different

On a deployment nobody has ever signed in to, there is nothing proved to protect. The first configuration is stored directly, with no probation and no prompt - the same way the setup wizard writes it.

The client secret is write-only

Admin sign-in is a public client by default, so most deployments leave this field empty. 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 - carrying an old realm's secret over to a new one would fail at the next sign-in with nothing to explain it.

This field is also the way back from one specific lockout. ezSign unseals the stored secret every time it rebuilds the sign-in configuration, so rotating the deployment's encryption key leaves a secret that can no longer be read - and admin sign-in with no way in to fix it. Re-typing the secret here re-seals it under the current key.

What this page cannot change

Who counts as an administrator is not set here. That list is fixed at deployment time (alpine.sign.oidc.admin-groups) and is not editable from the console. This page can move which claim group membership is read from; it can never widen who is an administrator.

That split is deliberate. It means the worst outcome of a mistake on this page is that administrators cannot sign in - recoverable, and recovered automatically - rather than that the wrong people can.

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.

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 - sign in to confirm the change
The identity provider accepted the client ID and secret Your provider authenticated ezSign Nothing - sign in to confirm the change
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 change was accepted; sign in to confirm it works
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. Refusing it would mean a network hiccup could stop the only page that can repair a broken sign-in configuration. 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.

What the login test does not prove

It cannot check the groups claim or the redirect URI, because it never completes an interactive sign-in. That is precisely what the confirmation sign-in is for - and why a change is not stored until one happens.

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 admin 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 - an installation being pointed at a provider that will not authenticate it is exactly what the trail is for;
  • the confirming sign-in is recorded when a change is promoted to the stored configuration;
  • a discard, a take-back and a break-glass recovery each get their own event;
  • a credential failure at sign-in is recorded when your provider later rejects the stored secret.

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 admin sign-in up during initialization

Admin sign-in is also configured during first-time setup, as step 1 of the initialization wizard, which is a required step. The wizard asks only for the issuer and client ID, and runs no login test. Whichever way you set it up, this page is where you change it afterwards - and it is also where the scopes, the client secret and the groups claim become editable.

Troubleshooting

I saved a change and now nobody can sign in as an administrator

Wait five minutes. An unconfirmed change discards itself and your previous settings come back automatically - and a sign-in that actually failed against the new settings discards them immediately, so in practice the recovery has usually already happened by the time you try again.

If sign-in is still broken after that, the change was confirmed by a sign-in and is stored, which means someone got in with it. Sign in and correct it here. If nobody can, ask whoever deployed ezSign to start with alpine.sign.oidc.recovery.discard-pending=true.

"Try signing in again" looks like it does nothing

Your identity provider still has you signed in. It answers the retry without asking you anything, so the browser is sent to the provider and back to this same page in under a second - and a repeat failure looks exactly like a button that does nothing. Nothing on screen distinguishes the two.

Sign out at your identity provider, or open a private browser window, then try again. The sign-in failure page gives the same advice under If you just changed the sign-in settings.

The login test passed but signing in still fails

That is the case the confirmation step exists for. The test cannot check the redirect URI or the groups claim, so both are still unproved when it passes. Check that your provider has ezSign's admin redirect URI on the client's allow-list, and that the claim named in Groups claim is one your provider actually sends. Either way the change discards itself, so you are not stuck.

I signed in fine but got "not an administrator"

Sign-in worked; the groups did not arrive. Either the Groups claim names a claim your provider does not send, or the account is not in one of the deployment's administrator groups. A wrong claim on an unconfirmed change is discarded on the spot, so the previous settings are already back in use.

The page says a change is awaiting confirmation and I do not know what it was

The fields on the page are showing it - while a change is pending, the form displays the values being tried rather than the ones on record. Either sign out and back in to keep them, or select Discard this change to go back to the stored settings.

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

Why is the Save & verify button disabled?

Because 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. It also stays clickable while a change is awaiting confirmation, so you can reopen the sign-in prompt.

Why do I have to sign out after saving?

Because a completed sign-in is the only thing that proves the change works. The login test cannot check the groups claim or the redirect URI, so until an administrator signs in with the new settings ezSign keeps your previous ones on record and treats the change as provisional.

What happens if I close the confirmation prompt?

Closing it with ✕, Esc, or a click outside takes that save back, and whatever you saved before it stays in use. Use Add more change instead if you want to keep the change and carry on editing.

What if I never sign in to confirm a change?

After five minutes ezSign discards it and carries on with your stored settings. Nothing is left in a half-changed state, and no action is needed.

Can I lock myself out by saving bad settings here?

No. Your stored settings are never overwritten by a change that has not been proved by a sign-in, so every failure - a refused login test, a failed sign-in, an elapsed window, a restart - lands back on the configuration that already worked.

How do I recover if I am already locked out of the administration area?

Ask whoever deployed ezSign to start it with alpine.sign.oidc.recovery.discard-pending=true. Any unconfirmed change is dropped at startup, before any request is served, and nothing else is touched. Unset it once you are back in.

Why does the pill say NOT VERIFIED when sign-in clearly works?

Because nothing has ever proved the stored settings - which is the normal state for an installation set up by the setup wizard, since the wizard runs no login test. It turns green the next time an administrator signs in.

Why can I not choose which groups are administrators?

That list is fixed at deployment time and deliberately not editable from the console. This page can change which claim group membership is read from, never who counts as an administrator - so a mistake here can only ever keep administrators out, not let the wrong people in.

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

No. A stored change applies to new sign-ins immediately. Sessions already signed in are unaffected until they end.

Do I have to re-enter the client secret when I change the issuer?

Yes. A stored secret belongs to the provider that issued it, so ezSign refuses a save that moves the issuer while keeping the old secret. Type the new realm's secret, or remove the secret with its trash icon if the new client is public.