96 lines
4.7 KiB
Markdown
96 lines
4.7 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.
|
|
|
|
## 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.
|