3 out of 8 rated this helpful - Rate this topic

Windows 8 VPN PowerShell for VPN Client Management

To make VPN profile management easier for administrators, new PowerShell cmdlets have been introduced in Windows 8 client. These cmdlets help administrators create, configure, and remove VPN connections on client computers by using PowerShell scripts.

PowerShell cmdlets enable you to achieve complex tasks in few lines of scripts. Third-party vendors can build their custom solutions based on overall PowerShell support provided by Windows, specifically in Windows Networking.

You can write simple PowerShell scripts using these cmdlets with the entire required configuration for VPN connection deployment, and distribute these scripts to client computers via a common share or a web-portal. Knowledge Workers just need to execute these single-click scripts on their client computers, and the VPN profiles are configured automatically without any further input.

Using VPN deployment and management scripts - ITPro

You can use VPN client management cmdlets to write scripts for VPN connection deployment on Windows 8 computers. This following sections describe how to

Create VPN connections
Configure and edit VPN connections
Write configuration scripts for VPN connection management
Use these PowerShell commandlets in context of third party EAP methods

Create VPN connections

The PowerShell cmdlet for creating a VPN connection on the client system is Add-VpnConnection.

Syntax

Add-VpnConnection [-Name] <string> [-ServerAddress] <string> [-TunnelType <string> {Pptp | L2tp | Sstp | Ikev2 | Automatic}] [-EncryptionLevel <string> {NoEncryption | Optional | Required | Maximum}] [-AuthenticationMethod <string[]> {Pap | Chap | MSChapv2 | Eap}] [-SplitTunneling] [-AllUserConnection] [-L2tpPsk <string>] [-RememberCredential] [-UseWinlogonCredential] [-EapConfigXmlStream <xml>] [-Force] [-PassThru] [-WhatIf] [-Confirm]

Properties

As the name suggests, Name is the connection name, which is a mandatory parameter and cannot be changed (via cmdlet).
ServerAddress is the IP-Address/FQDN/URL of the remote server to which the connection is to be established. This is a mandatory parameter.
The remainder of the properties are optional. Their names and value sets indicate their purpose. For example, TunnelType specifies the VPN Tunnel selection (such as PPTP or L2TP), and AuthenticationMethod specifies the VPN authentication protocol selection).
Switch parameters (SplitTunneling, AllUserConnection, RememberCredentials, UseWinlogonCredentials) when specified, switch-on (enable) the property.
EapConfigXmlStream parameter accepts an EAP Configuration XML. This can be any EAP XML (in-box or 3rd party). For in-box EAP methods, this XML can be generated by using another PowerShell cmdlet, New-EapConfiguration, described below.

Configure and edit VPN connections

The PowerShell cmdlet for editing a VPN connection on the client system is Set-VpnConnection.

Syntax

Set-VpnConnection [-Name] <string> [[-ServerAddress] <string>] [-TunnelType <string> {Pptp | L2tp | Sstp | Ikev2 | Automatic}] [-EncryptionLevel <string> {NoEncryption | Optional | Required | Maximum}] [-AuthenticationMethod <string[]> {Pap | Chap | MSChapv2 | Eap}] [-SplitTunneling <bool>] [-AllUserConnection] [-L2tpPsk <string>] [-RememberCredential <bool>] [-UseWinlogonCredential <bool>] [-EapConfigXmlStream <xml>] [-PassThru] [-Force] [-WhatIf] [-Confirm]

Properties

Name is the connection name, which is a mandatory parameter and cannot be modified
AllUserConnection parameter is used to identify the scope of the connection (phonebook type). If this switch is supplied, the global phonebook is searched for the connection, otherwise the local connections are looked up for editing.
All the other parameters carry the same meaning as Add cmdlet (described above).

New-EapConfiguration

New-EapConfiguration is a VPN connection cmdlet used for generating EAP configuration XML, which is consumed by Add-VpnConnection or Set-VpnConnection cmdlets. This cmdlet can generate EAP configuration XML for in-box EAP authentication methods EAP-MSCHAPv2 (default), EAP-TLS (Smart card or other certificates), EAP-TTLS (for inner-authentication methods, it accepts in-box Non-Eap/EAP as well as 3rd party EAP configuration XMLs) and PEAP (for inner-authentication methods, it accepts in-box methods EAP-MSCHAPv2 and EAP-TLS as well as 3rd party EAP configuration XMLs).

Syntax

