GSSO — gStack Identity and Single Sign-On Platform — Terms of Reference


Document code	SPEC-GSSO-2026 / Report 00
Version	0.1-draft (EN source, governing)
Date	2026-10-05
Status	Draft — open for review; no ADR accepted yet
Companion reports	01 ADR · 02 Requirements · 03 Consumers & contract · 04 Technical documentation · 05 Roadmap
Design	`gsso.dc.html` (seed: `gstyle/design/src/GStack/GSSO.dc.html`, published at `s3.eu-west-1.amazonaws.com/gstack.awsarhitect.me/Sistem+GStack/GSSO.dc.html`)

Revision history

Version	Date	Changes
0.1-draft	2026-10-05	Initial terms of reference: purpose, problem, scope, actors, glossary, architecture overview, principles, AC-001..030, Q-GSSO-1..14

Reading conventions

GSSO is the platform name. Write “GSSO” in every user-facing text; “Keycloak” names only the embedded identity engine.
IDs: GSSO-ADR-nnn (decisions, report 01), GSSO-FR-nnn and GSSO-NFR-<AREA>-nnn (requirements, report 02), AC-nnn (acceptance criteria, this report), Q-GSSO-n (open questions, this report), phases S0..S5 (report 05).
IDs are never renumbered. A changed row is marked [REVISED date], an obsolete row [WITHDRAWN date] reason, and new IDs are appended at the end of their series.
Domain terms are Romanian (Platforma, AtribuireAcces, RolPlatforma…) in every language; framework vocabulary stays English.
CAP-GSSO-nn are capabilities requested by consuming applications (CRM report 03 §4.1 and the gDocFlow, gTenders, gFlow, gInsight packages).
CU-* are universal gStack requirements; NFRQnn are the caiet-de-sarcini non-functional codes (saas_drumuri/docs/reports/02-cerinte-functionale-nefunctionale.md).

Report set

#	Report	Content
00	Terms of Reference (this)	purpose, problem, goals, scope, actors, glossary, compliance, architecture, principles, acceptance criteria, open questions
01	ADR	GSSO-ADR-001..014
02	Requirements	GSSO-FR-, GSSO-NFR-, traceability to CAP-GSSO, CU-*, NFRQ
03	Consumers & contract	every gStack app, its current auth pattern and migration path; API, events, starter, onboarding
04	Technical documentation	C4 views, components, data model, flows, realm model, security, deployment, testing
05	Roadmap	phases S0–S5 with exit gates, MVP, risks, dependencies

1. Purpose

GSSO is the shared identity, authentication, authorisation and single sign-on platform (PaaS) of gStack. It gives every gStack SaaS (Interdicții, Cancelaria, gDocs, gRegistry, Drumuri, CRM, gDocFlow, gTenders…) and PaaS (GLog, GNotify, gStorage, gFlow, GDS portal…) one place to:

authenticate staff, citizens and services (OIDC/OAuth 2.1, SAML 2.0, MPass/eID federation, AD/LDAP federation, MFA);
register platforms and services together with their clients and the roles they expose;
authorise, by granting roles to a specific user on a specific platform, optionally scoped to an organisational unit and a validity window, with request and approval;
synchronise that governed model into the identity engine and detect drift;
audit every login, token, admin change and grant into GLog;
operate realms (tenants), users, sessions, credentials and authentication policies from a GDS console.

