SSOGEN concepts explained: an IAM glossary in plain words

Every idea you meet in SSOGEN, in a few sentences each: what it is, why it exists, what you actually have to do about it, and where it lives in the console. For most of them the answer to “what do I do” is nothing, SSOGEN does it. The ideas are grouped in the order you meet them.

SSOGEN’s goal is single sign-on that looks like magic to the person running it and keeps full security. It absorbs the complexity (defaults, generated values, generated configuration). You should not have to learn new technology to run it, and the people who run your applications never need an SSOGEN credential of their own: you register the application, and they paste a configuration block you give them.

How to read the tables. “You do” says what is left for you. “Console” gives the exact menu path in the Admin Console as Menu group > Item. The Admin Console is at /admin/ on your SSOGEN address; its menu groups are Home, Identity, AI agents, SSO policies, Applications, Provisioning, Secure access, Monitoring and Settings. The first screen after sign-in for everyone else is My Apps, at the address itself.

Contents

The pieces
Who people are
How people sign in
How applications are connected
How trust works
The Gateway and remote access
AI agents
Running it
Which concept do I need to touch?
Glossary

1. The pieces

SSOGEN is one product with a few parts. The first one decides; the others carry the decision to where it is needed.

Piece	What it is	Why it exists	You do	Console
SSOGEN	The server that holds your people and decides who may open what. It runs the sign-in pages, the Admin Console, My Apps, and the connections to your directories. Think of the front desk of a building: it checks IDs and hands out passes.	One place makes every access decision, so no application keeps its own list.	Install it once and finish first-run setup.	Everything in this guide
Admin Console	The web console where administrators set everything up. Being signed in is not enough for administrator powers: the console may ask for an authenticator code to enter admin mode, which ends after 15 idle minutes or 60 minutes in all by default.	Administrator powers are risky, so they time out on their own.	Give each administrator a role. Six are built in: Super admin, Authentication admin, Application admin, Directory admin, Security audit reader, Read-only admin.	Settings > Admin roles
My Apps home	The page every person lands on at your SSOGEN address. A left menu has My Apps (Recently used, Favorites, the categories you define, and AI tools and Approvals when they apply to that person) and My Account (AI agents, Profile, Password, App passwords, Passkeys, Authenticator, Linked identities, Sessions, Devices, Activity). There is no separate account page.	One home for launching applications and managing your own sign-in.	Nothing, except telling people the address. Set your logo and wording if you like.	Settings > Branding
SSOGEN Gateway	A program you install inside your own network that carries SSOGEN’s decisions to places SSOGEN cannot reach on its own. It is one program with four features: App Proxy, Remote Access, Outbound Connector and Directory Connector (section 6). Think of a branch office of the front desk.	Your internal applications, servers and directories should not be opened to the internet.	Only if you need one of the three features: install it and enroll it once (section 5). On the SSOGEN-hosted service, SSOGEN switches the Gateway on for your organization first.	Secure access > Gateways
SSOGEN Web Agent	An Apache module (Apache 2.4; Apache 2.2 and Oracle HTTP Server from the same source) that stands in front of one application, makes sure the person signed in, and lets the application know who it is. A door guard for one application. It keeps a sealed copy of SSOGEN’s public signing keys from its last start that reached SSOGEN (in its state directory), so a full Apache restart still starts every site while SSOGEN is down (for up to 7 days).	Older applications cannot speak SAML or OpenID Connect and should not have to change.	Register the application in the console, copy the generated Apache configuration, and give it to the team that runs the web server. They paste it and restart Apache. They enroll nothing and hold no SSOGEN credential of their own.	Applications > Web Agents, then the application’s Integration tab
Java agent (SSO4J)	The same job for Java applications on Tomcat 9, 10.1 or 11, or Spring Boot. Same policy and logout as the Apache agent.	Java applications have no Apache in front of them.	Press Generate agent key on the application’s Integration tab, save the Java agent settings file it shows (the key is filled in that one time) on each application server, and add the valve or the Spring Boot setting the tab names. Like the Apache agent, it uses the application’s agent key and enrolls nothing.	Applications > Java Agents, and the application’s Integration tab
SSOGEN Authenticator	The phone app (iOS and Android). It shows one-time codes and, when push notifications are on, lets a person approve a sign-in by tapping, among six numbers on the phone, the one the sign-in page shows (number matching).	A second step that is hard to phish and easy to use.	Usually nothing. Choose whether people may use any authenticator app or only this one, and optionally set the download links shown to people.	Settings > Authenticator; for a person, My Account > Authenticator
Directory Connector	A Gateway feature that lets SSOGEN reach your on-premises Active Directory or LDAP directory without opening it to the cloud. It always uses LDAPS (LDAP over TLS). Today SSOGEN uses it to test a connection; sign-in does not go through it yet.	Directories live inside networks SSOGEN cannot reach.	Register the directory connection once and enter its service account.	Secure access > Directory Connector; the directory itself under Identity > Directories
Hosted or on your own servers	SSOGEN can run hosted by SSOGEN, or on your own servers from the release archive. Both come from the same release and look the same to your people and administrators.	You choose where the server runs; nothing else changes.	Pick the one that fits.	Same console either way
Realm (organization)	One organization’s own space inside SSOGEN: its people, groups, providers, applications, policies, settings and audit log. The console and the pages your people see call it your organization.	Keeps one organization’s data separate from every other.	Nothing.	Everywhere
Canonical origin	The one web address people use to reach your SSOGEN, for example `https://sso.acme.example`. It is fixed when the organization is created and cannot be changed afterward. SSOGEN refuses setup requests that arrive through any other address, and agents must be pointed at exactly this address.	Sign-in links, tokens and cookies are tied to one address, so nobody can impersonate another.	Choose it carefully at install.	The addresses on Monitoring > Endpoints are built from it

