VPN XML Reference

If you are using AnyConnect 3.1, 3.0, or 2.5 and ASDM 6.3(1) or later, you will not need this reference. You will create and edit client profiles using the profile editor launched from ASDM or the standalone Profile Editor which is downloadable from Cisco.com. See “Introduction to the AnyConnect Client Profiles” section for more information.

Use this appendix only if you are not upgrading ASDM to 6.3(1) or later. AnyConnect 2.5 supports a profile editor that you can access to configure AnyConnect features. However, you can access it only with ASDM 6.3(1) or later. Earlier AnyConnect versions provided a standalone profile editor that you could install on Windows, but it was undocumented and unsupported and is no longer available as a standalone editor. We strongly recommend upgrading to ASDM because it is much easier to create, edit, and manage profiles directly with the AnyConnect profile editor than it is edit them with a conventional editor. The new profile editor is documented and supports and comes with its own online help. The minimum ASA software release supported by ASDM 6.3(1) with AnyConnect 2.5 is ASA 8.0(2). However, we recommend upgrading to ASA 8.3(1) or later to take full advantage of the new client features.

Read Chapter 3, Configuring AnyConnect Client Features for familiarity with the AnyConnect profile and features. This appendix provides an alternative to this chapter.

The following sections briefly describe each client feature and provide XML tag names, options, descriptions, and example code. AnyConnect uses the default value if the profile does not specify one. Consider case when entering all profile tags and the specific options within each value. You must match the upper or lowercase values presented in this chapter to avoid error conditions.

Note Do not cut and paste the examples from this document. Doing so introduces line breaks that can break your XML. Instead, open the profile template file in a text editor such as Notepad or Wordpad.

Trusted Network Detection

Enables TND. Automatically manages when a VPN connection should be started or stopped according to the TrustedNetworkPolicy and UntrustedNetworkPolicy parameters.

false

Disables TND. VPN connections can only be started and stopped manually.

TrustedNetworkPolicy

Disconnect

Disconnects the VPN connection in the trusted network.

Connect

Initiates a VPN connection (if none exists) in the trusted network.

DoNothing

Takes no action in a trusted network.

Pause

Suspends the VPN session instead of disconnecting it if a user enters a network configured as trusted after establishing a VPN session outside the trusted network. When the user goes outside the trusted network again, AnyConnect resumes the session. This feature is for the user’s convenience because it eliminates the need to establish a new VPN session after leaving a trusted network.

UntrustedNetworkPolicy

Connect

Initiates a VPN connection upon the detection of an untrusted network.

DoNothing

Initiates a VPN connection upon the detection of an untrusted network. This option is incompatible with always-on VPN. Setting both the Trusted Network Policy and Untrusted Network Policy to Do Nothing disables Trusted Network Detection.

TrustedDNSDomains

String

A list of DNS suffixes (a string separated by commas) that a network interface may have when the client is in the trusted network. The following is an example of a TrustedDNSDomain string:

*.cisco.com

Wildcards (*) are supported for DNS suffixes.

TrustedDNSServers

String

A list of DNS server addresses (a string separated by commas) that a network interface may have when the client is in the trusted network. The following is an example of a TrustedDNSServers string:

161.44.124.*,64.102.6.247

Wildcards (*) are supported for DNS server addresses.

Trusted Network Detection

Refer to the following example to configure trusted network detection. In the example, the client is configured to automatically disconnect the VPN connection when in the trusted network and to initiate the VPN connection in the untrusted network:

Specifies possible DNS suffixes that a network interface may have when in a trusted network.

TrustedDNSServers

string

Specifies DNS server addresses that a network interface may have when the client is in a trusted network.

TrustedNetworkPolicy

disconnect

Disconnects from the VPN upon detection of a trusted network.

connect

Connects to the VPN upon detection of a trusted network.

donothing

Do not connect to the VPN or disconnect from the VPN upon detection of a trusted network.

UntrustedNetworkPolicy

connect

Disconnects from the VPN upon detection of an untrusted network.

disconnect

Connects to the VPN upon detection of an untrusted network.

donothing

Do not connect to the VPN or disconnect from the VPN upon detection of an untrusted network.

AlwaysOn

true

Enables always-on VPN.

false

Disables always-on VPN.

ConnectFailurePolicy

open

Does not restrict network access when AnyConnect cannot establish a VPN session (for example, when an adaptive security appliance is unreachable).

closed

Restricts network access when the VPN is unreachable. The restricted state permits access only to secure gateways to which the computer is allowed to connect.

AllowCaptivePortalRemediation

true

Relaxes the network restrictions imposed by a closed connect failure policy for the number of minutes specified by the CaptivePortalRemediationTimeout tag so that the user can remediate a captive portal.

false

