Break-glass account recovery for a locked-out administrator

Break-glass recovery is one command, run on the SSOGEN server, that gives a locked-out administrator a new way in. It prints a temporary password and ten new recovery codes for the administrator you name, and ends every authenticator and sign-in that account had. Use it when the only administrator lost the password or the phone, or when an administrator’s phone or account may be in someone else’s hands.

It applies to an SSOGEN you run on your own server, because it needs root on that server. SSOGEN normally refuses any change that would lock everyone out, as Admin lockout protection explains; this command is for the day it happens anyway.

1. Before you start

You need	Why
Root on the SSOGEN server, in an interactive terminal	The command reads the service’s settings and runs as the service account.
The administrator’s user name	The command recovers exactly one account.
A phone with the SSOGEN Authenticator	The run leaves the account with recovery codes only. A lasting second factor comes from pairing a phone afterwards. If there is no phone, read section 4 first.
A safe place for the output	The temporary password and the recovery codes are printed once and stored nowhere else.

The command works whether the SSOGEN service is running or stopped. It does not go through the web: SSOGEN is started once, without a web server, does the recovery and exits.

2. Run the command

sudo bash -c 'cd /; set -a; . /etc/ssogen/ssogen-platform.env; set +a
  exec runuser -u ssogen -- /opt/ssogen/bin/ssogen-platform \
    --spring.main.web-application-type=none \
    --ssogen.recover.username=<administrator username> \
    --ssogen.recover.confirm=true'

Replace <administrator username> with the account to recover. If your installation uses another service account or Java location, use the command that install.sh --apply printed at installation: it carries the right values for your server.

The command never takes a password. It generates the temporary password itself and prints it once. An option that would carry one is refused, because a value on a command line can be read by other users of the server and stays in the shell history.

3. What it prints

A successful run prints the build line, then a summary like this, and exits with status 0. The numbers depend on the account.

SSOGEN Platform 4.3.4 build 20261108 build id <build ID>
Recovered jane.smith (3f0c2c1e-5d2a-4c53-9f0e-2a7d6b1f4e11)
  temporary password : <printed once>
  must be changed    : at next sign-in
  account status     : active
  revoked            : 1 paired phone(s), 0 QR code authenticator(s), 1 passkey(s)
  ended              : 2 sign-in(s), 0 console elevation(s), 1 application refresh token(s), 0 agent delegation(s), 0 sign-in(s) waiting for a second step
  remote access      : 0 revocation(s) written to the feed the Edge polls; this administrator's remote sessions end at its next fetch
  removed            : 0 sign-in email/phone the administrator had added, 0 contact proof(s), 0 unused password-reset link(s), 0 application password(s)
  codes now go to    : email a•••@e•••.com, phone •••• •• 23
                       check that both are the administrator's own; if not, correct them in the console
  recovery codes     : 7KQM-2XWD-9PTH-4BZC <nine more>

Next: sign in with the temporary password and change it. When a second factor is
asked for (at sign-in or in Account), enter one recovery code (each works once);
pair a new phone under Account, then open the Admin Console with that phone's code.
Sessions applications already hold run to their own end: see the install guide, 5.4.

Recorded in the audit trail under correlation <correlation id>.

Keep the correlation id. It finds every record of this run in the audit log (section 8).

Each recovery code is 16 characters in four groups of four. Dashes, spaces and letter case do not matter when you type one, and each code works once.

When the run also changed the Admin Console’s sign-in policy, a console sign-in line says what changed and how to undo it. Section 7 explains it.

4. Options

Add an option to the command on its own line, before the closing quote, in the same form as --ssogen.recover.confirm=true.

Option	Use it when	Effect
--ssogen.recover.username=<name>	Always	The account to recover.
--ssogen.recover.confirm=true	Always	Without it the run refuses and changes nothing.
--ssogen.recover.enable=true	The account is disabled or archived	Also reactivates the account. Without it the status is left as it was, and the printout says the credentials will not let the account sign in.
--ssogen.recover.reset-at-source=true	The administrator’s password is held by a directory or identity provider, and you have already reset it there	Does everything except the password: no SSOGEN password is set. The printout says password : not set here.
--ssogen.recover.detach-from-source=true	That directory or identity provider is broken, gone, unreachable or itself in someone else’s hands	Makes the account an SSOGEN account, ends its identity links and sets a printed temporary password. The printout adds a detached from line.
--ssogen.recover.allow-any-app-codes=true	The administrator has no phone for the SSOGEN Authenticator	Allows this one administrator to set up any authenticator app by QR code under Account. Recorded as totp.enrollment_mode_override_changed. The exception stays until an administrator changes it.

reset-at-source and detach-from-source are two different answers and are refused together.