2. Who people are

Concept	What it is	Why it exists	You do	Console
User	A person SSOGEN knows: a username, sign-in methods, group memberships and application access.	Everything else (assignments, policies, audit) refers to a person.	Usually nothing: people arrive from a directory, a provider, an HR system or an import. Create one by hand for a first administrator or a contractor.	Identity > Users
Group	A named set of people. You give an application to a group instead of to each person; groups can be nested.	Access follows membership, so joiners and leavers need no application edits.	Create the few groups you need.	Identity > Groups
Everyone	The one system group. SSOGEN creates and maintains it and it follows a rule (every active person), so it cannot be renamed, deleted or edited by hand.	An application assigned to Everyone reaches the whole company, and no one can empty it by mistake.	Nothing.	Identity > Groups
SSOGEN Directory	The built-in store of accounts whose passwords SSOGEN keeps (listed as “SSOGEN Directory” in Users, and as “Username and password” among identity providers).	Your first administrator, contractors, and a way back in if another provider is down.	Nothing beyond creating accounts.	Identity > Users; SSO policies > Identity providers
Directory (LDAP or Active Directory)	Your existing company directory, connected so people sign in with the password they already have. SSOGEN checks the password against the directory each time and brings in users and groups.	Keep passwords where they are.	Add the directory once; for an internal CA, trust it (section 5).	Identity > Directories
Identity provider	Anything that can check who someone is: Microsoft Entra ID, Okta, Keycloak, Google, any SAML or OpenID Connect service. SSOGEN sends the person there and trusts what it reports. A new one starts as a draft, and does not appear on the sign-in page until you test and activate it.	People keep one password, and the provider applies its own checks.	Add, test, activate.	SSO policies > Identity providers
Linked identity	A sign-in on another provider tied to one SSOGEN user, so the same person signing in two ways is one account.	One person, one account.	Nothing. People can see theirs.	My Account > Linked identities
SCIM provisioning	A standard way for systems to exchange accounts automatically. Inbound: your HR system or provider creates, updates and switches off people in SSOGEN. Outbound: SSOGEN creates and switches off accounts inside an application as people gain or lose access.	Joiners and leavers happen on their own.	Create an access token for the other system (inbound) or connect the application (outbound).	Provisioning > Inbound, Provisioning > Outbound
Import	Bringing people in without waiting for their first sign-in. From a directory, an import reads the whole directory, adds the missing, refreshes details and can switch off people who left. A file import loads a CSV file of users.	People are ready before day one, and leavers lose access.	Press Import users when you want it.	Identity > Directories and Identity > Users

An analogy that holds for this whole group: a policy is the sign on a door that says how strongly you must prove who you are to go through it.

