Gateway configuration and identity resilience

An SSOGEN Gateway has no local list of routes. SSOGEN publishes a signed configuration for each Gateway group and every instance of the group fetches it, checks it and applies it. This page explains what an instance does when that cannot happen, so you know what your users see during an outage and which actions still cut access.

The examples use the fictional company Acme Corp, with SSOGEN at https://sso.acme.example and the Gateway group eg_acme_hq.

1. The short answer

A Gateway keeps its last good configuration. If it cannot fetch a new revision, or cannot apply one, it stays on the one it runs. It does not shut down for that reason.
Keeping the configuration does not keep access open. A Gateway must hear from SSOGEN regularly to go on accepting sign-ins and sessions. Without contact, new sign-ins stop after 30 seconds and existing sessions after 5 minutes.
Switching off works from SSOGEN. Revoking an instance, withdrawing grants and rotating session keys take effect on a running Gateway within seconds while it is connected, and within 5 minutes when it is not.
Everything resumes by itself when the connection returns, unless the outage outlasted the instance’s identity certificate (24 hours at most).

2. How configuration reaches a Gateway

You change something in the Admin Console (a route, a listener, a certificate, a resource). SSOGEN publishes a new revision for the Gateway group.
Each instance asks SSOGEN for the newest revision every 30 seconds (the service option --config-poll-interval, 30 seconds to 1 hour).
The instance verifies the revision’s signature, prepares it, and applies it.
If a part of the Gateway refuses the revision, the instance returns to the previous revision by itself and reports the refusal.
The instance stores the revision it runs. After a restart it verifies the stored revision, serves it, and then fetches again.

On Secure access, Gateways, the Config column of each instance shows the result: “Running revision N”, “revision N published but not active” while an instance has not picked up the newest one, or “revision N was refused: reason”. The reasons are explained in Troubleshooting the gateway.

One item that cannot run does not stop the rest. A route, resource or directory connection whose secret file is missing on the server is left out alone and shown as Not in effect; the rest of the revision is served. Once the file is right, the instance serves the item within a minute, without a restart.

On the server, the service log says what happened to a revision:

sudo journalctl -u ssogen-edge --no-pager

Look for lines that begin configuration was refused:, configuration revision N is still refused or configuration poll skipped.

3. When a Gateway cannot reach SSOGEN

The instance goes on serving the configuration it runs. What changes with time:

Time without contact	Web applications behind the App Proxy	Remote Access (SSH, RDP, VNC)
Up to 30 seconds	No change.	No change.
After 30 seconds	No new sign-in through the Gateway. People who are signed in continue.	No change.
After 2 minutes	As above.	New remote sessions are refused. Open ones continue.
After 5 minutes	Requests on existing sessions are refused too. The browser gets the Gateway’s error page with the code `SSO-EDGE-503-UNAVAILABLE`.	Open remote sessions are ended. The browser shows `revoked`.
After 7 days	The instance reports not ready, which takes it out of a load balancer.	As above.

What is not affected at any point: a route you published as public (it needs no sign-in) keeps being served.

Other effects of an outage:

No configuration changes arrive. What you publish in the Admin Console waits until the instance can fetch it.
The Gateways screen shows the instance offline. An instance reports about once a minute; see Last seen.
The instance’s identity certificate is not renewed. It lasts 24 hours and the instance renews it after 16 hours. An outage that ends before the certificate expires does no harm: the instance renews as soon as SSOGEN answers. See section 6 for what to do when it has expired.

A restart during an outage. The instance comes back with its stored configuration and serves it, but it accepts no new sign-in and no new remote session until SSOGEN answers. After 7 days without contact, a restarted instance stays not ready.

When the connection returns there is nothing to do. The instance notices within about 30 seconds, accepts sign-ins again, fetches the newest revision and reports to the Gateways screen.

4. How switching off still takes effect

You never have to log in to a Gateway server to cut access. These actions work from the Admin Console, also on an instance that runs an older configuration.

