# Architecture

## Online authentication

```text
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

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

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.