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

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'

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

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.