# 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 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`. A supplemental failure 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 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. 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. 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 for the complete hierarchy.

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.