An administrator who signs in through a directory or identity provider

When the account’s password is held by LDAP, Active Directory, Kerberos, SAML or OpenID Connect, a plain run refuses and changes nothing: whoever knows that password or holds that identity could still sign in, and SSOGEN cannot change it. Do this instead:

1. Reset the password in the directory, or disable the identity at the identity provider, first.
2. Run the command with --ssogen.recover.reset-at-source=true added.
3. The administrator signs in through the directory or identity provider with the new password, and enters a recovery code when a second factor is asked for. Continue at step 3 of section 6.

If the directory or identity provider cannot give the account back, run the command with --ssogen.recover.detach-from-source=true instead. Linking the account to a provider again later is a deliberate change by a Super Admin.

5. What the run changes

Item	After the run
Password	Replaced by the printed temporary password, which must be changed at the next sign-in. Not set with reset-at-source.
Paired phones, authenticator apps set up by QR code, passkeys	Revoked. A lost or stolen phone can no longer approve a sign-in, and its codes are refused.
Recovery codes	Replaced by ten new ones. The old ones stop working.
App passwords stored for this administrator	Removed. The administrator enters them again.
Sign-in email addresses and phone numbers the administrator added in Account, and the proofs of them	Removed, so reset links and sign-in codes no longer go to an address someone else may have added.
Password-reset links not used yet	Spent. A link mailed before the run sets no password.
The organization’s email address and mobile number on the account	Kept, and printed masked. Sign-in codes and reset links go there from now on. Check that both belong to the administrator.
Sign-in sessions, sign-ins waiting at the second step, console elevations, remembered browsers, applications’ refresh tokens, remote sessions, AI agent delegations the administrator granted	Ended.
Account status	Unchanged unless you add --ssogen.recover.enable=true.
Other people, other administrators included	Untouched.

The run is one database transaction. If anything fails, or if a sign-in or authenticator was added to the account while the run was working, nothing is changed, nothing is printed and the command exits with a non-zero status. Run it again.

Messages when the run refuses

Message	What to do
refusing to recover <username> without --ssogen.recover.confirm=true	Add the option.
no account named <username>	Check the user name.
--ssogen.recover.password is not accepted: the command chooses the new password itself and prints it once	Remove the option.
<username>'s password is held by <source> (a directory or identity provider), not by SSOGEN, …	Follow “An administrator who signs in through a directory or identity provider” above.
<username>'s password is already held by SSOGEN; there is no directory or identity provider to detach it from. …	Run the command without detach-from-source.
--ssogen.recover.reset-at-source and --ssogen.recover.detach-from-source are two different answers; give one. Nothing was changed.	Give one of the two.
an authenticator or sign-in was still active after recovery; nothing was changed, run the command again	Run it again.

A refused or failed run changes nothing and writes no audit event. The message on the terminal and the exit status are its only record.

6. Get back into the Admin Console

1. Open https://sso.example.com/admin/ (your SSOGEN address). Enter the user name and the temporary password. When a second factor is asked for, enter one of the printed recovery codes.
2. Choose a new password when asked. The page then says to sign in with it: enter the new password, and a recovery code you have not used yet if a second factor is asked for. The console opens.
3. Give the account a lasting second factor. Open Account, and under SSOGEN Authenticator select Pair a phone. The page first asks you to prove a second factor: choose a recovery code and enter an unused one. After that proof you land on the Account overview: open the Authenticator section again, then follow the pairing on the phone and type the confirmation code from the phone into the page.
4. From your next sign-in, approve on the phone or enter its code as the console’s second factor.
5. Later, Generate Recovery Codes in the same section gives you a new set. Store the codes somewhere other than the phone.

Without a phone, and with --ssogen.recover.allow-any-app-codes=true given, the Authenticator section offers a QR code for any authenticator app after step 2: prove a recovery code, scan the QR code, and enter the code the app shows. Without that option, an administrator with no phone opens the console only with recovery codes, each once.

Pairing a phone is described in SSOGEN Authenticator app.

7. Return to normal

7.1 The console’s sign-in policy

The recovered administrator signs in with an SSOGEN password. If the Admin Console’s sign-in policy did not admit the SSOGEN directory (for example because every administrator signed in through an identity provider), the run changes that in the same transaction, so the recovered sign-in reaches the console. The second factor is never weakened.

The console used	What the run does	Recorded as
A policy of its own	Adds the SSOGEN directory to that policy	authentication_policy.updated
A policy shared with applications, or the default policy	Leaves that policy exactly as it is, and gives the console a new policy named Administrator sign-in (after break-glass recovery) with the same second factors	authentication_policy.created, authentication_policy.assigned, admin.console_policy_created