Concept	What it is	Why it exists	You do	Console
Authentication policy	A named rule that applications share: which identity providers may be used, how much strength is required, which second steps are accepted, and what happens when a session does not have enough. Editing a policy reaches every application that uses it. Its optional conditions can only tighten it.	Say it once, apply it to many applications.	Make a few policies (for example one for employees and one for finance).	SSO policies > Policies
Default policy	The policy for any application that has none of its own, and for signing in at My Apps. With none set, an application with no policy of its own cannot be opened.	A safe starting point.	Set one early.	SSO policies > Defaults
Console policy	The policy that guards the Admin Console, set separately and never inherited from the default. It cannot have conditions, and email and text codes are never accepted on it.	Who may administer must not change when an employee policy is edited.	Keep a second administrator signed in when you change it.	SSO policies > Defaults (Administration console)
Access rules	One organization-wide list, read in order: the first rule that matches decides, and anything no rule allows is denied. Rules can match a group, a person, a network, the sign-in strength, the time of day, a risk score and more. A new version can run in monitoring mode, alongside the current one, before you enforce it.	Cross-cutting rules (for example “outside the office needs a second step”) without editing every policy.	Usually leave the defaults.	SSO policies > Defaults (Access rules); try one with SSO policies > What if
Network zone	A named group of network addresses, such as “corporate”. Policies can allow or relax by zone. An address in no zone is “unknown”.	“From the office” is a useful fact.	Zones are set by whoever installs SSOGEN; the console shows them read-only.	SSO policies > Network zones
Sign-in strength	How sure SSOGEN must be who you are. Three levels: Password or single sign-on (one proof), Plus a second factor, and Passkey or security key (only a passkey or security key counts, which cannot be phished). A policy states the level it requires.	Different applications deserve different strength.	Pick the level per policy.	Policy wizard, Requirements step
Step-up	Being asked for more proof in the middle of a session because an application needs a stronger level than you have shown. A policy decides whether the extra proof is an SSOGEN second factor, the identity provider’s, or either.	Strong proof only where it matters.	Choose the step-up mode per policy.	Policy wizard, Requirements step
Password policy	For accounts whose password SSOGEN keeps: a preset (Recommended, Stricter or Relaxed) sets the minimum length (never below 8), mixed characters, passwords remembered, expiry and lockout; at most 256 characters, stored in a form nobody can read back. Directory and provider accounts follow their own system’s rules.	A sensible default with presets rather than settings to get wrong.	Nothing: Recommended is the default. (A reset link works for a limited time, set in Security settings.)	Identity > Password policy; the password forms
Remembered browser	An opt-in per policy that skips the second step on a browser the person chose to remember. It never applies to the Admin Console.	Less friction on a personal laptop.	Decide per policy; off by default.	Policy wizard, Remembered browsers; a person’s My Account > Devices

Second factors, and the other ways in

Way	What the person does	Notes
Authenticator code	Types the six-digit code that the SSOGEN Authenticator (or another authenticator app, if allowed) shows.	The default code method.
Phone approval (push)	Approves on the paired phone: the sign-in page shows one number, the phone shows six, and the person taps the matching one and confirms with a fingerprint, face or screen lock.	With push notifications on, the phone is notified; otherwise the person opens the app to approve. SSOGEN provides push delivery for the SSOGEN Authenticator; you do nothing unless you publish your own rebranded app.
Passkey	Approves with the device they already unlock (fingerprint, face, PIN or a security key).	Cannot be phished. A policy turns passkeys on.
Recovery codes	Types one of a set of single-use codes kept somewhere safe.	For a lost phone. Can be switched off.
Email and text codes	Types a short code sent by email or text message.	Weaker, because they can be intercepted; off unless a policy lists them. Need SMTP or an SMS provider (section 8).
Sign in with your phone	Types only a username and approves on the paired phone. No password.	A policy option, off by default and never offered for the Admin Console. Anyone who knows a username can send a request to that phone, so the person approves only by tapping the number shown.
Email me a sign-in link	Asks for a link and a code sent to a verified email address. The link works only in the browser that asked, and only after the person presses Continue.	A policy option, off by default, allowed only on a “Password or single sign-on” policy and never for the Admin Console. It counts as single-factor, and whoever controls the mailbox can sign in, which the policy editor says.

You choose the accepted second steps, and their order, in the policy wizard’s Requirements step (“Second step”). People who have an authenticator or a paired phone are asked for it even where a policy asks for no second step.

Sessions, devices, risk and limits

Concept	What it is	Why it exists	You do	Console
Session	The time you stay signed in. By default it ends after 30 minutes idle or 12 hours in all.	A walk-away or stolen laptop does not stay signed in forever.	Change the two timeouts only if a standard requires it.	Settings > Security (Sessions); watch live ones in Monitoring > Sessions
Devices	The browsers SSOGEN knows you signed in from, and whether each is remembered. Paired phones are listed under Authenticator.	Lets a person forget a browser.	Nothing.	My Account > Devices, My Account > Authenticator
Risk score	Each sign-in gets a score from fixed, explainable facts: a new browser, a network the person has not used lately, an address in no network zone, and recent failed attempts. It is deterministic (no model decides), and a rule can use it to ask for more proof, shorten a session or deny.	Catch unusual sign-ins without guessing.	Optionally write a rule on it.	SSO policies > Defaults (Access rules)
Rate limits and lockout	Limits on repeated attempts: password sign-ins, second-factor codes, passkeys, password resets and admin mode, per client. Ten wrong codes in a row lock the account’s second factor for 15 minutes by default.	Slows guessing without a human watching.	Leave the defaults; tighten if you must.	Settings > Security (Sign-in protection)

4. How applications are connected