New-EapConfiguration [[-UseWinlogonCredential]] [-WhatIf] [-Confirm]
New-EapConfiguration [-Tls] [-VerifyServerIdentity] [-UserCertificate] [-WhatIf] [-Confirm]
New-EapConfiguration [-Ttls] [-UseWinlogonCredential] [-TunnledNonEapAuthMethod <string> {Pap | Chap | MSChap | MSChapv2}] [-TunnledEapAuthMethod <xml>] [-WhatIf] [-Confirm]
New-EapConfiguration [-Peap] [-VerifyServerIdentity] [-TunnledEapAuthMethod <xml>] [-EnableNap] [-FastReconnect <bool>] [-WhatIf] [-Confirm]

Properties

If no method switch (Tls, Ttls, Peap) is supplied, default method Eap-MsChapv2 is used.
Smart card is the default choice for EAP-TLS. To use user certificates, specify UserCertificate.
In addition to the in-box methods, admin can also supply EAP configuration XML for any EAP-authentication method for Ttls and Peap parameter sets in property TunneledEapAuthMethod.

VPN connection lookup

The PowerShell cmdlet for VPN connection lookup on the client system is Get-VpnConnection.

Syntax

Get-VpnConnection [[-Name] <string[]>] [-AllUserConnection]

Properties

Name is the connection name. It is an optional parameter here.
1. In case the connection name is not specified, all the VPN connection in the given phonebook are listed for the user.
2. More than one connection name (comma separated list) can also be looked up in the phonebook.
AllUserConnection parameter is used to identify the scope of the connection (phonebook type). If this switch is supplied, the global phonebook is searched for the connection(s), otherwise the local connection(s) is (are) used.

VPN connection removal

The PowerShell cmdlet for VPN connection deletion on the client system is Remove-VpnConnection.

Syntax

Name is the connection name. It is a mandatory parameter. More than one connection names (comma separated list) can also be removed at once.
AllUserConnection parameter is used to identify the scope of the connection (phonebook type). If this switch is supplied, the connection(s) is (are) removed from the global phonebook, otherwise the local connection(s) is (are) removed.]
Force switch is specified to suppress the connection removal confirmation dialogue.

Writing configuration scripts for VPN connection management

You can use the VPN management cmdlets described above for deploying VPN connections on computers running Windows 8 according to the network deployment and corporate requirements. This script, when distributed, is a single-click installer for Knowledge Workers.

The following examples show how to write a single-click script that can distribute the VPN profile and execute specific actions (post-connect actions) every time the VPN interface initiates.

# VPN Connection ‘My VPN’ provisioning 

#------------------------------------------------------------
# VPN Connection look-up to check any previous installations
#------------------------------------------------------------
$isTestVpn = $false
$vpnConnections = Get-VpnConnection -AllUserConnection

if($vpnConnections.Name -eq "My VPN")
{
    Write-Host "'My VPN' connection is already configured on your system." -ForegroundColor Yellow -BackgroundColor DarkGreen
    Write-Host "If you wish to reinstall, please uninstall the connection and then attemp again." -ForegroundColor Yellow -BackgroundColor DarkGreen
    Write-Host ""
    Write-Host "Please press any key to exit..."
    $x = read-host
    exit
}

Write-Host "******************************************" -ForegroundColor Black -BackgroundColor White
Write-Host "      Installing 'My VPN' connection      " -ForegroundColor Black -BackgroundColor White
Write-Host "__________________________________________" -ForegroundColor Black -BackgroundColor White

try
{
    # Generate Eap-Mschapv2 configuration XML
    $a = New-EapConfiguration
    # Generate Eap-TTLS configuration XML with EAP-Mschapv2 as inner method
    $b = New-EapConfiguration -Ttls -TunnledEapAuthMethod $a.EapConfigXmlStream
    # Edit properties within the generated configuration XML
    $c = $b.EapConfigXmlStream
    $c.EapHostConfig.Config.EapTtls.Phase1Identity.IdentityPrivacy = "false"

    # Create the VPN connection ‘My VPN’ with the EAP configuration XML generated above
    Add-VpnConnection -Name "My VPN" -ServerAddress "contoso.com" -EncryptionLevel Required -AuthenticationMethod Eap -EapConfigXmlStream $c -SplitTunneling -AllUserConnection
}
catch
{
    Write-Host "Error in connection setup!" -ForegroundColor White -BackgroundColor Red
    Write-Host $_.Exception.Message
    throw
}

Write-Host ""
Write-Host "‘My VPN’ VPN connection is ready for use." -ForegroundColor Black -BackgroundColor White

