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`](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

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

```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 `
  -RemoteDesktopGroupDn 'CN=SG-Laboratorio-Usuarios-RDP,OU=Laboratorio,DC=lci,DC=lasalle,DC=mx' `
  -CreateMissingOus `
  -DisableCertificateRevocationCheckForLab
```

Verify the service and managed OUs:

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

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

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

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

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

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

See [`windows-client-onboarding.md`](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.