# 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 configured SGU
   NTLM endpoint.
4. On success, the broker creates or moves the AD user and sets the AD password
   to the exact submitted password.
5. 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.

| 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 .\SGU-CredentialProvider.sln -c Release --no-build --no-restore
.\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.