Action	Where	Effect on a running Gateway
Revoke instance	Secure access, Gateways, the instance’s row	SSOGEN refuses the instance’s certificate from that moment: it receives no keys, no configuration and no renewal. Within about 10 seconds the instance stops accepting sign-ins and sessions and reports not ready. It can join again only with a new enrollment token. This cannot be undone.
Withdraw grants	Secure access, Gateways, on the group	The group’s Gateways stop accepting the access grants they hold. Nobody is signed out of SSOGEN: each person’s next request gets a new decision under the current policy.
Rotate session keys now	The group’s Listeners	Everyone signs in again on their next request through the group.
Revoke an Outbound Connector instance	Secure access, Gateways, the instance’s row	Its tunnels, and the sessions in flight on them, end when each Gateway takes its next configuration (30 seconds by default). The other connectors of the group keep serving.

Details that matter:

A revoked instance that cannot reach SSOGEN does not hear about the revocation. It still loses access through the rule of section 3: it honors sessions for at most 300 seconds. To end that at once, stop the service on the server.
Revoking does not sign people out by itself. People already signed in through the group keep their session (up to 12 hours) on the group’s other instances until you use Rotate session keys now.
A public route is still served by a revoked instance that keeps running, because a public route needs nothing from SSOGEN. Stop the service, or take the server out of DNS and the load balancer, to end that.
On the SSOGEN hosted service, if the Gateway feature is turned off for your organization, your enrolled Gateways are refused at their next call. They keep their identity and work again when the feature is turned back on.

To stop a Gateway server completely:

sudo systemctl disable --now ssogen-edge

5. Credentials and how they rotate

Credential	Lifetime and rotation	What you do
The instance’s identity certificate	24 hours. The instance renews it by itself after 16 hours. The key never leaves the server.	Nothing. The Certificate expires column on the Gateways screen shows the current end date.
SSOGEN’s certificate authority for your Gateways	When SSOGEN replaces it, running Gateways learn the new one from SSOGEN in signed form and renew under it.	Nothing for a running Gateway. A Gateway that was stopped during the whole changeover is refused afterwards: download the trust bundle again from the Gateways page, replace the file that `edge.pki.trustBundle` names in `edge.yaml`, and restart the service.
Session keys of a Gateway group	Replaced when you select Rotate session keys now.	Use it when you want everyone to sign in again.
Enrollment tokens	One use each. A token is never reused.	Issue a new one for each enrollment. Cancel an open token with Revoke on its row.
Secret files on the server (bind passwords, keytabs, stored passwords)	You own them. Each is a file under `/etc/ssogen-edge/secrets`, owned by `ssogen-edge`, mode 0600, on every instance of the group.	Replace the file on every instance. The Admin Console shows the exact path and command beside each field that names a secret.
Listener certificates (the certificates your users see)	You upload and replace them in the Admin Console.	See Publish an internal app with the App Proxy.

6. Enroll a Gateway again

Enrollment is done once. You need it again only in these cases:

Case	How you recognize it
The instance was revoked.	The Gateways screen shows Revoked.
The identity certificate expired during a long outage.	Certificate expires is in the past and the instance stays offline although the server reaches SSOGEN.
The server was rebuilt or replaced, or its disk was copied to another machine.	The service refuses to start on an identity that was enrolled elsewhere.

A new enrollment always needs a new one-time token, and the enroll command does not overwrite a working identity. The clean way is to give the server a fresh start:

In the Admin Console, open Secure access, Gateways. If the old instance is not shown as Revoked, select Revoke on its row. After an instance is revoked, its name (instanceId) can be enrolled again.
Issue a new enrollment token for the Gateway group and copy the enrollment string and the edge.yaml the page shows. See Install and enroll an SSOGEN Gateway, section 2.
On the server, stop the service:
```
sudo systemctl stop ssogen-edge
```
Note the secret files you keep in /etc/ssogen-edge/secrets; you create them again afterwards. Then delete the old identity, state and configuration: the directories /etc/ssogen-edge, /var/lib/ssogen-edge, /var/spool/ssogen-edge and /var/log/ssogen-edge.
From the unpacked archive, run the installer again so the directories are created with the right owners and modes:
```
sudo ./install-edge.sh --apply --mode gateway
```
Use the roles the server had (gateway, directoryConnector, outboundConnector).
Write edge.yaml, enroll with the new enrollment string, create the secret files again and start the service, exactly as in Install and enroll an SSOGEN Gateway, sections 4 to 7.
Confirm that the instance shows online with “Running revision N”.

The other instances of the group serve during all of this. The old certificate stays refused everywhere until it expires.