Concept	What it is	Why it exists	You do	Console
Application	Anything your people sign in to: a SaaS product, a web application you run, or an API that a program calls. The console lists applications by how they are connected.	The unit you assign, protect and launch.	Register each one with the wizard (General, Access mode, Connection, Sign-in policy, Identity sent to app, Launch, Try it (optional), Review and activate). It is saved unavailable and becomes available only when you activate it.	Applications > All applications
Assignment and visibility	Who may open an application: people or groups. An assignment lets the person open the application and puts its tile in their My Apps (once the application is active). Two switches refine it: Assignment required (on by default; when off, every active person can open the application and the sign-in policy still applies) and Show in My Apps (turn it off to hide the tile; assigned people can still sign in).	Access is decided in one place.	Assign groups, not people.	The application’s Assignments tab; Show in My Apps on its general settings
Access mode	How the application is connected. Pick the first that fits: SAML, OpenID Connect (nothing to install), Web Agent (an Apache module in front of the app), or App Proxy (the Gateway publishes the app). Remote access (SSH, RDP, VNC) is a separate kind of resource (section 6).	Each application speaks a different language.	Choose per application.	Applications > Web Agents / SAML / OpenID Connect / App Proxy; the application’s Access mode tab
SAML	An older, widely supported standard. SSOGEN acts as the application’s identity provider: the application sends the person to SSOGEN, and SSOGEN returns a signed statement (an assertion) saying who signed in. You give SSOGEN the application’s entity ID and assertion address (or its metadata file), and give the application SSOGEN’s metadata address.	Most SaaS products speak it.	Paste values both ways; the Integration tab lists what the application needs.	Applications > SAML, Integration tab
OpenID Connect (OIDC)	A newer, simpler standard. SSOGEN acts as the application’s OpenID provider: the application redirects the person to SSOGEN and receives a signed ID token. Only the authorization code flow, always with PKCE; a client secret or a private key is optional for server applications. Programs with no person present use a service application.	Modern web, single-page and mobile applications speak it.	Register redirect addresses; copy the client ID.	Applications > OpenID Connect, Integration tab
Identity sent to the application	The name and extra attributes the application receives: a name ID in SAML, claims in OIDC, or the signed-in user for a Web Agent or Java agent. Several choices of “which attribute is the user name” are offered.	Applications disagree on what to call a person.	Usually keep the default (the SSOGEN username).	The application’s Identity sent to app tab
Launch	What happens when a person clicks the tile: SSOGEN opens the application’s launch address, and the person arrives signed in.	The tile is the way in.	Set the launch address and icon (the App gallery has ready-made icons and definitions).	The application’s Sign-in / launch tab; Applications > App gallery
Form fill	For an application that has only a username-and-password page, the Gateway types the person’s own application password into the form for them. Each person has their own credential; the password never reaches the browser. The offer to save (capture) option lets a person’s first sign-in on the application’s own page save the password.	Last resort for applications that offer nothing better, and with no browser extension.	Only if nothing better fits, set the form and success rule on the App Proxy route.	Secure access > App Proxy routes, the application’s Sign-in to the app tab; people manage theirs in My Account > App passwords
App passwords	The application passwords a person has stored for form fill, entered by hand or saved at sign-in. Never shown again.	Enterprise applications reject shared accounts.	Nothing.	My Account > App passwords
App Pack	A signed, ready-made definition for a well-known application. Only a pack whose signature checks out is installed.	Skip typing the settings.	Pick it from the gallery when it exists.	Applications > App gallery

5. How trust works

This is the part that confuses people, so each idea gets an analogy. Almost all of it is generated for you. The “You do” lines are the exceptions.

5.1 Who proves what to whom

Concept	Analogy	What it is	You do
TLS server certificate	The building’s name board and the lock on its entrance.	Proves to whoever connects that this really is your SSOGEN (the padlock). The installer makes one for SSOGEN’s HTTPS listener (self-signed by default, or yours), or your reverse proxy or load balancer holds it. Every caller must trust the authority that signed it.	Use a certificate your people’s browsers trust, or add your own authority where callers need it (5.4).
Client credentials	The visitor’s badge.	What a caller shows to prove who it is: an agent key (Web Agent and Java agent), a workload certificate (Gateway), a client secret or private key (OIDC application), a one-use enrollment token. A TLS certificate proves the server to the caller; client credentials prove the caller to the server.	Mostly nothing; they arrive inside generated configuration.
Signing key and JWKS	A notary’s seal and a public sample of it.	SSOGEN signs tokens and SAML assertions with its signing key (one key per organization). The public half is published as a JWKS (a list of public keys) so applications can check signatures. Applications and agents fetch it themselves; for SAML you import SSOGEN’s metadata or certificate.	Nothing, except keeping an eye on its expiry.
Agent key (`SSOGENAgentKey`)	A keycard for exactly one room.	How a Web Agent proves which application it serves. One key per application, the same on every web server of that application. It is shown once, SSOGEN stores only a hash of it, and it cannot fetch another application’s configuration. To rotate it, regenerate it.	See 5.2.
Client ID versus key	The door’s name versus its keycard.	The client ID names the application and is not secret. The agent key proves the caller may speak for it. Both are in the generated configuration.	Nothing.
Session secret (`SSOGENSessionSecret`)	The stamp a guard uses to recognize wristbands he issued.	Signs the Web Agent’s own session cookie. If unset, the agent makes a random one at start. It never goes to SSOGEN.	Set the same value on every web server only when several servers share an application without sticky sessions.
Workload CA and workload certificate	A badge office for machines, and the badges it prints.	A certificate authority your SSOGEN runs, and the certificates it issues to machines instead of passwords. The Gateway (including the Directory Connector) uses them. A Web Agent may use one instead of the agent key; Web Agents using the key need nothing. The Java agent uses the agent key too, and may also use a certificate.	On an install you run yourself, `install.sh` creates the authority when it installs SSOGEN, and adds it on an upgrade of an installation without one (install guide, section 9.1). When SSOGEN hosts the server for you, SSOGEN does it. Setup health tells you if it is missing.
Enrollment token	A one-time invitation.	Lets one Gateway become itself: it generates its own key, and the token is spent. Gateways only (an agent that chooses the optional workload certificate has its own token). Put it in a file only the service user can read, use it, delete it.	Create it under Secure access > Gateways > Enrollment tokens.
Secret reference (`secret://`)	A claim ticket instead of the coat.	A short address for a secret, so the value never travels with the setting. See 5.3.	Rarely; forms create them.
Trusted proxy and client address	Caller ID on a call forwarded through a switchboard.	See 5.5.	Tell SSOGEN about your proxy.
Private CA bundle	A list of extra authorities to trust.	See 5.4.	Add your internal authority where it is needed.

