en-US
search-icon

Mobile Connect 4.0 OS X User Guide

Preferences and URL Control

This section describes the configurable elements that are accessed from the Preferences screen in Mobile Connect, including connection settings and URL control.

Topics:

Related topics:

Preferences Overview

SonicWall Mobile Connect allows you to set several preferences for connection and logging options. The Preferences screen is available under the SonicWall Mobile Connect menu.

SonicWall Mobile Connect menu

Tapping Preferences displays the configurable settings.

Preferences settings

The following options are controlled from the Preferences screen:

Connect on Launch - Sets Mobile Connect to automatically initiate a connection to the last-used profile when the application is launched.
Automatic Reconnect - Sets Mobile Connect to automatically attempt to reconnect if the connection is lost. The SSL VPN connection can be disrupted when your device’s connection transitions to a different network type (for example, from wireless to cellular). This setting lets applications rely on a sustained VPN connection. There is no limit on the amount of time it takes to reconnect.
URL Control - Allows other mobile applications to pass action requests using special URLs to Mobile Connect. These action requests can create VPN connection entries and connect or disconnect VPN connections. For example, another application can launch Mobile Connect, access internal resources as needed, and then disconnect by using the mobileconnect:// or sonicwallmobileconnect:// URL scheme.

Additional information about URL Control is provided in URL Control Syntax and Parameters.

Debug Logging - Enables full debug log messages of Mobile Connect activity. Leave this section disabled unless instructed to enable it by SonicWall Support staff.

Additional SMA 1000 Series / E-Class SRA Options

Two additional options can be modified for connections to SonicWall SMA 1000 Series / E-Class SRA appliances.

To view these options:
1
Navigate to the Connection screen.
2
Select an SMA 1000 Series / E-Class SRA connection from the Connections list.
3
Tap the Edit icon next to the selected connection.

The Edit Connection screen displays.

The following options can be configured:

Remember Credentials - Enables saving of user authentication credentials for the VPN connection. This is disabled by default and can be controlled by the SonicWall SMA 1000 Series / E-Class SRA server configuration.
Forget Selections - Mobile Connect remembers the Login Group that you specified when configuring the connection. To change to a different Login Group, tap Forget Selections. The next time you connect to the server, you are prompted to select a new Login Group.
* 
NOTE: If these options are not displayed, then you are connecting to either a SonicWall firewall or SMA 100 Series / SRA appliance.

URL Control Syntax and Parameters

This section provides the full set of URL parameters for the URL Control feature. URL Control currently supports the addprofile, connect, and disconnect commands. Callback URLs are also supported.

Topics:

Using the addprofile Command

The addprofile command requires either the name or server parameter, and accommodates both. All other parameters are optional. When the URL is opened in Mobile Connect, all of the parameters included in the URL are saved in the connection entry associated with that name and server.

Syntax for addprofile:

mobileconnect://addprofile[/]?name=ConnectionName&server=ServerAddress
[&Parameter1=Value&Parameter2=Value...]

 

addprofile command parameters

Command parameter

Description

name

The unique name of the VPN connection entry that is created and appears in the Mobile Connect Connections list. Mobile Connect accepts the name only if it is unique. Letters are case sensitive.

server

The domain name or IP address of the SonicWall appliance to which you wish to connect. For example: vpn.example.com

username

Optional: The username used in the VPN connection.

password

Optional: The password used in the VPN connection.

realm

Optional: The realm used in the VPN connection profile. Applies to SMA 1000 Series / E-Class SRA connections only.

domain

Optional: The domain used in the VPN connection profile. Applies to SRA 100 Series / SRA and Firewall connections only.

sessionid

Optional: The session ID or Team ID used for authentication.

connect

Optional: If presented and the value is non-null, the connection is initiated if the profile was successfully added.

callbackurl

Optional: The callback URL to be opened by Mobile Connect after the addprofile command has been processed. See Using the callbackurl Command Parameter for full details of the callback URL syntax and options.

