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

## Authentication contract

1. The Windows tile collects a `DO`, `AL`, or `AD` institutional key and a password.
2. It sends that exact password over mutually authenticated TLS to the broker.
3. The broker validates the same key/password pair against the lightweight SGU
   NTLM root. Only an authoritative `401`/`403` rejects the credential.
4. After successful authentication, the broker makes a separately bounded,
   best-effort request for the minimum available SGU profile fields.
5. On success, the broker creates or moves the AD user, updates the available
   name/mail/title/department/address metadata when available, and sets the AD password
   to the exact submitted password.
6. The Credential Provider serializes the original `SecureString` to Windows.

No derived password is created. Passwords are not written to a database, file,
event log, application log, command line, or response.

For administrative accounts, profile enrichment targets the read-only incident
overview and reads only the employee number, name, account type/status, email,
job title, and department from their stable element IDs. 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 retain the menu display-name fallback until
a richer role-specific page is verified. Missing or changed presentation HTML
never blocks authentication or password synchronization after the lightweight
NTLM root has accepted the credential.

Operational documentation:

- [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)
- [Decision: do not persist password verifiers in Redis](docs/decisions/0001-no-password-cache.md)

| Prefix | Role | Default OU |
|---|---|---|
| `DO` | Professor / docente | `OU=Docentes,OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx` |
| `AL` | Student / alumno | `OU=Alumnos,OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx` |
| `AD` | Administrative | `OU=Administrativos,OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx` |

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.

Never disable the built-in Microsoft password Credential Provider. It is the
supported recovery path if a third-party provider fails to load.

## Upstream license

The Lithnet source remains under its MIT license in [LICENSE](LICENSE). Project
additions are distributed under the same license.