5.2 The agent key, step by step

Open the application, Integration tab, and press Generate agent key. The Apache configuration shown now contains the SSOGENAgentKey line.
Press Copy Apache config, then I have copied it. The key is not shown again.
Send the block to the team that runs the web servers. They paste it into the application’s virtual host on every web server and restart Apache. They can keep the key out of the file by putting it on one line in a file only root can read and using SSOGENAgentKeyFile.
To replace it, press Regenerate agent key and choose how long the old key keeps working: 24 hours (the default), 1 hour, 7 days, or Stop it at once.

The key travels over HTTPS and works through a proxy that ends TLS. If SSOGEN refuses an agent, the SSOGEN’s log and Monitoring > Audit (event agent.credential_refused) say why, with a reason such as agent_key_not_recognised or agent_key_retired.

5.3 Secret references

Settings > Secrets stores passwords and tokens SSOGEN needs (a directory bind password, a mail password, a provisioning token). They are encrypted, take effect at once, and are never shown again. Each gets a reference like secret://stored/…. Most of the time a form for a directory, provider or mail server stores its own secret and you never visit this page.
secret://env/NAME points at an environment variable on the SSOGEN server. It is off unless the operator lists the permitted names.
On the Gateway, secret://NAME is a file on the Gateway host, /etc/ssogen-edge/secrets/NAME, owned by the Gateway’s service user, mode 0600. The console shows the exact path and a ready command beside each field that needs one. Keys, keytabs and passwords are always files; a CA certificate is public, so you paste it in the console and SSOGEN sends it to the Gateway group (it appears as secret://platform-trust/<sha256>; no file is needed).
All stored secrets are encrypted with one key kept outside the database. Back it up apart from your database backups.

5.4 Private CA bundles (trusting your own authority)

Where	When	How
SSOGEN trusting your directory	LDAPS directory signed by your own authority	Settings > Certificates, Trusted certificate authorities: add the authority that issued the directory’s certificate (not the directory’s own certificate).
Web Agent trusting SSOGEN	SSOGEN’s certificate is from an internal authority	The `SSOGENCACertificateFile` directive adds authorities to the system store.
Gateway trusting SSOGEN	Always	The Gateway trusts only the file it is given: it must hold the authority that signed SSOGEN’s HTTPS certificate (even if publicly trusted) and the workload CA.
Gateway trusting an internal back end	Back end or remote desktop with a certificate from your authority	Paste the authority’s certificate in the console.

5.5 Trusted proxy and client address

SSOGEN records where each sign-in came from (the audit trail, rate limits, network zones and push messages all use it). When a load balancer or reverse proxy sits in front, every request arrives from the proxy, so SSOGEN would see only the proxy’s address. The proxy therefore adds the real address in a header (by default X-Forwarded-For). SSOGEN believes that header only when the connection comes from a proxy you listed, and counts entries from the right, one per proxy. A client cannot invent its address by writing the header itself.

Setting	Meaning	Default
`SSOGEN_TRUSTED_PROXY_CIDRS` (installer `--trusted-proxy`)	The addresses or subnets of the proxy that connects to SSOGEN.	Empty: nobody is trusted
`SSOGEN_TRUSTED_PROXY_HOPS` (installer `--trusted-proxy-hops`)	How many proxies append to the header, 1 to 8.	1
`SSOGEN_CLIENT_IP_HEADER` (installer `--client-ip-header`)	Which one header to read.	`X-Forwarded-For`