Examples of the addprofile command:

mobileconnect://addprofile/?name=Example&server=vpn.example.com

sonicwallmobileconnect://addprofile/?name=Example&server=vpn.example.com

mobileconnect://addprofile?name=Example%202&server=vpn.example.com

mobileconnect://addprofile?name=vpn.example.com

mobileconnect://addprofile?server=vpn2.example.com

mobileconnect://addprofile?name=SRA%20Connection&server=sslvpn.example.com
&username=test&password=password&domain=LocalDomain&connect=1

mobileconnect://addprofile?name=EX%20Connection&server=workplace.example.com
&username=test&password=password&realm=Corp&connect=1

* 
NOTE: All appropriate characters in values of parameters used in URLs are required to be URL encoded. For instance, to match a space, enter %20.

Using the connect Command

The connect command is used to easily establish VPN connections. Connection information can be embedded in the URLs and they can be provided to users for easy setup and configuration. In addition, a callback URL can be provided that Mobile Connect opens after the connection attempt is completed, making it possible for other applications to initiate VPN connections in a seamless manner.

Syntax for connect:

mobileconnect://connect[/]?[name=ConnectionName|server=ServerAddress]
[&
Parameter1=Value&Parameter2=Value...]

 

connect command parameters

Command parameter

Description

name

The unique name of the VPN connection entry that is created and appear in the Mobile Connect Connections list. Mobile Connect accepts the name only if it is unique. Letters are case sensitive.

server

The domain name or IP address of the SonicWall appliance in which you wish to connect. For example: vpn.example.com

username

Optional: The username used in the VPN connection.

password

Optional: The password used in the VPN connection.

realm

Optional: The realm used in the VPN connection profile. Applies to SMA 1000 Series / E-Class SRA connections only.

domain

Optional: The domain used in the VPN connection profile. Applies to SMA 100 Series / SRA and Firewall connections only.

sessionid

Optional: The session ID or Team ID used for authentication.

connect

Optional: If presented and the value is non-null, the connection is initiated if the profile was successfully added.

callbackurl

Optional: The callback URL is opened by Mobile Connect after the connect command has been processed. See Using the callbackurl Command Parameter for full details of callbackurl syntax and options.

Examples of the connect command:

mobileconnect://connect/?name=Example

sonicwallmobileconnect://connect/?name=Example

mobileconnect://connect?name=Example

mobileconnect://connect?server=vpn.example.com

mobileconnect://connect?name=Example%202&server=vpn.example.com

mobileconnect://connect?name=SRA%20Connection&server=sslvpn.example.com
&username=test&password=password&domain=LocalDomain

mobileconnect://connect?name=EX%20Connection&server=workplace.example.com
&username=test&password=password&realm=Corp

Using the disconnect Command

The disconnect command is used to disconnect an active connection. In addition, a callback URL can be provided that Mobile Connect opens after the connection is disconnected that makes it possible to return to the calling application. If there is no active VPN connection, the disconnect command is ignored.

Syntax for disconnect:

mobileconnect://disconnect[/]

mobileconnect://disconnect[/]?[callbackurl=CallBackURL]

 

disconnect command parameters

Command parameter

Description

callbackurl

Optional: The URL defined for callbackurl is opened by Mobile Connect after the disconnect command has been processed. See Using the callbackurl Command Parameter for full details of callbackurl syntax and options.

Examples of the disconnect command:

mobileconnect://disconnect

mobileconnect://disconnect/

sonicwallmobileconnect://disconnect

mobileconnect://disconnect?callbackurl=customapp%3A%2F%2Fhost%3Fstatus%3D%24STATUS
%24%26login_group%3D%24LOGIN_GROUP%26error_code%3D%24ERROR_CODE%24

sonicwallmobileconnect://disconnect?callbackurl=customapp%3A%2F%2Fhost%3Fstatus%3D
%24STATUS%24%26login_group%3D%24LOGIN_GROUP%26error_code%3D%24ERROR_CODE%24

