Importare un profilo VPN in PowerShell con Add-VpnConnection

Non esiste alcun cmdlet Import-VpnProfile, e quello che gli somiglia di più, Add-VpnConnection, non legge mai un file .ovpn o .conf. Compone un profilo Windows nativo dai parametri che passate, ed è per questo che il primo punto di controllo qui è il formato del file e non la riga di comando. Se il gateway parla SSTP, IKEv2, L2TP/IPsec o PPTP, Windows può possedere il profilo e il resto della lista vale. Se vi è stato consegnato un file OpenVPN o WireGuard, fermatevi al primo passo: quei client hanno i propri importatori.

Passo 1: confermare quale profilo Windows può davvero possedere

Eseguite Get-Command -Module VpnClient sulla macchina prima di ogni altra cosa. Windows 10, Windows 11 e Server 2016 o successivi includono il modulo; se manca, nessuno script copiato farà accettare a questo host un profilo nativo. I cmdlet che contano sono Add-VpnConnection, Get-VpnConnection e Remove-VpnConnection, e l'elenco dei parametri nella documentazione di Add-VpnConnection merita una lettura completa.

Nativo significa che lo stack VPN di Windows termina il tunnel. Questo copre IKEv2, spesso con un certificato macchina; SSTP, che è TLS con autenticazione utente o certificato all'interno; e L2TP/IPsec con una chiave precondivisa. Un file .ovpn è uno script OpenVPN, non una connessione Windows: trasporta direttive come remote, cipher o tls-auth di cui lo stack Windows non ha alcun concetto. Un .conf WireGuard racconta la stessa storia con PrivateKey e AllowedIPs; convertire l'uno nell'altro non è una scelta di parametri ma un'altra implementazione del tunnel.

Esiste un terzo ramo. Se un amministratore vi consegna un documento XML VPNv2 CSP o un profilo Intune, quella è la via MDM, applicata dallo stack di provisioning e non da Add-VpnConnection. Non traducete quei nomi di nodo in parametri PowerShell; chiedete invece quale meccanismo applica l'XML.

Passo 2: abbinare il tipo di tunnel al metodo di autenticazione

-TunnelType e -AuthenticationMethod sono parametri separati, e al gateway interessa solo la combinazione. Uno giusto e l'altro sbagliato e ottenete un profilo che non si connette a nulla, o che si blocca con il tunnel già attivo. Impostate entrambi esplicitamente invece di fidarvi di un valore predefinito scelto per un altro servizio.

• IKEv2 con MachineCertificate: il client presenta un certificato computer; impostate anche -EncryptionLevel Required.
• SSTP con Eap: prima il tunnel TLS, poi PEAP/MSCHAPv2 o un certificato dentro EAP. Questo richiede l'XML del passo 3.
• SSTP, L2TP o PPTP con MSChapv2, Chap o Pap: nome utente e password semplici, senza blob EAP.
• L2TP con MSChapv2 e -Lt2pPsk: la PSK copre la metà IPsec, l'utente copre PPP; entrambe devono corrispondere al server.

Uno splat tiene i valori in un solo posto:

$p = @{
  Name                 = "Corp IKEv2"
  ServerAddress        = "vpn.example.com"
  TunnelType           = "Ikev2"
  AuthenticationMethod = "MachineCertificate"
  EncryptionLevel      = "Required"
  SplitTunneling       = $false
  DnsSuffix            = "corp.example.com"
}
Add-VpnConnection @p -PassThru

-PassThru restituisce l'oggetto che Windows ha appena scritto, così potete ispezionarlo senza una seconda chiamata. Se il nome esiste già, il cmdlet rifiuta di eseguire; -Force lo sovrascrive, ed è il riflesso sbagliato su un portatile di produzione, perché scarta in silenzio ciò che qualcuno ha configurato a mano.

Passo 3: consegnare correttamente il materiale delle credenziali

Le password, le chiavi precondivise e i blob EAP sono il punto in cui questi script di solito si rompono. -EapConfigXmlStream vuole un XmlDocument, non un percorso, quindi leggete e convertite prima il file. Passare una stringa produce un errore di conversione che sembra un problema di schema e spinge a riscrivere un XML che non è mai stato sbagliato.

$eap = [xml](Get-Content -Raw .\peap-mschapv2.xml)
Add-VpnConnection -Name "Corp SSTP" -ServerAddress "sstp.example.com" `
  -TunnelType Sstp -AuthenticationMethod Eap `
  -EapConfigXmlStream $eap -EncryptionLevel Required

