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 a separately bounded, best-effort GET to the administrative incident overview for AD, the student information page for AL, or the portal menu for DO. After the incident page confirms an AD employee number, two additional GETs in the same in-memory session read the structured name from datos/personales.aspx and the address from datos/ubicacion.aspx. Docentes keep the menu name as a base and attempt those same two shared staff modules without requiring them 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. 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. A docente's supplemental fields remain tied to the fresh NTLM-authenticated portal session and are optional; the menu display name remains usable if neither shared page is available. 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.

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. 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.

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.