Until a Super Admin decides, Setup health shows the warning Administrator sign-in after break-glass recovery, with the text “The console admits the SSOGEN directory since break-glass” and the correlation id of the run. End it in one of three ways under SSO policies:

• remove the SSOGEN directory from the console’s policy, or
• give the console its previous policy back, or
• to keep the SSOGEN directory, open the console’s policy and save it.

Take either of the first two only when another administrator can still sign in to the console. Each choice is recorded in the audit log and ends the warning. See System health for where the warning appears.

7.2 Sessions that applications still hold

The run ends everything SSOGEN holds. It cannot end what an application was already given:

Where	How long it can last	To end it now
Access tokens already issued to applications	60 seconds (at most 270 seconds for an AI agent’s token)	Wait.
Applications behind the Web Agent	The Web Agent’s own session, until SSOGENSessionMaxDuration (12 hours by default) or its idle timeout (30 minutes by default)	Stop and start Apache on each Web Agent server (systemctl restart httpd). A graceful restart is not enough. This signs everyone out of that server.
Applications published through a Gateway	The Gateway’s own session, until its absolute timeout (12 hours by default) or idle timeout (30 minutes by default)	Restart each Gateway of the group, or use Gateways, Withdraw grants on the group. Either ends everyone’s sessions on that group.
SAML and OpenID Connect applications	The application’s own session timeout	End the person’s sessions in the application’s own administration.

Do this when the account may have been in someone else’s hands. For a lost password with no sign of misuse, the sessions simply run out.

7.3 Review what the account did

The run takes back the administrator’s own way in. It does not undo what somebody did with the account before. If the account may have been misused, review the audit log from the time it may have been taken until the run: administrators and roles created or changed, API and AI agent clients, provisioning tokens, identity provider connections, application settings, and the organization’s email address or phone number on any account. Undo what you did not do.

Then make sure this cannot repeat: keep at least two Super Admins, each with their own second factor, as Admin lockout protection recommends.

8. What the audit log records

A successful run writes one event, break_glass.recovered, and one event for each thing it revoked, all under the correlation id the run printed. The actor is break-glass: followed by the operating-system user who ran the command. No password and no recovery code is written to the audit log or to the server log.

To see them, open the audit log and filter on Correlation id.

Event	Meaning
break_glass.recovered	The recovery itself, with the counts below
local_password.admin_set_force_change	The temporary password was set
authenticator.device_revoked	A paired phone was revoked
totp.revoked	An authenticator app set up by QR code was revoked
webauthn.revoked	A passkey was revoked
recovery_codes.rotated	The recovery codes were replaced
mfa.reset_by_admin	The account’s second factors were cleared
nhi.delegation_revoked	An AI agent delegation the administrator had granted was ended
totp.enrollment_mode_override_changed	Only with allow-any-app-codes
authentication_policy.updated, or authentication_policy.created, authentication_policy.assigned and admin.console_policy_created	Only when the console’s sign-in policy was changed (section 7.1)

break_glass.recovered carries these details:

Detail	Meaning
phones_revoked, code_credentials_revoked, passkeys_revoked	Authenticators revoked, by kind
sessions_ended, elevations_ended, sign_in_challenges_failed	Sign-ins, console elevations and second-step sign-ins ended
refresh_families_revoked, delegations_revoked, remote_session_revocations	Application refresh tokens, AI agent delegations and remote sessions ended
recovery_codes_issued	New recovery codes issued
contacts_cleared, contact_verifications_cleared, reset_links_spent, app_passwords_removed	What was removed from the account
account_reactivated	Whether enable reactivated the account
any_app_codes_allowed	Whether allow-any-app-codes was given
password_reset_at_source	Whether the run was made with reset-at-source
detached_from_source, identity_links_ended	Set by a run with detach-from-source
console_ssogen_directory_readmitted, console_readmission	Whether the console’s policy was changed, and how: policy_edited or policy_replaced

9. Recovery codes issued by earlier versions

Recovery codes issued before the 16-character format are 10 characters long. They keep working, once each, until they are used or replaced, and not after 2027-01-15T00:00:00Z. To choose another date, set SSOGEN_RECOVERY_CODES_LEGACY_ACCEPTED_UNTIL in /etc/ssogen/ssogen-platform.env to a UTC instant such as 2026-12-01T00:00:00Z and restart SSOGEN. A value that is not an instant stops SSOGEN from starting.

After that date, a person whose only second factor is an old recovery code cannot pass the second-factor step. Have people generate a new set, or pair a phone or passkey, before the date. An administrator in that position is recovered with the command on this page.

Related pages

• Admin lockout protection
• Admin console sign-in
• Audit log
• Audit event reference
• System health
• SSOGEN Authenticator app