Using the callbackurl Command Parameter

callbackurl is an optional query string argument for each of the connect/disconnect/addprofile commands. If a callback URL is included in a command, then that URL will be launched by Mobile Connect once the command has been completed. While invoking Mobile Connect using a URL, a third-party application can use the callbackurl parameter to include a URL to be launched by Mobile Connect after it completes the requested action.

The callbackurl value can contain special tokens that are evaluated and dynamically replaced by Mobile Connect to provide additional status and connection information back to the app that is opened by the callback URL. Tokens are evaluated in place, in the same order in which the tokens were specified.

To ensure that it functions properly, the base callbackurl URL value format should be RFC 1808 compliant and should be able to be launched independently of Mobile Connect. For example, it should launch through a web page.

URL syntax for a callbackurl:

<scheme>://<net_loc>/<path>;<params>?<query>#<fragment>

* 
NOTE: The URL value of callbackurl must be properly URL encoded to ensure that Mobile Connect can process the callback URL correctly. All appropriate characters in values of parameters used in URLs are required to be URL encoded. For instance, to match a space, enter %20.

Any number of dynamic tokens from Dynamic tokens supported by callbackurl can be specified in the <query> element of the URL. These can be used by administrators when configuring the callback URLs on a web site or in an email to their users, such as to auto-configure a VPN profile. The dynamic tokens are useful because they allow Mobile Connect to provide information to the website or app that is being launched when the callback URL is opened.

 

Dynamic tokens supported by callbackurl

Dynamic token

Description

$ERROR_CODE$

The numerical value of the error from the failed connection attempt.

$ERROR_MESSAGE$

The string value of the error message from the failed connection attempt.

$LOGIN_GROUP$

The string value of the authentication login group or realm. Applies to SMA 1000 Series / E-Class SRA connections only.

$COMMUNITY$

The string value of authentication community. Applies to SMA 1000 Series / E-Class SRA connections only.

$ZONE$

The string value of EPC (End Point Control) zone. Applies to SMA 1000 Series / E-Class SRA connections only.

$TUNNEL_IP$

The string value of the Mobile Connect IPv4 client address.

$TUNNEL_MODE$

One of split, split-nonlocal, redirectall, or redirectall-nonlocal, depending on the tunnel mode. Applies to SonicWall SMA 1000 Series / E-Class SRA connections only.

$ESP_ENABLED$

One of yes or no, depending on if ESP (Encapsulating Security Payload) is enabled. Applies to SonicWall SMA 1000 Series / E-Class SRA connections only.

ESP is a protocol used to provide confidentiality, data origin authentication, connectionless integrity, an anti-replay service (a form of partial sequence integrity), and limited traffic flow confidentiality.

Examples of the callbackurl command:

Callback URL (1):

customapp://host?status=$STATUS$&login_group=$LOGIN_GROUP&error_code=
$ERROR_CODE$

Corresponding full URL with URL encoded callbackurl value:

mobileconnect://connect?sessionid=<teamid>&callbackurl=customapp%3A%2F%2Fhost
%3Fstatus%3D%24STATUS%24%26login_group%3D%24LOGIN_GROUP%26error_code%3D%24
ERROR_CODE%24

Callback URL (2):

myapp://callback?status=$STATUS$&login_group=$LOGIN_GROUP&error_code=
$ERROR_CODE$

Corresponding full URL with URL encoded callbackurl value:

mobileconnect://connect?sessionid=<teamid>&callbackurl=myapp%3A%2F%2Fcallback
%3Fstatus%3D%24STATUS%24%26login_group%3D%24LOGIN_GROUP%26error_code%3D%24
ERROR_CODE%24

Callback URL (3):

http://server/example%20file.html

Corresponding full URL with URL encoded callbackurl value:

mobileconnect://connect?callbackurl=http%3A%2F%2Fserver%2Fexample%20file.html