Enforces the network restrictions imposed by a closed connect failure policy even if AnyConnect detects a captive portal.

CaptivePortalRemediationTimeout

Integer

The number of minutes AnyConnect lifts the network access restrictions.

ApplyLastVPNLocalResourceRules

true

Applies the last client firewall it received from the security appliance, which may include ACLs allowing access to resources on the local LAN.

false

Does not apply the last client firewall received from the security appliance.

AllowVPNDisconnect

true

Displays a Disconnect button to provide users with the option to disconnect an always-on VPN session. Users might want to do so to select an alternative secure gateway before reconnecting.

false

Does not display a Disconnect button. This option prevents the use of the AnyConnect GUI to disconnect from the VPN.

Caution A connect failure closed policy prevents network access if AnyConnect fails to establish a VPN session. It is primarily for exceptionally secure organizations where security persistence is a greater concern than always-available network access. It prevents all network access except for local resources such as printers and tethered devices permitted by split tunneling and limited by ACLs. It can halt productivity if users require Internet access beyond the VPN if a secure gateway is unavailable. AnyConnect detects most captive portals (described in
Captive Portal Hotspot Detection). If it cannot detect a captive portal, a connect failure closed policy prevents all network connectivity.

If you deploy a closed connection policy, we highly recommend that you follow a phased approach. For example, first deploy always-on VPN with a connect failure open policy and survey users for the frequency with which AnyConnect does not connect seamlessly. Then deploy a small pilot deployment of a connect failure closed policy among early-adopter users and solicit their feedback. Expand the pilot program gradually while continuing to solicit feedback before considering a full deployment. As you deploy a connect failure closed policy, be sure to educate the VPN users about the network access limitation as well as the advantages of a connect failure closed policy.

Always-On VPN—XML Example

If you are using a release of ASDM that is earlier than 6.3(1), use the following example to edit the AnyConnect XML profile manually. This always-on VPN example does the following:

Enables the Disconnect button (AllowVPNDisconnect) to let users establish a VPN session with another secure gateway.

Specifies the connect failure policy is closed.

Relaxes network restrictions imposed by the connect failure policy for five minutes to remediate a captive portal.

Specifies when AnyConnect should warn users that their certificate is going to expire.

AutomaticSCEPHost

fully qualified domain name of the ASA/group-alias

The host attempts automatic certificate retrieval if this attribute specifies the ASA host name and connection profile (tunnel group) for which SCEP certificate retrieval is configured.

IP address of the ASA/group-alias

CAURL

fully qualified domain name

IP address of CA server

CertificateSCEP

Defines how the contents of the certificate will be requested.

CADomain

Domain of the certificate authority.

Name_CN

Common Name in the certificate.

Department_OU

Department name specified in certificate.

Company_O

Company name specified in certificate.

State_ST

State identifier named in certificate.

Country_C

Country identifier named in certificate.

Email_EA

Email address.

Domain_DC

Domain component.

SurName (SN)

The family name or last name.

GivenName (GN)

Generally, the first name.

UnstructName (N)

Undefined name.

Initials (I)

The initials of the user.

Qualifier (GEN)

The generation qualifier of the user. For example, “Jr.” or “III.”

Qualifier (DN)

A qualifier for the entire DN.

City (L)

The city identifier.

Title (T)

The person's title. For example, Ms., Mrs., Mr.

CA Domain

Used for the SCEP enrollment and is generally the CA domain.

Key Size

The size of the RSA keys generated for the certificate to be enrolled.

DisplayGetCertButton

true

Permits users to manually request provisioning or renewal of authentication certificates. Typically, these users will be able to reach the certificate authority without first needing to create a VPN tunnel.

false

Does not permit users to manually request provisioning or renewal of authentication certificates.

ServerList

Starting tag for the server list. The server list is presented to users when they first launch AnyConnect. Users can choose which ASA to log into.

HostEntry

Starting tag for configuring an ASA.

HostName

Host name of the ASA.

HostAddress

Fully qualified domain name of the ASA.

SCEP Protocols

Refer to the following example to configure SCEP elements in user profiles:

Specifies the number of days prior to the certificate’s expiration date. Users are warned that their certificate is expiring.

CertificateMatch

n/a

Defines preferences that refine client certificate selection. Include only if certificates are used as part of authentication. Only those CertificateMatch subsections (KeyUsage, ExtendedKeyUsage and DistinguishedName) that are needed to uniquely identify a user certificate should be included in the profile.

KeyUsage

n/a

Group identifier, subordinate to CertificateMatch. Use these attributes to specify acceptable client certificates.

MatchKey

Decipher_Only

Encipher_Only

CRL_Sign

Key_Cert_Sign

Key_Agreement

Data_Encipherment

Key_Encipherment

Non_Repudiation

Digital_Signature

