SGU-CredentialProvider/README.md

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

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
• Broker location, health, timeout, and recovery
• Windows domain join and remote-access onboarding
• Required Credential Provider client enrollment
• Linux client enrollment with realmd and SSSD
• Domain monitoring, usage reports, and six-month retention
• Decision: do not persist password verifiers in Redis

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.

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. Review docs/security.md before production deployment and 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:

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:

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 for edition limitations, network parameters, security properties, and release publication.

Upstream license

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