SGU-CredentialProvider/docs/architecture.md

Architecture

Online authentication

LogonUI
  -> SGU Credential Provider (SecureString)
      -> HTTPS 1.1 + client certificate
          -> SGU Auth Broker
              -> SGU IIS NTLM endpoint (original password)
              -> minimum SGU profile metadata (same authenticated response)
              -> 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 logical GET is sent directly to the administrative incident overview for AD identities or to the portal menu for DO/AL identities. NTLM may still require its normal challenge/response round trips on that connection. The broker keeps any transient portal cookie in an in-memory per-request container; it is 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 displayName, mail, title, department, employeeType, and employeeID. The administrative employee number must match the six numeric digits of the requested AD identity before any scraped metadata is trusted. 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.

The managed hierarchy is rooted at OU=Usuarios-SGU: Docentes, Alumnos, and Administrativos are direct child OUs beneath it.

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.