SGU-CredentialProvider/docs/lab-runbook.md

Hyper-V lab runbook

Validated lab inventory:

• Domain controller/broker: Windows Server 2025 Standard, WIN-1AIQMMA1EPR.lci.lasalle.mx, 192.168.50.10.
• Client: no active Windows client VM. The next enrollment target is a clean Windows 11 Enterprise VM placed in OU=Laboratorio.
• 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.

For replacement machines, use the release bootstraps in bootstrap-recovery.md. They consolidate the manual steps below into one server command and one client command, including the required reboot/resume and per-client certificate registration.

1. Build on the Windows 11 host

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

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:

.\New-LabCertificate.ps1 -Role BrokerServer

On Windows 10:

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

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

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:

.\Deploy-AuthBroker.ps1 `
  -PublishPath C:\Deploy\broker `
  -ServerCertificateSubject sgu-auth.lci.lasalle.mx `
  -AllowedClientThumbprints CLIENT_CERT_THUMBPRINT `
  -RemoteDesktopGroupDn 'CN=SG-Laboratorio-Usuarios-RDP,OU=Laboratorio,DC=lci,DC=lasalle,DC=mx' `
  -CreateMissingOus `
  -DisableCertificateRevocationCheckForLab

Verify the service and managed OUs:

Get-Service SGUAuthBroker
Get-NetTCPConnection -LocalPort 8443 -State Listen
sc.exe qfailure SGUAuthBroker
Get-ADOrganizationalUnit -Filter * -SearchBase 'OU=Usuarios-SGU,DC=lci,DC=lasalle,DC=mx'
Get-ADGroup -Filter 'SamAccountName -like "SGU-*"' -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:

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

For a new client, prefer the provider-first transaction in client-enrollment.md. The direct installation below is kept for repair and existing domain members.

On Windows 10:

.\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 `
  -TimeoutSeconds 90 `
  -InstallDotNetRuntime `
  -DotNetRuntimeInstallerPath C:\SGUDeploy\prerequisites\dotnet-runtime-10.0.11-win-x64.exe

Use Lithnet's Invoke-CredUI test utility when available, or sign out/restart the VM and select Acceso institucional SGU. Keep the built-in Windows password provider available through Other user.

On the domain controller, apply the SGU user and computer policies once:

.\Set-SguDomainUserPolicies.ps1
.\Set-SguDomainComputerPolicies.ps1

It links SGU - User session restrictions to OU=Usuarios-SGU and prevents managed users from manually locking the workstation or starting a screen saver. It also links SGU - Windows client experience to OU=Laboratorio to suppress first-logon privacy/diagnostic/location screens and keep display, sleep, and hibernation disabled.

Before testing through Hyper-V Enhanced Session/RDP, enable the dedicated lab group and Windows PowerShell Remoting:

.\Enable-LabRemoteAccess.ps1 `
  -RemoteDesktopPrincipal 'LCI\SG-Laboratorio-Usuarios-RDP' `
  -EnableAdministrativeFirewallGroups

See windows-client-onboarding.md for domain join, RDP, WinRM, firewall, and error 0xC000015B diagnostics.

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.