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

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

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

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