Within the KeyUsage group, MatchKey attributes specify attributes that can be used for choosing acceptable client certificates. Specify one or more match keys. A certificate must match at least one of the specified key to be selected.

ExtendedKeyUsage

n/a

Group identifier, subordinate to CertificateMatch. Use these attributes to choose acceptable client certificates.

ExtendedMatchKey

ClientAuth

ServerAuth

CodeSign

EmailProtect

IPSecEndSystem

IPSecUsers

Timestamp

OCSPSigns

DVCS

Within the ExtendedKeyUsage group, ExtendedMatchKey specifies attributes that can be used for choosing acceptable client certificates. Specify zero or more extended match keys. A certificate must match all of the specified key(s) to be selected.

CustomExtendedMatchKey

Well-known MIB OID values, such as 1.3.6.1.5.5.7.3.11

Within the ExtendedKeyUsage group, you can specify zero or more custom extended match keys. A certificate must match all of the specified key(s) to be selected. The key should be in OID form (for example, 1.3.6.1.5.5.7.3.11).

DistinguishedName

n/a

Group identifier. Within the DistinguishedName group, Certificate Distinguished Name matching lets you specify match criteria for choosing acceptable client certificates.

DistinguishedNameDefinition

Bold text indicates default value.

Wildcard:

“Enabled”

“Disabled”

Operator:

“Equal” (==)

“NotEqual” ( !==)

MatchCase:

“Enabled”

“Disabled”

DistinguishedNameDefinition specifies a set of operators used to define a single Distinguished Name attribute to be used in matching. The Operator specifies the operation to use in performing the match. MatchCase specifies whether the pattern matching is case sensitive.

Name

CN

DC

SN

GN

N

I

GENQ

DNQ

C

L

SP

ST

O

OU

T

EA

ISSUER-CN

ISSUER-DC

ISSUER-SN

ISSUER-GN

ISSUER-N

ISSUER-I

ISSUER-GENQ

ISSUER-DNQ

ISSUER-C

ISSUER-L

ISSUER-SP

ISSUER-ST

ISSUER-O

ISSUER-OU

ISSUER-T

ISSUER-EA

A DistinguishedName attribute to be used in matching. You can specify up to 10 attributes.

Pattern

A string (1-30 characters) enclosed in double quotes. With wildcards enabled, the pattern can be anywhere in the string.

Specifies the string (pattern) to use in the match. Wildcard pattern matching is disabled by default for this definition.

Certificate Matching

Refer to the following example to enable the attributes that you can use to refine client certificate selections:

Note In this example, the profile options for KeyUsage, ExtendedKeyUsage, and DistinguishedName are just examples. You should configure only the CertificateMatch criteria that apply to your certificates.

Windows Mobile Policy

Note ● This configuration merely validates the policy that is already present; it does not change it.

AnyConnect version 3.0 and later does not support Windows Mobile devices. See Cisco AnyConnect Secure Mobility Client Administrator Guide, Release 2.5 for information related to Windows Mobile devices.

XML Tag Name

Options

Description

MobilePolicy

n/a

Determines the group identifier.

DeviceLockRequired

n/a

Group identifier. Within the MobilePolicy group, DeviceLockRequired indicates that a Windows Mobile device must be configured with a password or PIN prior to establishing a VPN connection. This configuration is valid only on Windows Mobile devices that use the Microsoft Default Local Authentication Provider (LAP).

Server List

Group identifier, subordinate to ServerList. This is the data needed to attempt a connection to a specific host.

HostName

An alias used to refer to the host, FQDN, or IP address. If this is an FQDN or IP address, a HostAddress is not required.

Within the HostEntry group, the HostName parameter specifies a name of a host in the server list.

HostAddress

An IP address or Full-Qualified Domain Name (FQDN) used to refer to the host. If HostName is an FQDN or IP address, a HostAddress is not required.

Group identifier, subordinate to CertificateMatch. Use these attributes to choose acceptable client certificates.

PrimaryProtocol

SSL or IPsec

The encryption protocol for the VPN tunnel, either SSL (default) or IPsec with IKEv2.

For IPsec, the client uses the proprietary AnyConnect EAP authentication method by default.

StandardAuthenticationOnly

n/a

Use the StandardAuthenticationOnly parameter to change the authentication method from the default proprietary AnyConnect EAP authentication method to a standards-based method.

Be aware that doing this limits the dynamic download features of the client and disables some features and disables the ability of the ASA to configure session timeout, idle timeout, disconnected timeout, split tunneling, split DNS, MSIE proxy configuration, and other features.

If you choose a standards-based EAP authentication method, you can enter a group or domain as the client identity in this field. The client sends the string as the ID_GROUP type IDi payload.

By default, the string is *$AnyConnectClient$*.

The string must not contain any terminators (for example, null or CR).