A sample script for adding post-connect task of plumbing routes and connection specific DNS suffix is shown below. This script adds a new task to the system Task-Scheduler which will perform the tasks upon VPN connect and post-connect:

## This piece of code performs the following actions –
## 1. Dynamically generate support files for VPN connection configuration,  
## 2. Creates task in task-scheduler, which triggers post-connect actions on the VPN connection using 
##    the support files generated above

write-host "Generating support files..."
# Create the common directory for support files
$testProfileDir = Test-Path $env:ALLUSERSPROFILE\Microsoft\Network\Connections\Cm\MyVPN\
if(!$testProfileDir)
{
    mkdir $env:ALLUSERSPROFILE\Microsoft\Network\Connections\Cm\MyVPN
}

$Directory = "$env:ALLUSERSPROFILE\Microsoft\Network\Connections\Cm\MyPN"

# Specify support file content variables, and generate these files in the common location ($Directory)
$RoutesFile = $Directory + "\routes.netsh"
$DnsSuffixFile = $Directory + "\dnssuffix.ps1"
$ConnectTaskFile = $Directory + "\Connect.xml"

# route provisioning file content
$routes = @"
interface ipv4
add route prefix=192.168.0.0/16 interface="My VPN" store=active
exit
"@

# Connection specific DNS suffix provisioning file content
$dnssuffix = @"
Set-DnsClient -InterfaceAlias "My VPN" -ConnectionSpecificSuffix "contoso.com"
"@

# Post-connect task scheduler XML file content
$connecttask = @"
<?xml version="1.0" encoding="UTF-16"?>
<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">

# XML file content
</Settings>
  <Actions Context="Author">
    <Exec>
      <Command>netsh.exe</Command>
      <Arguments>exec routes.netsh</Arguments>
      <WorkingDirectory>%ALLUSERSPROFILE%\Microsoft\Network\Connections\Cm\MyVPN\</WorkingDirectory>
    </Exec>
    <Exec>
      <Command>powershell.exe</Command>
      <Arguments>-Command "%ALLUSERSPROFILE%\Microsoft\Network\Connections\Cm\MyVPN\dnssuffix.ps1"
      </Arguments>
    </Exec>
  </Actions>
</Task>
"@

$routes|out-file -FilePath $RoutesFile
$dnssuffix|out-file -FilePath $DnsSuffixFile
$connecttask|out-file -FilePath $ConnectTaskFile

write-host "Files generated..."

write-host "Initiating configuration for ‘My VPN' ..." -ForegroundColor Black -BackgroundColor White
SCHTASKS /create /tn "\MyVPN\Connect" /xml $env:ALLUSERSPROFILE\Microsoft\Network\Connections\Cm\MyVPN\Connect.xml /F

write-host ""
write-host "Configuration completed..." -ForegroundColor Black -BackgroundColor White

Using VPN deployment and management scripts – Knowledge Worker

Once you write the scripts for connection deployment and distribute these scripts to a public share or an external web-portal, Knowledge Workers can simply go to the scripts’ location and run them by clicking. Once the scripts are run, the VPN profile is configured on the client computer, and is ready to use on the corporate network.

These cmdlets are available in all Windows 8 operating systems, and thus all types of clients (managed / unmanaged / PCs / tablets) can use these scripts for client deployment.

Using VPN client PowerShell commandlets for third party EAP methods

Inbox EAP authentication methods in Windows 8 are already supported with Add / Set / Get - VpnConnection, but configuration/retrieval of third party EAP authentication method for the given VPN connection is a bit tricky. This section describes how to retrieve the EAP configuration settings for third party EAP methods and use those settings to setup similar new VPN connections.

If a system is already configured with a VPN connection having a third party EAP authentication method, Get-VpnConnection for that VPN connection might fail if the configuration details are not stored in default phonebook. The workaround for this situation is as follows:

On a computer where the third party EAP authentication method is configured for VPN, in Start type Control Panel, click Network and Internet, and then click Network Connections.
Right-click the VPN connection configured with third party EAP authentication, and select Properties.
In the VPN Connection Properties, click the Security tab.
In Authentication - Use Extensible Authentication Protocol (EAP), verify that the third party EAP authentication method is selected.
Click Properties below the EAP method drop-down box.
Click OK twice to exit.
The third party EAP configuration details will now be stored in the default RAS phonebook, and the subsequent call to Get-VpnConnection will succeed.

To configure new VPN connections with the identical third party EAP method settings, retrieve the EAP configuration XML using Get-VpnConnection as described above, and then use Add/Set-VpnConnection with the EAP XML thus obtained.

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

Community Additions

ADD