SGU-CredentialProvider/docs/architecture.md

Architecture

Online authentication

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

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 the broker is different: the provider displays an error and does not serialize the rejected credential.

Account synchronization

The broker normalizes the username to uppercase and accepts exactly two letters plus six digits. It searches BaseDn by sAMAccountName, creates the user when absent, moves it to the mapped OU when required, sets userPrincipalName, and passes the submitted password directly to ADSI SetPassword.

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.

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 SGU credential is rendered as a dedicated branded tile instead of being grouped below the anonymous Other user tile. Machine policy assigns the SGU 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 policy and disables screen savers for the complete hierarchy. 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.

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.