UserGroup

The connection profile (tunnel group) to use when connecting to the specified host.

This parameter is optional.

If present, used in conjunction with HostAddress to form a Group-based URL.

If you specify the Primary Protocol as IPsec, the User Group must be the exact name of the connection profile (tunnel group). For SSL, the user group is the group-url or group-alias of the connection profile.

Lets users enable or disable the running of OnConnect and OnDisconnect scripts.

false

(Default) Prevents users from controlling the scripting feature.

TerminateScriptOnNextEvent

true

Terminates a running script process if a transition to another scriptable event occurs. For example, AnyConnect terminates a running OnConnect script if the VPN session ends and terminates a running OnDisconnect script if AnyConnect starts a new VPN session. On Microsoft Windows, AnyConnect also terminates any scripts that the OnConnect or OnDisconnect script launched, as well as all their script descendents. On Mac OS and Linux, AnyConnect terminates only the OnConnect or OnDisconnect script; it does not terminate child scripts.

false

(Default) Does not terminate a script process if a transition to another scriptable event occurs.

EnablePostSBLOnConnectScript

true

Prevents launching of the OnConnect script if SBL establishes the VPN session.

false

(Default) When SBL establishes the VPN session, launches the OnConnect script, if present.

Authentication Timeout Control

By default, AnyConnect waits up to 12 seconds for an authentication from the secure gateway before terminating the connection attempt. AnyConnect then displays a message indicating the authentication timed out.

Allows only one local user to be logged on during the entire VPN connection. With this setting, a local user can establish a VPN connection while one or more remote users are logged on to the client PC. If the VPN connection is configured for all-or-nothing tunneling, then the remote logon is disconnected because of the resulting modifications of the client PC routing table for the VPN connection. If the VPN connection is configured for split-tunneling, the remote logon might or might not be disconnected, depending on the routing configuration for the VPN connection. The SingleLocalLogin setting has no effect on remote user logons from the enterprise network over the VPN connection.

SingleLogon

Allows only one user to be logged on during the entire VPN connection. If more than one user is logged on, either locally or remotely, when the VPN connection is being established, the connection is not allowed. If a second user logs on, either locally or remotely, during the VPN connection, the VPN connection is terminated.

WindowsVPNEstablishment

LocalUsersOnly

Prevents a remotely logged-on user from establishing a VPN connection. This is the same functionality as in prior versions of the AnyConnect client.

AllowRemoteUsers

Allows remote users to establish a VPN connection. However, if the configured VPN connection routing causes the remote user to become disconnected, the VPN connection is terminated to allow the remote user to regain access to the client PC.

Allow AnyConnect Session from an RDP Session for Windows Users

Refer to the following example to configure AnyConnect sessions from an RDP session:

Other AnyConnect Profile Settings

Table A-21 shows other parameters you can insert into the ClientInitialization section.

Table A-21 Other AnyConnect Profile Settings

XML Tag Name

Options

Description

CertificateStoreOverride

true

Allows an administrator to direct AnyConnect to search for certificates in the Windows machine certificate store. This tag becomes useful when certificates are located in this store and users do not have administrator privileges on their device. You must have a pre-deployed profile with this option enabled in order to connect with Windows 7 or VISTA using machine certificate. If this profile does not exist on a Windows 7 or VISTA device prior to connection, the certificate is not accessible in the machine store, and the connection fails.

false

(Default) AnyConnect will not search for certificates in the Windows machine certificate store.

ShowPreConnectMessage

true

Enables an administrator to have a one-time message displayed prior to a users first connection attempt. For example, the message can remind users to insert their smart card into its reader. The message appears in the AnyConnect message catalog and is localized.

false

(Default) No message displayed prior to a users first connection attempt.

MinimizeOnConnect

true

(Default) Controls AnyConnect GUI behavior when a VPN tunnel is established. By default, the GUI is minimized when the VPN tunnel is established.

false

No control over AnyConnect GUI behavior.

LocalLanAccess

true

Allows the user to accept or reject Local LAN access when enabled for remote clients on the Secure Gateway.

false

(Default) Disallows Local LAN access.

AutoUpdate

true

(Default) Installs new packages automatically.

false

Does not install new pacakges.

RSASecurIDIntegration

automatic

(Default) Allows the administrator to control how the user interacts with RSA. By default, AnyConnect determines the correct method of RSA interaction. An administrator can lock down the RSA or give control to the user.

software token

hardware token

RetainVPNOnLogoff

true

Keeps the VPN session when the user logs off a Windows operating system.

false

(Default) Stops the VPN session when the user logs off a Windows operating system.

UserEnforcement

AnyUser

Continues the VPN session even if a different user logs on. This value applies only if the RetainVPNPnLogoff is true and the original users logged off Windows when the VPN session was up.