Add SGU credential provider and authentication broker

2026-08-31 17:48:18 -06:00
parent 5e216f42a4
commit 1f43f200b4
50 changed files with 3226 additions and 236 deletions
@@ -0,0 +1,144 @@
+# Hyper-V lab runbook
+
+Validated lab inventory:
+
+- Domain controller/broker: Windows Server 2025 Standard,
+  `WIN-1AIQMMA1EPR.lci.lasalle.mx`, `192.168.50.10`.
+- Client: Windows 10 Pro 22H2,
+  `DESKTOP-U1I3BNN.lci.lasalle.mx`, `192.168.50.20`.
+- Domain: `lci.lasalle.mx` / `LCI`.
+- Private switch: `Laboratorio AD`.
+
+Run guest commands from an elevated PowerShell console inside each VM. Do not
+put an institutional password on a command line or in a script file.
+
+## 1. Build on the Windows 11 host
+
+```powershell
+Set-Location C:\Users\alex\Documents\projects\SGU-CredentialProvider
+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
+```
+
+Copy `artifacts\broker` and the deployment/certificate scripts to Windows Server.
+Copy `artifacts\credential-provider` and the installation/certificate scripts to
+Windows 10. Hyper-V Guest Service Interface or an ISO can be used because the
+lab switch is private.
+
+## 2. Create non-exportable lab certificates
+
+On Windows Server:
+
+```powershell
+.\New-LabCertificate.ps1 -Role BrokerServer
+```
+
+On Windows 10:
+
+```powershell
+.\New-LabCertificate.ps1 -Role CredentialProviderClient
+```
+
+Exchange only the two generated `.cer` public files. Never move a private key.
+The helper also trusts each self-signed public certificate on the machine where
+it was created. This is required because the provider deliberately refuses
+client certificates whose chain is not locally valid.
+On Windows Server, import the client public certificate; on Windows 10, import
+the server public certificate:
+
+```powershell
+.\Import-LabPeerCertificate.ps1 -CertificatePath .\peer.cer
+```
+
+Record both reported thumbprints. For a production CA, import the issuing CA
+chain instead and leave revocation checking enabled.
+
+## 3. DNS and broker
+
+The broker VM needs an internet-capable adapter in addition to the private lab
+adapter. On Windows Server, create the broker DNS record and set explicit lab
+forwarders so public SGU resolution survives a reboot. Use the Hyper-V Default
+Switch gateway shown by `Get-NetIPConfiguration` as the first forwarder; the
+public resolvers below are lab fallbacks. Production must use organization-
+approved DNS forwarders.
+
+```powershell
+Get-NetIPConfiguration
+.\Set-LabBrokerDns.ps1 `
+  -ExternalForwarders 172.30.32.1,1.1.1.1,8.8.8.8
+Resolve-DnsName sgu-auth.lci.lasalle.mx
+Resolve-DnsName sgu.ulsa.edu.mx
+```
+
+Deploy the broker, supplying the server certificate subject and client
+certificate thumbprint:
+
+```powershell
+.\Deploy-AuthBroker.ps1 `
+  -PublishPath C:\Deploy\broker `
+  -ServerCertificateSubject sgu-auth.lci.lasalle.mx `
+  -AllowedClientThumbprints CLIENT_CERT_THUMBPRINT `
+  -CreateMissingOus `
+  -DisableCertificateRevocationCheckForLab
+```
+
+Verify the service and managed OUs:
+
+```powershell
+Get-Service SGUAuthBroker
+Get-ADOrganizationalUnit -Filter * -SearchBase 'OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx'
+```
+
+## 4. Broker preflight from Windows 10
+
+Use the interactive credential prompt so the password is not placed in shell
+history:
+
+```powershell
+.\Test-Broker.ps1 `
+  -BrokerEndpoint https://sgu-auth.lci.lasalle.mx:8443/v1/authenticate `
+  -ClientCertificateThumbprint CLIENT_CERT_THUMBPRINT
+```
+
+Verify the returned domain/username, then confirm the user exists in the mapped
+OU on Windows Server. Use separate authorized test accounts for `DO`, `AL`, and
+`AD` when available.
+
+## 5. Install the Credential Provider
+
+On Windows 10:
+
+```powershell
+.\Install-CredentialProvider.ps1 `
+  -PublishPath C:\Deploy\credential-provider `
+  -BrokerEndpoint https://sgu-auth.lci.lasalle.mx:8443/v1/authenticate `
+  -ClientCertificateThumbprint CLIENT_CERT_THUMBPRINT `
+  -ServerCertificateThumbprint SERVER_CERT_THUMBPRINT `
+  -InstallDotNetRuntime `
+  -DotNetRuntimeInstallerPath C:\SGUDeploy\prerequisites\dotnet-runtime-10.0.11-win-x64.exe
+```
+
+Use Lithnet's `Invoke-CredUI` test utility when available, or lock the VM and
+select **Acceso institucional SGU** under sign-in options. Keep the built-in
+Windows password tile visible.
+
+## 6. Required end-to-end cases
+
+1. Online valid `DO`, `AL`, and `AD` logons; verify each OU.
+2. Explicit bad institutional password; verify rejection and no AD password reset.
+3. Change the institutional password, log on online once, and verify the new value
+   becomes the AD password.
+4. Stop `SGUAuthBroker`; verify the last synchronized AD password still logs on
+   through Windows cached/domain validation.
+5. While the broker is stopped, verify a different password fails.
+6. Start `SGUAuthBroker`; verify online synchronization recovers.
+7. Verify the Microsoft password Credential Provider still works throughout.
+
+## Rollback
+
+Run `Uninstall-CredentialProvider.ps1` in an elevated Windows 10 session. By
+default it removes only registration; add `-RemoveFiles` after reboot when the
+COM DLL is no longer loaded. Stop/remove the `SGUAuthBroker` service and firewall
+rule separately only after clients have been rolled back.