GSSO is built on top of the existing Keycloak 26.6.3 (https://sso.gstack.esempla.systems). Keycloak remains the identity runtime: credentials, sessions, tokens, MFA and federation. GSSO adds what Keycloak lacks for a government platform:

a service catalog;
a governed grant lifecycle;
desired-state reconciliation;
an append-only audit trail;
a standard integration kit;
a console in the gStack design system.

2. Problem statement

The current state, as observed on 2026-10-05:

No platform, only a server. Keycloak 26.6.3 runs as a hand-configured container on the shared demo host. There is no infrastructure-as-code, no realm export, no custom theme and no backup of configuration in any repository.
One shared realm with every app’s clients. Realm interdictii holds interdictii-web, gregistry-web, glog-web, glog-ingest, gstack-platform, cancelarie and others. A realm named after one SaaS is in practice the gStack staff realm.
Realms referenced but not reconciled. Code refers to realms gdocs, gnotify, gstorage, gstack and ultra. Only gstorage is recorded as created; gnotify is recorded as missing. Nothing tells which realm should exist.
Four inconsistent integration patterns:
- A, dual auth: the app mints its own HS512 JWT after the Keycloak login (interdictii, gdocs, gnotify).
- B, true resource server: the app validates Keycloak tokens directly (gregistry, glog, cancelarie).
- C, local JWT only, plus MPass SAML: drumuri.
- D, design only: CRM, gFlow, gDocFlow, gTenders. Roles live partly in Keycloak, partly in app databases.
Coarse roles. Only realm roles ROLE_ADMIN and ROLE_USER exist. They are shared by every app, so an admin of one app is an admin of all.
No governance of access. Grants are made by hand in the Keycloak admin console. There is no request, no approval, no expiry, no reason, and no view of “who can do what on which platform”.
No usable audit. Keycloak events are not stored durably nor forwarded to GLog. The dashboard figures in the design (logins per 24 h, failed logins, auth mix) cannot be produced.
Missing capabilities requested by consumers:
- CAP-GSSO-01: corporate realm and clients per microservice.
- CAP-GSSO-02: AD/LDAP and TOTP per role.
- CAP-GSSO-03: session list and forced termination.
- CAP-GSSO-04: revocation ≤ 60 s and org-unit claims.
- CAP-GSSO-06: automatable client provisioning.
- CAP-GSSO-07: token exchange.
Operational fragility. The TLS certificate of sso. expired on 2026-09-23 and broke every login, and admin secrets are kept in plain-text notes.

3. Goals and success criteria

#	Goal	Success criterion
G-1	One login for all gStack staff apps	A user logged into any staff app opens any other staff app without a second password prompt (AC-010)
G-2	Platform-scoped authorisation	Roles are namespaced per platform (`CRM_ADMIN`, `INTERDICTII_EMITENT`…); an admin of one platform has no rights on another (AC-012)
G-3	Governed access	Every role assignment has a requester, an approver (for sensitive roles), a reason, a validity, and an audit trail (AC-013..016)
G-4	Configuration as code	Realms, clients, roles, mappers, flows and theme are reproducible from the repository on an empty Keycloak (AC-005)
G-5	Drift visible	A change made directly in the Keycloak admin console is detected and reported within one reconcile cycle (AC-008)
G-6	Standard integration	A new app integrates with one starter dependency and three settings; no app mints its own tokens (AC-020)
G-7	Full audit	Every login, failure, token issuance for service accounts, admin change and grant transition appears in GLog with actor, realm, IP and time (AC-017)
G-8	Consumer capabilities	CAP-GSSO-01, 02, 03, 04, 06 and 07 are delivered (traceability in report 02 §III)

4. Stakeholders and consumers

Stakeholder	Interest
gStack platform team	Owns GSSO: build, run, upgrade Keycloak, publish the starter
Platform (app) owners	Register their app, define its roles, approve grants for their app
Security officer / auditor	Reviews access, approves sensitive roles, reads audit and login reports
Institution IAM administrators	Manage users of their realm or org unit
Staff end users	One login, MFA, self-service of credentials and sessions
Citizens	Login to public portals through MPass/eID
Consuming applications	Tokens with stable claims, service accounts, admin API for provisioning

Consumers are listed in report 03:

SaaS: interdictii, cancelaria, gdocs, gregistry, drumuri, CRM, gDocFlow, gTenders.
PaaS: glog, gnotify, gstorage, gflow, gportal/GDS, platform docs/RAG.
Mobile: gsso_mob (GovSign).
Whitelabel sites: ultra-, bts-, esempla-*.

5. Scope

5.1 In scope

Keycloak 26.6.x as the embedded identity engine, deployed from the GSSO repository with:
- a realm baseline (gstack, cetatean, the tenant template);
- the GSSO Keycloak extensions (event listener, protocol mappers);
- the GDS login, account and email themes in RO/RU/EN.
Realm (tenant) management: create from template, enable/disable, branding, federation (broker) and policies. The console has a realm switcher.
Service catalog: platforms and services (SaaS/PaaS) with owners, base URLs, accents, their clients (public PKCE, confidential, bearer-only, service account) and the roles each platform exposes (realm or client roles, composite, sensitive).
User management:
- create, invite, enable/disable, edit attributes (IDNP, org unit, locale);
- reset credentials, required actions;
- view and terminate sessions;
- view and remove MFA credentials;
- search across realms through a projection.
Access grants (AtribuireAcces): request → approve/reject → active → revoke/expire. Grants are per user × platform role × optional org unit × validity window, with four-eyes approval for sensitive roles, bulk grant and expiry notifications.
Organisational units: a tree, emitted as the org_unit claim.
Authentication policies per realm:
- methods: password, OTP, WebAuthn/passkey, QR cross-device, client credentials, broker, magic link;
- password policy and session lifetimes;
- MFA required for sensitive roles;
- the browser flow shown as ordered steps.
Desired-state reconciliation into Keycloak: idempotent jobs, retries, a periodic full reconcile, drift report or enforce per realm, and adoption of existing realms.
Events:
- Keycloak user and admin events through the extension to Kafka;
- GSSO’s own append-only events;
- forwarding to GLog;
- the dashboard: KPIs, logins per 24 h, failures, auth-method mix, recent security events.
API in GovStack zones: admin (console), app (consuming apps: self-registration, user lookup, grant request, session termination), plus the operational endpoints.
Integration kit: gsso-spring-boot-starter, @gstack/gsso-angular, and an onboarding runbook and checklist.
Token exchange (RFC 8693) configuration for on-behalf-of calls between apps.
Migration path for every existing app from patterns A/B/C to the standard, including the adoption of realm interdictii.

5.2 Out of scope

Re-implementing an identity provider. Login, tokens, credentials and federation stay in Keycloak (GSSO-ADR-001).
Business authorisation inside an app (row-level visibility, object ownership). GSSO provides roles and claims, and the app decides.
Qualified electronic signature (MSign / gsso_mob signing). GSSO authenticates; signing is a separate service.
An HR system. Employees and org structure may be imported, but the HR master stays outside.
The live production cut-over of existing apps and of the shared realm. This is planned in report 05 and executed only with explicit owner approval.
Terraform provider and Kubernetes operator. These are optional in S5.

6. Actors and roles

Actor	GSSO role	Can
Platform administrator	`GSSO_ADMIN`	Everything, in all realms; manage realms, templates, reconciler settings
Realm administrator	`GSSO_REALM_ADMIN` (scoped to a realm)	Users, clients, roles, policies of one realm
Platform owner	`GSSO_PLATFORM_OWNER` (scoped to a platform)	Define the platform’s roles and clients, approve grants on them
Approver / security officer	`GSSO_APPROVER`	Second approval for sensitive roles; access reviews
Auditor	`GSSO_AUDITOR`	Read-only: catalog, grants, events, reports
Helpdesk	`GSSO_HELPDESK`	Search users, reset credentials, unlock, terminate sessions; no role changes
End user	—	Self-service through the Keycloak account console (GDS theme): password, MFA, sessions; request access
Consuming application	service account with scope `gsso:app`	Self-register (when allowed), look up users, request grants, terminate sessions
Reconciler	`gsso-reconciler` service account in `master`	Apply desired state to Keycloak (never used by people)

7. Glossary

Term	Meaning
Realm	A Keycloak tenant: isolated users, clients, roles and policies. GSSO entity `Realm`
Platforma	A gStack SaaS or PaaS registered in the catalog (`crm`, `glog`…)
ClientAplicatie	An OIDC/SAML client of a platform: SPA (public + PKCE), backend (confidential or bearer-only), service account
RolPlatforma	A role exposed by a platform, prefixed with its code (`CRM_ADMIN`). It may be composite or sensitive
AtribuireAcces	A grant: one user receives one platform role, optionally for an org unit and a validity window
UnitateOrganizationala	An org-unit tree node, emitted as the `org_unit` claim
PoliticaAutentificare	A realm’s authentication policy: methods, password policy, MFA, session lifetimes
JobSincronizare	One unit of reconciliation work (create/update/delete in Keycloak) or one drift finding
ProiectieUtilizator	GSSO’s searchable read model of a Keycloak user
EvenimentGsso	An append-only audit event (login, admin, grant, sync)
Desired state	The configuration declared in GSSO; Keycloak is converged towards it
Drift	A difference between the desired state and Keycloak
Adoption	One-time import of an existing realm’s configuration into the catalog
SSO session	The Keycloak browser session shared by all clients of a realm
BFF	Backend-for-frontend: the JHipster gateway holds the tokens server-side; the SPA gets a session cookie
MPass	Moldova’s government authentication service (SAML), brokered by realm `cetatean`
IDNP	National personal identifier (13 digits), stored as a user attribute

8. Compliance

Area	Reference	GSSO response
Personal data	Law 133/2011 (RM), GDPR-aligned	Minimal user attributes; IDNP restricted to authorised roles; projection purge on user deletion; audit retention policy
Information security	NFRQ56–66 (least privilege, OWASP Top 10, session expiry, security audit)	Platform-namespaced roles, four-eyes for sensitive roles, MFA policy, session lifetimes, all admin actions audited
Audit	Law 133 forensic requirement, CU-AUDIT-*	Append-only `EvenimentGsso` with hash chain; forwarding to GLog WORM
Interoperability	GovStack Identity BB, CU-API-003..006	OIDC/OAuth 2.1, SAML, RFC 8693, RFC 7807, GovStack API zones
Government identity	MPass / eID	Identity brokering in realm `cetatean`
Accessibility	NFRQ39 (WCAG 2.1 AA)	GDS components in console and login themes
Languages	NFRQ38	RO (native), RU, EN in console, themes and emails
AI Act	Reg. (EU) 2024/1689	Not an AI system; no automated decision on access (triage in report 01, GSSO-ADR-014)

9. High-level architecture

flowchart LR
  subgraph Users
    adm[IAM admin / owner / auditor]
    staff[Staff user]
    cit[Citizen]
  end
  subgraph GSSO
    web[gsso-web<br/>Angular + GDS]
    gw[gsso-gateway<br/>JHipster BFF]
    srv[gsso<br/>JHipster microservice]
    db[(PostgreSQL gsso)]
    kc[Keycloak 26.6<br/>+ gsso extensions + GDS themes]
    kdb[(PostgreSQL keycloak)]
  end
  kafka[[Kafka]]
  glog[GLog]
  gnotify[GNotify]
  apps[gStack SaaS / PaaS]
  mpass[MPass / eID]
  ldap[AD / LDAP]

  adm --> web --> gw --> srv
  gw -. OIDC login .-> kc
  srv -- Admin REST --> kc
  srv --- db
  kc --- kdb
  kc -- events --> kafka --> srv
  srv -- audit --> glog
  srv -- expiry / approval mails --> gnotify
  staff -- OIDC --> kc
  cit -- OIDC --> kc -- SAML broker --> mpass
  kc -- federation --> ldap
  apps -- tokens / JWKS --> kc
  apps -- api/v1/app --> gw

gsso holds the governed model and reconciles it into Keycloak through the Admin REST API, using the service account gsso-reconciler.
Keycloak publishes user and admin events through the GSSO event-listener extension to Kafka gsso.kc-events.v1.
gsso consumes those events, stores them, updates the user projection and the dashboard, and forwards them to GLog.
Apps never call Keycloak’s admin API. They use tokens and JWKS from Keycloak and api/v1/app from GSSO.

10. Principles

Keycloak is the runtime, GSSO is the control plane. No credential, session or token logic is re-implemented (GSSO-ADR-001).
The desired state is declared in GSSO and converged into Keycloak. Manual Keycloak edits are drift (GSSO-ADR-004).
One staff realm for real SSO. All staff-facing gStack apps are clients of realm gstack. Citizens are in cetatean. Isolated tenants get their own realm (GSSO-ADR-002).
Roles belong to platforms. Every role is <PLATFORM>_<ROLE>. The only cross-platform roles are GSSO_* and the default ROLE_USER (GSSO-ADR-005).
Access is granted, not edited. Role mappings for people are created only through AtribuireAcces, so each one has a requester, an approver when needed, a validity window and a reason (GSSO-ADR-006).
Events are append-only and leave the platform. Everything is in EvenimentGsso and in GLog (GSSO-ADR-007).
One way to integrate. Apps are OAuth2 clients or resource servers validating GSSO tokens, through the starter. No app mints its own tokens or stores passwords (GSSO-ADR-009).
Configuration as code. Realm baselines, extensions and themes live in git. The production Keycloak can be rebuilt from the repository plus a database backup (GSSO-ADR-011).
Least privilege and four-eyes for sensitive roles, MFA for sensitive roles, short sessions for admins.
The DEV-PLAYBOOK stack: JHipster 9.1.0 microservice + gateway, OAuth2, Maven, PostgreSQL, Kafka, ro,ru,en, a separate Angular SPA on GDS (GSSO-ADR-010).

11. Requirements summary and acceptance criteria

11.1 Requirement groups (details in report 02)

Group	IDs	Count
Realms and tenants — FR-RLM	GSSO-FR-001..010	10
Service catalog — FR-CAT	GSSO-FR-011..022	12
Users and sessions — FR-USR	GSSO-FR-023..036	14
Roles and grants — FR-GRT	GSSO-FR-037..052	16
Organisational units — FR-ORG	GSSO-FR-053..056	4
Authentication and federation — FR-AUT	GSSO-FR-057..070	14
Reconciliation — FR-SYN	GSSO-FR-071..080	10
Events and audit — FR-EVT	GSSO-FR-081..090	10
Dashboard and reports — FR-RPT	GSSO-FR-091..096	6
App API and integration kit — FR-API	GSSO-FR-097..108	12
Console (UI) — FR-UI	GSSO-FR-109..116	8
Non-functional — NFR-*	PERF, CAP, AVL, SEC, TEN, OBS, OPS, CMP, DATA	44

11.2 Acceptance criteria

ID	Criterion
AC-001	`docker compose up` of the GSSO stack on an empty host yields Keycloak with realms `gstack` and `cetatean`, GDS login theme in RO/RU/EN, and the GSSO extensions loaded
AC-002	An admin logs into the GSSO console through `gsso-gateway` (realm `gstack`, client `gsso-console`); the SPA holds no token
AC-003	Creating a realm from the tenant template in the console creates it in Keycloak with the baseline flows, mappers and theme
AC-004	The realm switcher scopes every console screen to the selected realm; a `GSSO_REALM_ADMIN` sees only their realm
AC-005	Deleting realm `gstack` in a test Keycloak and running a full reconcile recreates its catalog-managed clients, roles, mappers and policies
AC-006	Registering a platform with 2 clients and 3 roles creates them in Keycloak within 10 s
AC-007	Reconciliation is idempotent: running it twice produces no change and no duplicate
AC-008	A role created by hand in the Keycloak admin console appears as `DRIFT` within one reconcile cycle; in `enforce` mode it is removed
AC-009	Adopting an existing realm imports its clients, roles and role mappings into the catalog without changing Keycloak
AC-010	A user logged into app A (realm `gstack`) opens app B without a password prompt; logout from the console ends the SSO session
AC-011	The access token contains `roles` (flat), `org_unit`, `locale` and, when allowed, `idnp`; `sub` is a UUID
AC-012	A user with `CRM_ADMIN` receives no `GLOG_` or `INTERDICTII_` authority in GLog or Interdicții
AC-013	A grant request for a non-sensitive role approved by the platform owner becomes `ACTIVA`, and the role is in the user’s next token
AC-014	A grant for a sensitive role needs two distinct approvers; the requester cannot approve their own request
AC-015	A grant with `validPana` in the past is expired by the scheduler, the mapping is removed and the user is notified
AC-016	Revoking a grant removes the mapping and terminates the user’s sessions on the affected clients; the role is absent from tokens within 60 s
AC-017	Login success, login failure, admin change and grant transition each appear in the console event list and in GLog with actor, realm, IP and time
AC-018	`UPDATE` and `DELETE` on `eveniment_gsso` are rejected by the repository and by a database trigger
AC-019	The dashboard shows realms, clients, users, active sessions, logins per 2 h over 24 h (success/failure), and the auth-method mix
AC-020	A sample Spring Boot app with only `gsso-spring-boot-starter` and 3 settings validates GSSO tokens and maps `roles` to authorities
AC-021	An app with scope `gsso:app` self-registers its platform, clients and roles through `POST /api/v1/app/platforme` (if self-registration is enabled for it)
AC-022	`DELETE /api/v1/app/utilizatori/{sub}/sesiuni` terminates the user’s sessions within 60 s
AC-023	Token exchange from client `crm-gateway` to audience `gdocflow` returns a token for the same user with the target audience; an unauthorised pair is refused
AC-024	OTP is required at login for a user holding any sensitive role; WebAuthn is accepted as an alternative
AC-025	Citizen login on a `cetatean` client is brokered to an MPass SAML mock and creates or links a user by IDNP
AC-026	Users, clients, roles, grants and events lists support filter, sort and pagination and respond within the NFR-PERF targets
AC-027	All console labels are translated in RO, RU and EN; no untranslated key is visible (`/gfront` sweep)
AC-028	`/health/live`, `/health/ready` (includes Keycloak reachability), `/metrics`, `/info`, `/api/v1/openapi.json` respond; errors are RFC 7807
AC-029	`/gsast` reports no high/critical finding without an accepted waiver; no secret in the repository
AC-030	The interdictii realm migration dry-run produces a mapping report (clients, roles, users) without any write to production

12. Open questions

ID	Question	Proposed answer	Owner
Q-GSSO-1	Keep realm `interdictii` as the staff realm and rename it in display only, or create `gstack` and migrate?	Create `gstack`, adopt `interdictii` read-only, migrate app by app (report 05 S4)	Platform team + app owners
Q-GSSO-2	Production MPass integration: SAML metadata, certificates and test accounts from AGE?	Mock in S2, real metadata when available	Institution
Q-GSSO-3	Which AD/LDAP directory (per institution) and read-only or writable federation?	Read-only, `READ_ONLY` edit mode, per realm	Institution IT
Q-GSSO-4	Which roles are sensitive by default?	All `_ADMIN`, `GSSO_` except `GSSO_AUDITOR`, roles flagged by owners	Security officer
Q-GSSO-5	Default validity of grants (indefinite or e.g. 12 months with renewal)?	12 months for sensitive roles, indefinite for others, with yearly access review	Security officer
Q-GSSO-6	Who may approve: platform owner only, or also the user’s org-unit head?	Platform owner, plus approver for sensitive roles; org-unit head optional per platform	Platform owners
Q-GSSO-7	Retention of login events (GSSO DB vs GLog)?	90 days in GSSO, as per GLog policy in GLog	DPO
Q-GSSO-8	Is the citizen realm `cetatean` part of this platform’s production scope or later?	Designed now, production after MPass is available	Product
Q-GSSO-9	gsso_mob QR cross-device login: implement as a Keycloak authenticator (SPI) or keep the per-site approve endpoint?	Keycloak authenticator in S5, keeps one implementation for all sites	Platform team
Q-GSSO-10	Hosting: stay on the shared demo host or move to the Kubernetes target of the playbook?	Docker compose on the demo host for S0–S3; Helm chart for the target	DevOps
Q-GSSO-11	Should apps keep a local “break-glass” admin account?	No local passwords; break-glass = a `master` realm emergency account held by the platform team	Security officer
Q-GSSO-12	Self-registration of platforms through `app` API: allowed for all apps or only platform team CI?	Only for clients explicitly flagged; others through the console	Platform team
Q-GSSO-13	`idnp` in tokens: always, never, or per client?	Per client, opt-in via a client scope `idnp`, approved by the DPO	DPO
Q-GSSO-14	Keycloak upgrade cadence (26.x minor) and who owns it?	Quarterly, platform team, with the realm baseline test suite as gate	Platform team