You do: list your proxy’s subnet, make the proxy send the header, and let only the proxy reach SSOGEN’s port. If this is wrong, the audit trail shows the proxy’s address for everyone and per-address limits are shared. Monitoring > System health, under Setup health, has a “Client address” item. If a front end keeps the client address and adds no header, leave the list empty.

6. The Gateway and remote access

Concept	What it is	Why it exists	You do	Console
Gateway group and instance	An instance is one running Gateway. A group is a set of instances that serve the same routes; SSOGEN publishes routes to the group and each instance fetches them.	Several Gateways can share work and be replaced one by one.	Create a group and enroll instances (section 5).	Secure access > Gateways
App Proxy and route	A reverse proxy in front of an internal web application. A route maps a public host name to an internal back end: the visitor signs in to SSOGEN first, then is let through, and the application needs no change. The back end can be signed in by the signed-in user’s identity alone, by form login (form fill), or by Kerberos (Windows Integrated Authentication, which needs Enterprise Linux 9 on the Gateway host).	Publish an internal application without exposing it or touching it.	Add a route, a certificate and the application.	Secure access > App Proxy routes, Secure access > App Proxy certificates
Forward-auth	A way to use App Proxy when you already have your own ingress or reverse proxy: your ingress asks the Gateway whether to let each request through.	You keep your front end.	Issue a certificate and credential for the ingress, add a forward-auth listener and a route with Delivery set to forward-auth (guide).	Secure access > Gateways (listeners), Secure access > App Proxy routes
Remote resource	A server you reach in the browser: SSH (a terminal), RDP (a Windows desktop) or VNC (a Linux or appliance desktop). The Gateway connects only to the destination written in the signed configuration, never one the browser names. A resource can need approval: the person gives a reason and a duration, an approver decides, and the session ends when the approved window ends.	Administer servers without a VPN or a jump host.	Add the resource, who may use it, and whether approval is required.	Secure access > Remote Access (Resources, Requests, Live Sessions)
Stored account and pairing	For SSH, RDP and VNC, SSOGEN can keep one account (a password, an SSH key you upload, or a key SSOGEN generates) and sign people in with it, so they type nothing. Before a host can be used this way an administrator pairs it: the Gateway reports the key or certificate the host presents, the administrator compares it with the host’s own and presses Trust. People never accept a host key themselves. The stored account is write-only and goes only to the Gateway of one session.	Shared servers and desktops without handing out passwords, and a host identity nobody can be tricked into accepting.	Choose Stored account on the resource, store the account, then Pair and Trust.	Secure access > Remote Access
Outbound Connector and reach through	A small program inside a private network that dials out to your Gateway. A route or a remote resource that chooses Reach through a connector group is served over that connection, so the private network opens no inbound port.	Applications and servers in a factory, branch office or customer network the Gateway cannot reach.	Enroll a connector, add the Connector address and the connector group on the Gateway group, then pick the group on the route or resource.	Secure access > Outbound Connector, App Proxy routes
Host header	A route’s choice between sending the application its own internal name (Internal, with links, redirects and cookies in the answers rewritten back to the public name) or the public name unchanged (External).	Many applications break when they are asked for a name they do not know.	Leave Internal for a new route unless the application expects the public name.	Secure access > App Proxy routes
Relay, uplink and automatic certificates	A relay is a server on the internet that passes encrypted connections to a Gateway that dials out to it. A Gateway group’s Uplink relay setting turns that on, and SSOGEN then orders and renews the certificates for the relay names.	Reach a Gateway that has no inbound access.	Create a relay registration, give its admit string to whoever runs the relay, choose the uplink; the relay’s operator publishes the CAA record shown.	Secure access > App Proxy routes (Uplink relay)
Enrollment string	One pasted text, starting `ssogen-edge-enrol:`, shown once beside an enrollment token. It carries the token, the SSOGEN address and the fingerprint of the Gateway-identity authority.	No trust bundle to download or compare.	Paste it at the prompt of `ssogen-edge enrol`.	Secure access > Gateways

7. AI agents

AI agents are software that acts for a person or on its own. SSOGEN gives them identities that are as accountable as people: the feature is off for an organization until an administrator turns it on (the AI overview page), and then the rest of the AI agents menu appears. Decisions stay deterministic; no AI system makes the access decision.

