Files
SGU-CredentialProvider/README.md
T

173 lines
9.0 KiB
Markdown

# SGU Windows Credential Provider
Windows Credential Provider and ASP.NET Core authentication broker for the
`lci.lasalle.mx` Active Directory laboratory.
The repository starts from the current
[Lithnet Windows Credential Provider](https://github.com/lithnet/windows-credential-provider)
source and adds an SGU-specific provider, an mTLS-protected broker, Active
Directory synchronization, deployment scripts, and tests.
Ready-to-run bootstrap packages are published on the
[releases page](https://gitea.lci.ulsa.mx/alexrg/SGU-CredentialProvider/releases).
## Authentication contract
1. Windows selects **Acceso Institucional** by default. The built-in
Microsoft password provider stays available for recovery.
2. Ordinary domain usernames go straight to Windows for Active Directory
authentication. A `DO`, `AL`, or `AD` key is checked against SGU first.
3. The tile sends recognized institutional keys and their exact passwords over
mutually authenticated TLS. After SGU accepts the credential, the broker
performs an idempotent Active Directory UPSERT: it creates or repairs the
account, role OU and group, supported profile fields, and AD password.
4. If SGU rejects the key or is unavailable, the unchanged credentials go to
Windows. Existing AD accounts can authenticate there; unknown or misspelled
accounts are rejected by Windows and are never created.
No derived password is created. Passwords are not written to a database, file,
event log, application log, command line, or response.
This makes Active Directory the only Windows sign-in account while preserving
automatic synchronization: if a person changes their institutional password,
the next successful Acceso Institucional sign-in updates the domain password
before Windows continues. A matching prefix alone never creates an account;
the institutional authority must first accept the submitted password.
For administrative accounts, profile enrichment first verifies the employee
number against the incident overview, then reads the structured given names and
surnames from `datos/personales.aspx` and the postal address from
`datos/ubicacion.aspx` in the same authenticated session. Account type/status,
email, job title, and department remain sourced from the incident overview.
Birth date, identifiers, telephone, emergency-contact, incident, calendar,
photo, and manager fields are ignored. Student enrichment targets the read-only
student information page and reads only the matching student number, structured
name, email, career, and postal address. The career becomes an AD title in the
form `Estudiante de ...`; faculty/department remains unset because the verified
page does not expose it. Professors use the portal menu name as their safe base
profile and then attempt the same personal and location modules as administrative
staff. A missing route, non-success response, timeout, or absent element ID merely
skips that optional field. Missing or changed presentation HTML never blocks
authentication or password synchronization after the lightweight NTLM root has
accepted the credential.
For administrative staff and professors, the location page is enriched with its
ASP.NET PageMethods responses. `GetDireccion` supplies the saved state,
municipality and neighborhood identifiers; `GetLocalidadListado` resolves the
municipality name, and `GetColoniasListado` validates or supplies the
neighborhood name. This avoids reading the temporary `Seleccione...` values
visible while the browser populates those controls asynchronously.
Operational documentation:
- [Centro de Experiencia Digital Wi-Fi policy and management](docs/ced-network-operations.md)
- [One-command server recovery and client enrollment](docs/bootstrap-recovery.md)
- [Broker location, health, timeout, and recovery](docs/broker-operations.md)
- [Windows domain join and remote-access onboarding](docs/windows-client-onboarding.md)
- [Required Credential Provider client enrollment](docs/client-enrollment.md)
- [Linux client enrollment with realmd and SSSD](docs/linux-client-enrollment.md)
- [Self-hosted RustDesk server and managed Windows remote access](docs/rustdesk-operations.md)
- [Domain monitoring, usage reports, and six-month retention](docs/monitoring.md)
- [Laboratorio desktop wallpaper protection](docs/laboratorio-wallpaper-policy.md)
- [Optional Azure user roaming by role with Azure Files and FSLogix](docs/user-roaming.md)
- [Decision: do not persist password verifiers in Redis](docs/decisions/0001-no-password-cache.md)
| Prefix | Role | Default OU | Security group in the same OU |
|---|---|---|---|
| `DO` | Professor / docente | `OU=Docentes,OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx` | `SGU-Docentes` |
| `AL` | Student / alumno | `OU=Alumnos,OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx` | `SGU-Alumnos` |
| `AD` | Administrative | `OU=Administrativos,OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx` | `SGU-Administrativos` |
If the broker or institutional NTLM authority is unavailable, the provider
submits the unchanged credentials to Windows for normal AD/cached-domain
validation. This is not an unauthenticated bypass: Windows LSA must still accept
the last password registered in AD. An explicit NTLM `401` is rejected and is
not treated as an outage.
## Projects
- `src/SGU.CredentialProvider` — x64 .NET 10 COM Credential Provider based on Lithnet.
- `src/SGU.AuthBroker` — Windows-hosted ASP.NET Core broker with mTLS, NTLM validation,
and Active Directory provisioning.
- `src/SGU.AuthBroker.Core` — testable authentication workflow and prefix classifier.
- `tests` — exact-password, role mapping, rejection, and outage-fallback tests.
- `scripts` — publishing, certificate, server deployment, client installation,
broker testing, and rollback.
## Build
Prerequisites are captured in `.vsconfig`; the pinned SDK is .NET `10.0.400`.
```powershell
dotnet restore .\SGU-CredentialProvider.sln
dotnet build .\SGU-CredentialProvider.sln -c Release --no-restore
dotnet test --project .\tests\SGU.AuthBroker.Core.Tests\SGU.AuthBroker.Core.Tests.csproj -c Release
dotnet test --project .\tests\SGU.CredentialProvider.Tests\SGU.CredentialProvider.Tests.csproj -c Release
.\scripts\Publish-Lab.ps1
```
The provider's .NET COM host is framework-dependent, so the Windows client needs
the latest .NET 10 x64 runtime. The broker is published self-contained.
## Deployment and test
Follow [docs/lab-runbook.md](docs/lab-runbook.md). Review
[docs/security.md](docs/security.md) before production deployment and
[docs/architecture.md](docs/architecture.md) for the component contract.
For a public Azure VM, use
[docs/azure-vpn-deployment.md](docs/azure-vpn-deployment.md). It supports an
optional Azure P2S gateway or direct enrollment restricted to explicit public
source CIDRs. Every SGU role uses an ordinary local Windows profile by default:
Desktop and Documents stay under `C:\Users` and no profile share is mapped.
Azure Files/FSLogix roaming remains available only as an experimental,
explicit opt-in that requires acknowledgement of its login, sign-out, storage,
cache and recovery risks. See [docs/user-roaming.md](docs/user-roaming.md) for
the opt-in and rollback procedures.
Never disable the built-in Microsoft password Credential Provider. It is the
supported recovery path if a third-party provider fails to load.
For a clean Windows 10 or Windows 11 workstation, use the unified package:
- `sgu-windows-client-bootstrap-VERSION.zip` (x64 Pro, Enterprise or Education),
including optional Azure P2S setup for both versions.
Double-click `Start-SguClientEnrollment.cmd` and enter the server IP and domain
credentials, or provide the server IP on the command line:
```bat
Start-SguServerBootstrap.cmd 192.168.50.10
Start-SguClientEnrollment.cmd 192.168.50.10
```
El bootstrap prueba interfaces y rutas hacia el servidor, incluyendo VPN ya
conectadas, sin pedir la IP del cliente ni exigir la misma subred. Conserva DHCP
y el DNS de Internet; descubre el dominio autenticado y configura DNS sólo para
ese dominio. Si recibe una IP pública, configura DoH y los nombres necesarios de
AD después de autenticar al servidor. El segmento público del cliente debe estar
autorizado en el servidor y su firewall perimetral. Los casos sin DHCP o sin ruta
muestran un diagnóstico.
Ver [client-enrollment.md](docs/client-enrollment.md) para requisitos y parámetros
avanzados de IP estática.
Linux clients are enrolled through their native PAM/SSSD stack instead of the
Windows Credential Provider:
```bash
sudo bash ./Enroll-SguLinuxDomainClient.sh \
--domain-controller 192.168.50.10 \
--enable-hyperv-enhanced-session
```
The server command creates a new forest and resumes by itself after its required
restart. The client command registers a unique non-exportable mTLS certificate,
installs and validates SGU before domain join, then enables the managed remote
access configuration after restart. See
[bootstrap-recovery.md](docs/bootstrap-recovery.md) for edition limitations,
network parameters, security properties, and release publication.
## Upstream license
The Lithnet source remains under its MIT license in [LICENSE](LICENSE). Project
additions are distributed under the same license.