Files
SGU-CredentialProvider/docs/architecture.md
T

200 lines
12 KiB
Markdown

# Architecture
## Online authentication
```text
LogonUI
-> SGU Credential Provider (SecureString)
-> HTTPS 1.1 + client certificate
-> SGU Auth Broker
-> SGU IIS lightweight NTLM root (original password)
-> minimum SGU profile metadata (bounded, best effort)
-> Active Directory (same original password + optional profile)
<- domain + canonical username; never a password
-> Windows credential serialization (original SecureString)
-> LSA / Kerberos / cached domain logon
```
The broker performs the NTLM exchange and AD update before returning `200 OK`.
It follows only HTTPS redirects whose host appears in `AllowedRedirectHosts`,
which prevents credential forwarding to an unexpected redirect target. HTTP/1.1
is forced because NTLM authentication is connection-bound.
The authoritative logical GET is sent to `/psulsa/`, a lightweight route that
returns the NTLM challenge without waiting for the slow application pages. A
`401` or `403` rejects the credential; an allowed `2xx` or `3xx` proves that IIS
accepted it. The broker then makes separately bounded, best-effort profile GETs.
It uses the administrative incident overview for `AD`, the student information
page for `AL`, and the portal menu as a conservative base for `DO`. After the
incident page confirms an `AD` employee number, two additional GETs in the same
in-memory session read the structured name and selected sex from
`datos/personales.aspx` and the address inputs from `datos/ubicacion.aspx`. The
broker then calls the location page's `GetDireccion`, `GetLocalidadListado`, and
`GetColoniasListado` methods to correlate the saved state, municipality, and
neighborhood identifiers instead of reading transient `Seleccione...` options.
Docentes request
`nomina/consultanomina.aspx` for a matching employee number, email, employee
type and job title, then attempt the same two shared staff modules without
requiring any optional route to exist. A supplemental
404, changed/missing element ID, other failure, or timeout preserves fields
already collected, and a profile timeout does not invalidate an already
authenticated credential. NTLM may still require its normal
challenge/response round trips on the connection. Transient portal cookies are
kept only in an in-memory per-request container and are never persisted or
returned to the client.
## Offline authentication
```text
Broker timeout, TLS failure, 429, or 5xx
-> provider preserves the entered username/password
-> Windows LSA validates against AD or its cached domain verifier
-> only the last AD password succeeds
```
An explicit `400` or `401` from SGU does not create or update an account. The
tile submits the unchanged credentials to Windows, which accepts them only if
they match an existing Active Directory account.
## Account synchronization
The visible Windows experience is one **Acceso Institucional** sign-in tile,
selected by default, with `Usuario` and `Contraseña`. Ordinary usernames go
straight to Windows for domain authentication. A `DO`, `AL`, or `AD` key is
checked by the broker against SGU. After SGU accepts the submitted password,
the broker searches `BaseDn` by `sAMAccountName`, creates the user when absent,
moves it to the mapped OU when required, sets `userPrincipalName`, and passes
that same password directly to ADSI `SetPassword`. This is an idempotent UPSERT
performed on every successful sign-in, so the next sign-in after an institutional
password change updates AD before Windows validates the interactive logon. If
SGU rejects the credential or is unavailable, the unchanged credentials go to
Windows; only an existing AD account can then authenticate. A matching username
pattern alone never provisions an account.
Before an account becomes usable, the broker applies explicit deny ACEs for the
Active Directory `Change Password` extended right to SELF and Everyone. Users
beneath `OU=Usuarios-SGU` therefore cannot replace the synchronized password
from Windows, Ctrl+Alt+Delete, LDAP or another client. The broker's
administrative `SetPassword` operation uses the separate `Reset Password` right
and remains able to synchronize the current institutional credential after each
successful SGU authentication. Repeated synchronizations detect the existing
ACEs and do not duplicate them.
When the authenticated HTML exposes recognized stable IDs, the broker also
updates the applicable `displayName`, `givenName`, `sn`, `mail`, `title`,
`department`, `employeeType`, `employeeID`, `streetAddress`, `l`, `st`, and
`postalCode` attributes. The SGU sex value is normalized to `Male`/`Female` and
written as the managed `SGU-Gender:` line in the built-in `info` attribute while
preserving unrelated notes. Administrative and student numbers must match the six
numeric digits of the requested identity before any role-specific metadata is
trusted. Administrative personal and location pages are accepted only after
that incident-page match. Docente payroll metadata must match the requested
six-digit number; all docente supplemental fields remain tied to the fresh
NTLM-authenticated portal session and are optional. The menu display name
remains usable if the payroll or shared staff pages are unavailable. Student faculty/department
is deliberately left unset because the verified page does not expose it.
Missing metadata does not clear existing AD values and never changes the
password outcome.
## Optional Azure user roaming
The default architecture uses local Windows profiles for every role. Desktop,
Documents and the remainder of the profile live under `C:\Users`; enrollment
does not map a profile share and the domain GPO keeps FSLogix disabled.
An experimental opt-in can add a dedicated Azure Files account. Student
accounts (`AL`) redirect only Documents/Desktop, while administrative and
professor accounts (`AD`/`DO`) receive an FSLogix VHDX profile container through
object-specific settings. Enabling it is never implicit: both infrastructure
deployment and policy configuration require an explicit risk acknowledgement.
The storage account uses AD DS Kerberos with AES-256 and share-root ACLs use
`CREATOR OWNER`. See [user-roaming.md](user-roaming.md) for the observed
sign-out/cache failure modes, staged rollout requirements and rollback.
Every synchronization also enforces one idempotent security-group membership
from the classified institutional prefix: `AL` to `SGU-Alumnos`, `AD` to
`SGU-Administrativos`, and `DO` to `SGU-Docentes`. Each role group is stored
inside its corresponding user OU. During an upgrade,
the bootstrap moves a legacy group from the `Usuarios-SGU` root while preserving
its SID and memberships instead of creating a duplicate. Membership enforcement
happens synchronously inside the broker before the institutional password is written to AD. A missing
or inaccessible role group therefore fails provisioning instead of leaving a
new usable account without its authorization classification. Existing accounts
are repaired automatically on their next successful SGU authentication.
Human-readable SGU values are decoded with BOM/header/meta detection, strict
UTF-8 validation, and a Windows-1252 fallback for the legacy portal. Names and
titles are normalized with Spanish-aware casing; particles such as `de`, `del`
and `de la` remain lowercase and Unicode accents are preserved. Values that
still contain the Unicode replacement character are not written to AD.
When `RemoteDesktopGroupDn` is configured, the broker also adds each successfully
synchronized SGU user to that dedicated AD security group. The laboratory
Windows client maps the group into its local **Remote Desktop Users** group.
Every synchronized user also receives `La Salle` in the AD
`company` attribute unless deployment configuration supplies another default.
The generic Acceso Institucional credential is rendered as a dedicated
branded tile instead of being grouped below the anonymous **Other user** tile.
Machine policy assigns
the provider CLSID as the default provider, hides the last signed-in identity, and
disables local-user enumeration while retaining the built-in Microsoft password
provider and its **Other user** recovery path. The computer GPO also applies
Windows' native default account picture to named Windows accounts; client
enrollment installs the La Salle mascot bitmap in Windows' standard account-picture
location before that GPO takes effect. It enumerates one
`CPFT_TILE_IMAGE` and places the `CPFT_LARGE_TEXT` heading immediately after it
with `CPFS_DISPLAY_IN_SELECTED_TILE`. LogonUI owns field typography and vertical
tile order: on Windows 10 and 11, the account-name title used by **Other user**
is shell UI, not a style that a generic Credential Provider can request. Do not
add a second tile image, filter the system password provider, or create a
synthetic Windows account to imitate that title or ordering.
The managed hierarchy is rooted at `OU=Usuarios-SGU`: `Docentes`, `Alumnos`,
and `Administrativos` are direct child OUs beneath it. The domain GPO
`SGU - User session restrictions` is linked to this root and enables the
per-user `DisableLockWorkstation` and `DisableChangePassword` policies and
disables screen savers for the complete hierarchy. The enforced laboratory
loopback GPO also applies `DisableLockWorkstation` and disables screen savers
for domain accounts. Its computer-startup script runs as `LocalSystem` and
writes the same setting into every existing local profile and the Default
profile template, covering local accounts such as `ing`; it deliberately does
not apply `DisableChangePassword` to them. The computer GPO
`SGU - Windows client experience` is linked to `OU=Laboratorio`; it suppresses
first-logon/privacy/diagnostic prompts, disables location, and enforces
always-on display, sleep, and hibernation settings for managed clients. The
same computer GPO configures Edge with `HideFirstRunExperience=1`,
`BrowserSignin=0`, and `SyncDisabled=1`, so shared machines do not show consumer
onboarding or permit personal browser sign-in and cloud synchronization.
That computer GPO also owns the base lock-screen image and a per-logon command
for the personalized desktop wallpaper. The client-side renderer reads the
managed `SGU-Gender: Male|Female` line from the user's built-in `info` attribute
(without requiring an irreversible AD schema extension). It uses neutral Spanish
when that optional enrichment is unavailable. The renderer also reads the
authenticated user's `displayName` plus the computer object's `location` and
immediate parent OU, then composes those values over the bundled dark-blue
background with the bundled Indivisa fonts. Missing directory attributes degrade
to deterministic text and never block the interactive session.
The domain controller is also the source-initiated Windows Event Collector for
managed laboratory computers. Kerberos-authenticated WEF sends only selected
logon/logoff, failed-logon, reconnect/disconnect, and operating-system power
events to `ForwardedEvents`. Daily EVTX archives are retained for 183 days, and
a five-minute server-side inventory records WinRM reachability and AD last-logon
metadata. Session-duration reports correlate Windows logon IDs; no password or
SGU HTTP payload is included in this monitoring path.
Broker diagnostics use the dedicated `SGU Auth Broker` Windows log with stable
event IDs for authorization outcomes, SGU network/timeout failures, unexpected
profile HTML, partial enrichment, and AD synchronization warnings. The same
daily maintenance task archives that log for 183 days. Messages identify the
institutional user and role but never include passwords, password verifiers, or
raw SGU HTML.
Per-user synchronization is serialized inside the broker to prevent concurrent
create/reset races. Production deployments should run the broker as a gMSA with
delegated create-user, move-user, write-property, enable-account, and reset-password
rights limited to `Usuarios-SGU` and its three managed child OUs. The lab can run it on the domain
controller as LocalSystem.