Concept	What it is	Why it exists	You do	Console
Non-human identity	A registered, named identity for software: an AI agent, an MCP client, an automation or a service. Each has at least one human owner (up to five, one primary), so someone is always accountable. If its owner leaves, it is suspended.	Software needs identities that can be limited, audited and switched off.	Register each one; suspend or revoke when done.	AI agents > Identities
Scopes	The specific things an agent may do against a specific application. A request outside what was granted is refused, not quietly narrowed.	Least privilege.	Grant the few it needs, and open the application to non-human callers.	The agent’s page; the application’s Non-human callers tab
Consent and delegation	When an agent acts for a person, the person signs in under the application’s own policy and sees a consent screen. What they approve (agent, resources, scopes, expiry) is recorded. A delegation never gives the agent more than the person has. They can withdraw it any time.	A person decides what acts in their name.	Nothing; people manage theirs.	AI agents > Delegations; for a person, My Account > AI agents
Approvals	For sensitive scopes the agent can be made to ask each time. The person approves it in their My Apps Approvals inbox.	A human check on risky actions.	Nothing; the console page is read-only.	AI agents > Approvals
Tokens	Short-lived (at most 270 seconds) and tied to the agent’s own key, so a stolen token is useless without it. There is no refresh token.	Limits damage.	Nothing.	n/a
MCP server	An application that AI agents reach using the Model Context Protocol. The Gateway checks the scope on each tool call.	Agents need a safe way to use your tools.	Register the server.	AI agents > MCP servers
Kill switch	Stops every non-human identity of one type (AI agent, MCP client, Automation, Service) at once. Releasing it does not reactivate suspended agents. Turning the whole feature off stops new tokens at once; tokens already issued expire within 4.5 minutes, so engage a kill switch first for an instant stop.	An emergency stop.	Know where it is.	AI agents > Kill switches

8. Running it

Concept	What it is	You do	Console
License	The SSOGEN Software License Agreement ships in the bundle; your order states the term and quantities. SSOGEN itself has no license-key setting. The Web Agent’s standalone SAML and OpenID Connect modes (not the normal SSOGEN mode) need a license key from SSOGEN.	Keep the agreement; add the key only for those standalone modes.	n/a
SMTP	The mail server SSOGEN uses to send reset links, emailed codes and notices.	Enter the server and send a test mail.	Settings > SMTP (text messages: Settings > SMS)
Push (FCM and APNs)	The Google and Apple services that deliver push notifications to the Authenticator. SSOGEN provides push delivery for its app.	Nothing, unless you publish your own rebranded app and use your own Apple and Google credentials.	Settings > Authenticator (Push notifications)
Backups and restore	A restorable backup is several parts kept apart: the database, the environment file with its keys, the signing keystore and the TLS keystore. A database backup alone is not enough, and the keys must not be stored with it.	Back up all parts on a schedule; test a restore.	Install guide, Backup and restore
Upgrade	`install.sh --upgrade` checks the new bundle, stops the service, backs up the database and configuration, applies the new version and restarts. It refuses a downgrade. Deploy SSOGEN before upgrading Gateways.	Run it with the new bundle.	Install guide, Upgrade
System health and Setup health	System health shows a health badge, sign-in activity and deployment details. Under it, Setup health lists what the server still needs: mail, push, the HTTPS and signing certificates (flagged 60 days before they end), the certificate authority for agents and Gateways, Gateways, secrets and client addresses, each with a reason and a link to the fix.	Look here after install and when something is off.	Monitoring > System health
Audit and logs	The audit log is tamper evident (each event depends on the one before) and records sign-ins, changes and refusals. Logs shows the server’s newest log lines.	Check Audit integrity; export for auditors.	Monitoring > Audit, Monitoring > Logs, Monitoring > Webhooks
Version and build ID	Every build carries its version, build date and build ID. Quote the build ID when you ask for support.	Read it from the console, the start-up log line, or `--version`.	Home > Overview (build line)

9. Which concept do I need to touch? (your first day)

I want to…	You touch	You do not touch	First steps
Set up the first administrator	Canonical origin (chosen at install), the one-time setup token, your first account, your authenticator, recovery codes	Policies, groups, the workload CA	Install, open the setup address exactly as the canonical origin, enter the token, choose the name and password, scan the authenticator code, save the recovery codes. Then add a second administrator (Settings > Admin roles) and set mail (Settings > SMTP).
Add an application (SAML or OpenID Connect)	Application, access mode, assignment, a policy (or the default)	Agent key, workload CA, Gateway	Applications, register, copy the values to the application (Integration tab), assign a group, try it, activate.
Add an application behind Apache (Web Agent)	Application, assignment, agent key	Workload CA, enrollment tokens	Register under Web Agents, press Generate agent key, copy the Apache configuration, hand it to the web server team, assign a group, activate.
Connect a directory	Directory, identity providers, a secret (bind password), maybe a trusted authority	Policies at first	Identity > Directories: add the directory, test, import users, then use SSO policies > Defaults to set a default policy. An on-premises directory SSOGEN cannot reach can be tested through the Directory Connector on a Gateway, but sign-in does not use it yet.
Add a Gateway	Gateway group, enrollment token, the trust bundle, secret files (if a form names one), a TLS certificate for the route	Agent key, sign-in policies	Create a group and an enrollment token, install the Gateway, enroll it once, then check Monitoring > System health Setup health.
Make a login stronger	Policy (strength, second steps), access rules	The application itself	SSO policies > Policies, pick the second steps; use What if to test; assign the policy.
Turn on AI agents	AI overview setting, identities, scopes, kill switch	Everything else	AI agents > AI overview, turn on, register an agent with an owner, grant a scope.