Quell'XML non si inventa da un estratto di blog. Nomina il tipo di metodo EAP e l'autenticazione interna, e il gateway confronta entrambi con la sua policy. Un metodo interno non corrispondente fallisce dopo che lo handshake TLS è completato, il che sembra esattamente una password sbagliata e non lo è. Prendete l'XML da chi gestisce il gateway, o esportatelo da un profilo che già funziona.

Per IKEv2 la metà certificato è una ricerca nell'archivio. -MachineCertificateIssuerFilter accetta un oggetto certificato, e Windows lo usa per trovare un certificato client utilizzabile in LocalMachine\My. Il certificato ha bisogno di una chiave privata e di una catena fidata dal server; quando manca l'una o l'altra, l'autenticazione fallisce senza dettagli utili, quindi controllate prima l'archivio:

Get-ChildItem Cert:\LocalMachine\My |
  Where-Object { $_.HasPrivateKey -and $_.NotAfter -gt (Get-Date) } |
  Select-Object Subject, Issuer, Thumbprint, NotAfter

Tenete i segreti fuori dal file di script. Una PSK passata sulla riga di comando o cotta in un .ps1 finisce in trascrizioni, sessioni salvate e repository condivisi, e -RememberCredential memorizza le credenziali utente per dopo, trasformando un test una tantum in un'autorizzazione duratura.

Passo 4: decidere l'ambito prima della prima esecuzione

Lo stesso cmdlet scrive in due rubriche diverse. Senza -AllUserConnection il profilo è vostro e vive in %APPDATA%\Microsoft\Network\Connections\Pbk\rasphone.pbk. Con l'opzione, da un prompt elevato, il profilo va in %ProgramData%\Microsoft\Network\Connections\Pbk\rasphone.pbk ed è visibile a ogni account, schermata di accesso compresa.

L'ambito non è cosmetico. Un profilo per tutti gli utenti è ciò che un account di servizio, un'attività pianificata o uno scenario pre-accesso possono usare; un profilo per utente è invisibile a tutti e tre. Gli oggetti si leggono anche diversamente: Get-VpnConnection elenca le voci dell'utente corrente, Get-VpnConnection -AllUserConnection quelle dell'intera macchina. Sceglietene uno ora, e trattate un cambio successivo come eliminazione e ricreazione anziché modifica:

# elevated prompt
Remove-VpnConnection -Name "Corp IKEv2" -Force
Add-VpnConnection -Name "Corp IKEv2" -ServerAddress "vpn.example.com" `
  -TunnelType Ikev2 -AuthenticationMethod MachineCertificate `
  -EncryptionLevel Required -AllUserConnection

Passo 5: testare ciò che un tunnel deve davvero consegnare

Un'icona connessa prova che il tunnel è salito e nulla più. Collegatevi prima dalla riga di comando, così i guasti arrivano come testo e non come finestra di dialogo, poi rileggete ciò che Windows ha registrato:

rasdial "Corp IKEv2"
Get-VpnConnection -Name "Corp IKEv2" |
  Select-Object Name, ServerAddress, TunnelType, ConnectionStatus, SplitTunneling
Get-NetRoute -DestinationPrefix "0.0.0.0/0"

I due guasti che gli utenti segnalano mentre lo stato dice ancora Connected sono DNS e routing. Risolvete un nome interno e verificate quale server ha risposto; un profilo senza -DnsSuffix può tunnelare perfettamente e fallire comunque ogni ricerca intranet. Poi guardate la rotta predefinita: con lo split tunneling disattivato, la rotta 0.0.0.0/0 con metrica più bassa dovrebbe puntare nell'interfaccia VPN, e con lo split attivo solo i prefissi attesi. Se entrambe sembrano corrette e il traffico muore lo stesso, il problema è oltre il profilo, nella policy o nel filtro del gateway.

Quando la connessione fallisce del tutto, il codice restringe il passo da rivedere:

• 691: il gateway ha rifiutato le credenziali. Tornate al passo 3, non al tunnel.
• 809: lo handshake IKEv2 non è mai stato completato. Controllate UDP 500 e 4500, e la fiducia nel certificato.
• 789: la chiave precondivisa L2TP/IPsec manca o è errata.
• 868: il nome del server non è stato risolto. Sistemate il DNS prima di modificare il profilo.

Tenete il comando funzionante accanto alle impostazioni che codifica, così la persona successiva può ricostruire invece di decodificare a rovescio il profilo dall'interfaccia. Se dovete davvero ricostruire, cancellate la voce e ricreatela con gli stessi parametri; rattoppare un profilo configurato a metà lascia dietro rotte obsolete e stato di autenticazione. E se il file non è mai stato nativo, tornate al client che lo possiede. Un .ovpn travestito da profilo IKEv2 non è un'importazione, è un ticket di supporto.