128 lines
6.2 KiB
Markdown
128 lines
6.2 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://github.lci.ulsa.mx/alexrg/SGU-CredentialProvider/releases).
|
|
|
|
## 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 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.
|
|
|
|
Operational documentation:
|
|
|
|
- [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)
|
|
- [Domain monitoring, usage reports, and six-month retention](docs/monitoring.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.
|
|
|
|
For a clean machine, the supported entry points are the release packages:
|
|
|
|
```bat
|
|
Start-SguServerBootstrap.cmd 192.168.50.10
|
|
Start-SguClientEnrollment.cmd 192.168.50.10
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
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.
|