10. Glossary

Alphabetical. Names in bold are the labels you see in the console.

Access mode: how an application is connected (SAML, OpenID Connect, Web Agent, App Proxy).
Access rules: the organization-wide ordered list where the first match decides and anything not allowed is denied.
Admin mode: the short-lived state in which an administrator may use administrator powers.
Agent key: the secret one Web Agent application uses to prove itself; shown once, stored hashed, rotated by regenerating.
Application: anything your people sign in to.
App Pack: a signed, ready-made definition of a well-known application.
App password: an application password a person stores for form fill.
App Proxy: the Gateway feature that puts SSOGEN sign-in in front of an internal web application.
Assertion: the signed statement SSOGEN sends a SAML application saying who signed in.
Assignment: giving an application to a person or group.
Audit log: the tamper-evident record of what happened and who did it.
Authentication policy: a named rule for providers, strength and second steps.
Authenticator (SSOGEN Authenticator): the phone app for number-matching approval and codes.
Build ID: the exact identity of the build you run, quoted for support.
Canonical origin: the one address people use to reach SSOGEN, fixed when the organization is created.
Client ID: the public name of an application.
Client credentials: what a caller shows to prove who it is.
Console policy: the policy that guards the Admin Console.
Default policy: the policy for applications that have none.
Delegation: what a person lets an AI agent do for them.
Directory: your LDAP or Active Directory, connected to SSOGEN.
Directory Connector: the Gateway feature that reaches a directory SSOGEN cannot.
Enrollment string: the one pasted text shown beside an enrollment token; it replaces the trust bundle download.
Enrollment token: a one-use invitation for a Gateway to become itself.
Everyone: the system group of every active person.
Forward-auth: your own ingress asks the Gateway whether to let each request through.
Form fill: the Gateway types a person’s own application password into a login form.
Gateway (SSOGEN Gateway): the program you run inside your network; its features are App Proxy, Remote Access, Outbound Connector and Directory Connector.
Gateway group: Gateways that serve the same routes.
Host header: the name an application is asked for; a route sends its own internal name or the public name.
Group: a named set of people.
Identity provider: a service that checks who a person is.
Import: bringing people in from a directory or a file.
JWKS: the published list of SSOGEN’s public signing keys.
Java agent (SSO4J): the agent for Java applications.
Kill switch: stops all non-human identities of one type.
Linked identity: a sign-in elsewhere tied to one SSOGEN user. Shown in My Account under Linked identities.
MCP server: an application AI agents reach through the Model Context Protocol.
Outbound Connector: a program in a private network that dials out to a Gateway so the Gateway can reach what is inside.
Pairing: the administrator’s check and trust of a remote host’s key or certificate.
My Apps: the home page that lists a person’s applications, with My Account in its left menu.
Number matching: approving a sign-in by tapping, on the phone, the number the sign-in page shows.
Phone approval: approving a sign-in on the paired SSOGEN Authenticator instead of typing a code.
Network zone: a named group of network addresses.
Non-human identity: a registered identity for software.
OpenID Connect (OIDC): a standard for an application to learn who signed in.
Passkey: sign-in with a device you already unlock; cannot be phished.
Realm (organization): one organization’s own space.
Recovery code: a single-use code for a lost phone.
Relay: a server on the internet that passes encrypted connections to a Gateway that dials out to it (Uplink relay).
Remote Access: SSH, RDP and VNC in the browser through the Gateway.
Remembered browser: a browser that skips the second step, when a policy allows. Two sign-ins at once in one browser (two tabs) do not forget it, though its next sign-in may ask the second step once more; three or more at once forget it.
Risk score: a fixed, explainable score for each sign-in.
Route: the rule that maps a host name to an internal application.
SAML: a standard for a signed statement of who signed in.
SCIM: a standard for exchanging accounts automatically.
Scope: a specific thing an agent may do.
Secret reference (secret://): a short address for a secret.
Session: the time you stay signed in.
Session secret: the key that signs a Web Agent’s own session cookie.
Setup health: the list of what a server still needs.
Signing key: the key SSOGEN signs tokens and assertions with.
Sign-in strength: single-factor, multi-factor or phishing-resistant.
Step-up: being asked for more proof mid-session.
Stored account: the one account SSOGEN keeps for a Remote Access resource and signs people in with; write-only.
TLS certificate: proves a server’s identity to whoever connects.
Trusted proxy: a proxy whose forwarded client address SSOGEN believes.
User: a person SSOGEN knows.
Web Agent (SSOGEN Web Agent): the Apache module that protects one application.
Workload CA / certificate: the authority and certificates SSOGEN issues to machines. The installer creates the authority.