Product Documentation

Installing App Controller

Jan 27, 2014

Citrix App Controller delivers access to web, SaaS, Android, and iOS apps, as well as integrated ShareFile data and documents. Users access their applications through Citrix Receiver, Receiver for Web, or Worx Home.

With App Controller, you can provide the following benefits for each application type:
  • SaaS applications. Active Directory-based user identity creation and management, with SAML-based single sign-on (SSO).
  • Intranet web applications. HTTP form-based SSO by using password storage.
  • iOS and Android apps. Unified store to which you can install MDX apps for iOS and Android devices, and security management for MDX policies, encompassing WorxMail and WorxWeb. You can wrap iOS and Android apps with the MDX Toolkit to create MDX apps.
  • ShareFile access. Delivery of files by configuring ShareFile settings and the ShareFile application that provides seamless SAML SSO, and Active Directory-based ShareFile service user account management.

Getting Ready to Install App Controller

The App Controller virtual machine (VM) runs on Citrix XenServer, Microsoft Hyper-V, or VMware ESXi. You can use XenCenter or vSphere management consoles to install App Controller 2.9.

Before installing App Controller, you must do the following:
  • Install XenServer or VMware ESXi on a computer with adequate hardware resources.
  • Install XenCenter or vSphere on a separate computer. The computer that hosts XenCenter or vSphere connects to XenServer or VMware ESXi host through the network.
  • Install Windows Server 2008 R2 or Windows Server 2012 with Hyper-V enabled, role enabled, on a computer with adequate system resources. While installing the Hyper-V role, be sure to specify the network interface cards (NICs) on the server that Hyper-V will use to create the virtual networks. You can reserve some NICs for the host.
This section details the following steps for installing App Controller on XenServer, Hyper-V, or VMware:
  • Installing the VM on XenServer and setting the properties for App Controller in XenCenter.
  • Installing App Controller on VMware ESXi and using vSphere to allocate virtual hardware components to App Controller, such as memory and virtual CPUs.
  • Installing App Controller on Hyper-V.
  • Configuring the IP address and subnet mask, default gateway, DNS servers, and Network Time Protocol (NTP) servers for App Controller by using the XenCenter or vSphere command-line console.

When you finish configuring App Controller network settings by using the command-line console, you log on to the App Controller management console. Then, you configure the following network settings:

  • Active Directory configuration from which you obtain groups for App Controller
    Note: After you complete the Configure wizard, you can configure settings for additional Active Directory servers in your network.
  • Administrator settings
  • Workflow email settings

Optionally, you can change the settings you configured by using the command-line console in the wizard. These settings include:

  • App Controller system settings, such as IP address, subnet mask, and the default gateway
  • NTP and DNS server settings and the time zone

After you configure App Controller system settings, to complete the configuration, App Controller retrieves the groups and members of the groups from the specified Base DN in Active Directory. When the retrieval is complete, App Controller logs off. You can log on again to continue configuring App Controller features.

Installing App Controller on XenServer

After you download the virtual image (VM) from the Citrix web site, install App Controller on XenServer. After installation, set the properties for App Controller in XenCenter.

To install App Controller on XenServer

  1. Start XenCenter on your computer.
  2. In the navigation pane, click the name of the XenServer on which you want to install App Controller and then connect.
  3. On the File menu, click Import.
  4. In the Import wizard, in Filename, browse to the location to which you saved the .xva image file and then click Open.
  5. Follow the instructions in the wizard to import the App Controller image.

After you click Finish in the wizard, you can click the Logs tab to view the status of the import process. When the import process is complete, you configure the initial settings for App Controller by using the command-line console. For more information, see Setting the App Controller IP Address for the First Time.

To set the properties for App Controller

When you import App Controller, the number of virtual CPUs (VCPUs) is set to 2. You cannot change this setting. The default memory setting is 4096. You can leave the memory setting or change it by using the Memory tab in XenCenter.

Note: If the App Controller virtual machine acts as the cluster head, configure 4 VCPUs.

Installing App Controller by Using VMware ESXi

To install App Controller on VMware ESXi, you must first install VMware on a computer with adequate hardware resources. To perform the App Controller installation, you use vSphere. You install vSphere on a remote computer that can connect to the VMware host through the network. After you install App Controller, you can create virtual hardware components on VMware and then use vSphere to allocate them to App Controller.

When you install App Controller on VMware ESXi, you use the vSphere client. You select the OVF template to start the Deploy OVF Wizard. Follow the directions in the wizard to import the App Controller OVA (.ova) file. You provide a name for App Controller and then configure additional settings to import the file to VMware ESXi.

After the import is complete, you set the App Controller properties in vSphere. These settings include:

  • Allow the virtual machine to start and stop automatically with the system.
  • Set the startup order for App Controller.
  • Set the memory size to 4096.
  • Set the number of VCPUs to 2.

For more information about VMware ESXi and the vSphere client, see the manufacturer's documentation.

Installing App Controller on Microsoft Hyper-V

To install App Controller on Microsoft Hyper-V, you must first install Microsoft Server 2012 with Hyper-V enabled or Microsoft Hyper-V Server 2012 on a computer with adequate hardware resources. To perform the App Controller installation, you use the Hyper-V Manager, which is a Microsoft Management Console (MMC) snap-in. Hyper-V Manager is installed automatically when you enable the Hyper-V role.

You download a compressed ZIP file to install App Controller on Microsoft Hyper-V. You extract the files and then use Hyper-V Manager to install App Controller.

Note: Make sure that you extract the files in the ZIP folder into a different folder before you specify the path to the folder.

After you import the virtual machine, you need to configure the virtual network adapter by associating the adapter to the virtual networks created by Hyper-V. App Controller 2.8 requires one virtual network adapter.

In Hyper-V Manager, you select the server on which you want to install App Controller and then import the virtual machine. When the import starts, you are prompted to specify the path of the folder that contains the App Controller software files.

After the import is complete, you set the App Controller properties in Hyper-V Manager. These settings include:

  • Allow the virtual machine to start and stop automatically with the system.
  • Set the startup order for App Controller.
  • Set the memory size to 4096.
  • Set the number of VCPUs to 2.

For more information about Microsoft Hyper-V and the Hyper-V Manager, see the manufacturer's documentation.

Setting the App Controller IP Address for the First Time

After importing the App Controller image, you need to configure the IP address. The IP address is the management address at which you can access App Controller through a web browser or by using a Secure Shell (SSH) client, such as PuTTY. You can access the App Controller command-line interface through the XenCenter console to specify an IP address, subnet mask, default gateway, Domain Name Servers (DNS) and a Network Time Protocol (NTP) server. The default IP address for App Controller is 10.20.30.40.

To change the IP address for App Controller in XenCenter

  1. In XenCenter, select the App Controller virtual machine and then click the Console tab.
  2. At the console logon prompt, enter the administrator credentials.

    The default user name for the console is admin and the default password is password.

  3. At a command prompt, type 0 to select Express Setup.
  4. Select the appropriate number to change the IP address, subnet mask, default gateway, DNS servers, and NTP server.
    Note: Citrix recommends using an NTP server to set the date and time on App Controller.
  5. Press 5 to commit the changes.

When you commit the changes, you are prompted to restart App Controller. Review your settings and then type y to commit the changes. After App Controller restarts, you can then access the management console by using the new IP address in a web browser. To open the management console, type https://App ControllerIPaddress:4443/ControlPoint in the address bar of the web browser. For example, type https:// 10.20.30.40:4443/ControlPoint. The user name is administrator and the password is password.

When you connect to App Controller, you must use HTTPS. If you attempt to connect with HTTP, the connection fails.

Configuring App Controller for the First Time

After you install the App Controller virtual machine (VM) and configure the initial settings by using the command-line console, you can configure additional App Controller network settings in the App Controller management console. To open the management console, type https://AppControllerIPaddress:4443/ControlPoint in the address bar of the web browser. For example, type https://10.20.30.40:4443/ControlPoint. The user name is administrator and the password is password. When you log on to the management console for the first time, the Configure wizard appears prompting you to configure settings that include the following:

  • Administrator password
    Note: Make sure that the email address is part of the base DN that you configure in the Active Directory settings.
  • App Controller host name, IP address, subnet mask, and default gateway
    Note: You can also configure an IP address for App Controller if you want a different IP address than what you configured by using the command-line console.
  • Active Directory settings to one server
  • Certificates
    Note: In the Configure wizard, you can add, create, or remove certificates on the Active Directory page. The option to configure certificates from the Active Directory page only appears when you configure App Controller for the first time in the management console. After you run the Configure wizard for the first time, you can then manage certificates from the Settings tab in the management console.
  • Network Time Protocol (NTP) server and time zone
  • DNS server settings
  • Workflow email settings
    Important: For workflows to work correctly, when you add users to Active Directory, you must enter the first name, last name, and email in the user properties. If you do not configure users in Active Directory with this information, App Controller cannot synchronize these individuals. When users attempt to start an app, users receive a message that they are not authorized to use the app.

After you configure and save the remaining network settings in the management console, App Controller retrieves users from Active Directory and then logs off. If you changed the password, log on again with the new password.

Important: If you have a large number of users or groups, it might take a few hours for App Controller to retrieve users. You cannot make any changes to App Controller until this process is complete. If you close the browser, interrupt the synchronization and then restart the Configure wizard in another web browser, your settings are not saved. Citrix recommends that you allow the Active Directory synchronization to complete. When you configure the App Controller settings for the first time, you can enter a group domain name (DN) that speeds the synchronization of Active Directory membership with App Controller.

If you need to make changes to system settings at a later time, you can access the Settings tab. You can configure or reconfigure the following on the Settings tab:

  • Active Directory settings, such as IP address, administrator email and password, and base DN
  • Administrator settings that allows you to change the password for the management console and the command line console
  • Support options that allows you to configure GoToAssist user assistance settings.
  • Branding that allows you to upload your own Portable Network Graphics (png) to mobile devices
  • Certificates where you can install root, intermediate, and server certificates on App Controller
  • Deployment settings for StoreFront or NetScaler Gateway
  • Domain Name Server such as a DNS or WINS server
  • GoToAssist settings for email or phone support
  • Log transfer that sends logs to a server in your network
  • Network connectivity that are the App Controller network settings
  • NTP server that contains the settings for a Network Time Protocol server
  • Receiver email template where you can send emails to your users to download Receiver
  • Receiver updates
  • Release management that allows you to upload software upgrades, patches, and application connectors
  • Store credentials where you can save the user name, password, and device ID for the Google Play Store
  • SysLog server settings
  • Workflow email which is the administrator email settings for workflows
  • XenMobile MDM where you configure connection settings to XenMobile Device Manager

To change App Controller settings

  1. In the App Controller management console, click Settings at the top of the page.
  2. In the left pane, under System Configuration, click one of the options to configure the settings.

After you complete App Controller configuration, you can configure roles, users, applications, and application categories for single sign-on (SSO). You can do the following:

  • Refresh users from Active Directory.
  • Add roles to map which Active Directory groups receive access to applications.
  • Add web and SaaS applications to App Controller from the provided connector catalog.
  • Upload mobile apps to App Controller.
  • View a user device inventory in which you can erase and stop erasing application data and documents from a device, lock and unlock a device, or delete a device from the inventory.
  • Retrieve mobile app information by configuring mobile links.
  • Add links to commonly used web sites including Internet and intranet sites.
  • Create access to applications that are not in the catalog for SSO by using either HTTP Federated Formfill or SAML connectors.
  • Download certificates for use with some SAML applications.
  • Create user accounts automatically based on Active Directory group membership.
  • Assign users to applications based on their role within the organization.
  • Add categories to which you can add applications.
  • Connect StoreFront to App Controller. When users connect with Citrix Receiver, they can see the application list, subscribe to applications, and access applications seamlessly.
  • Configure ShareFile settings for user data and documents.

Icons in the AppController Management Console

The AppController management console includes icons that users click to perform different tasks. The following table defines each icon.
Icon Icon Name Definition
Click to enable app.

Enable

Indicates that an app is disabled. When clicked, enables the app.

Click to disable app.

Disable

Indicates that an app is enabled. When clicked, disables the app.

Edit app.

Edit

Used to edit a role or application.

Delete app.

Remove

Used to remove an application, remove an application from a role, or to remove a category, workflow, or user device.

Sync app.

Sync

Used to synchronize application users with Active Directory for accounts that are configured for user account management. Also opens a Storage Zone dialog box in Roles to enable you to find a particular storage zone and provide credentials.

Upgrade app

Upgrade

Used to upgrade a mobile application with a new version.

Details icon.

Role details

In Roles, you can view the Active Directory groups that belong to a configured role or you can delete the role.

Lock a user device.

Lock

Used to lock a user device.

Unlock user device.

Unlock

Used to unlock a user device after you have locked it.

Wipe a user device.

Erase

Used to erase data and documents from a device.

Restore data and docs.

Stop erasing

Used to stop the process of erasing data and documents from the device.

Apps associated with workflow

Apps

In Workflows, shows the apps with which the workflow is associated, if any.

Workflow details

Workflow details

In Workflows, lets you view the levels of manager approval and additional approvers for a configured workflow.

User icon

User

In Roles, lets you view members of the Active Directory groups.

Adding Active Directory Domains to App Controller

App Controller uses Active Directory groups and users. You configure Active Directory in two ways:

  • With the Configure wizard when you log on to the App Controller management console for the first time. This domain is considered the default domain.
  • On the Settings tab where you can configure multiple Active Directory domains.

With Active Directory, you can:

  • Create roles in App Controller that map to one or more Active Directory groups within multiple domains.
  • Create and remove user application accounts based on their Active Directory group membership by using applications assigned to roles.
  • Create workflows for manager approval of user accounts for applications.
Important: When you add users to Active Directory, you must enter the first name and last name in the user properties. If you do not configure users in Active Directory with this information, App Controller cannot synchronize these individuals. When users attempt to start an app, users receive a message that they are not authorized to use the app. The administrator account must be recognized by all corresponding Active Directory domains you configure in App Controller.

When App Controller synchronizes with Active Directory, either after the first time you configure Active Directory in App Controller or if you manually synchronize with Active Directory, the length of time it takes to synchronize depends on the size of Active Directory. If you have a large number of users and groups, this process can take a few hours. During this time, you cannot configure any other settings in Active Directory. If you enter a group DN when you first configure Active Directory, the synchronization occurs more quickly. For example, you enter cn=Users,dc=servername,dc=net, where cn=users is the group base DN and servername is the name of the Active Directory server. When the initial synchronization is finished, App Controller logs off from the management console and returns to the management console logon page.

Note: If you provide the root level base DN, such as dc=mycompany,dc=com, App Controller retrieves users in child domains. To prevent retrieval of child domain users, provide specific user base DN paths that relate to the parent domain.

Configuring Multiple Active Directory Domains

After you configure one Active Directory domain by using the Configure wizard, you can add additional Active Directory domains on the Settings > Active Directory tab in the App Controller management console.

When you configure Active Directory domains, you provide the server information including:

  • IP address
  • Port
  • Domain name
  • Service account
  • Password
  • User base DN
  • Group base DN
  • SSL support

You can configure Active Directory domains in the following ways:

  • One Active Directory instance per domain. You can specify multiple base DNs in each domain. Separate each base DN with a semi-colon (;).
  • Two domains that belong to different Windows Server trees.
  • Two domains that belong to different Windows Server forests.

For each domain, the service account you specify must be able to access the base DN for each domain. App Controller does not maintain any internal relationship between managed domains. You can manage multiple Active Directory domains as separate instances. When you configure multiple Active Directory domains, Citrix recommends that you use the User Principal Name (UPN) so you can include the domain name.

If you configure multiple domains, keep the following in mind:

  • Default domain users only can log on directly to App Controller.
  • Log on from users in other domains must be authenticated by NetScaler Gateway.
  • Domains configured in App Controller and NetScaler Gateway must match.
  • Domains configured in App Controller and StoreFront must match when StoreFront is used as the authentication server.

If StoreFront is used as the authentication server, the domain information must be included in the token validation response from StoreFront. You can use sAMAccount (domain\user name) or UPN (user@domain) for user logon.

Modifying and Deleting Active Directory Domains

You can modify and delete Active Directory domains in App Controller. App Controller retrieves users and groups when you add each domain. If you modify a domain, if you change the user or group base DN, App Controller synchronizes with Active Directory.

You can delete one domain at a time and you cannot delete the default domain. When you delete a domain, App Controller marks all of the users in the domain as terminated users. These users lose access to role-based apps. App Controller also deletes pending workflows and provisioning requests. User accounts reconciled to terminated users are processed according to the app configuration (ignore, disable, or delete).

Important: If you delete a domain, you cannot add the same domain to App Controller again.

Adding and Synchronizing Active Directory Domains

You can add multiple Active Directory domains to App Controller. After you add a domain, click the Sync icon to retrieve users and groups from the Active Directory domain.

To add Active Directory domains

  1. In the App Controller management console, click Settings at the top of the page.
  2. In the left pane, under System Configuration, click Active Directory.
  3. In the details pane, click Add.
  4. In Server and Port, enter the IP address and port number of the Active Directory server. The default port number is 389.
  5. In Domain name, add the Active Directory domain, such as mycompany.net. When you add the domain name, User Base DN and Group Base DN populate automatically.
  6. In User Base DN and Group Base DN enter any other parameters, such as cn=Users.

    A warning appears if the base DN is a top-level domain.

  7. In Service Account, add the email address of the administrator account. You can use either the sAMAccountName, in which users log on with domain\user, or the User Principal Name (UPN) in which users log on with user@mycompany.com.
    Note: All Active Directory domains that you add to App Controller must recognize this service account.
  8. Password and Confirm Password enter the password of the service account and then click Save.
When you configure settings and only configure the top-level domain, the Add Domain dialog box appears as in the following figure:

Adding an Active Directory Domain

To remove the warning message, configure a subdomain as part of the base DN. For example, enter cn=Users, dc=mycompany,dc=net.

To manually synchronize with Active Directory

App Controller supports the following three types of Active Directory synchronization:

  • Initial synchronization. When you log on to the management console for the first time, you configure Active Directory settings in the initial wizard along with network and email settings. When you save the settings, App Controller synchronizes with Active Directory.
  • Periodic synchronization. App Controller contacts Active Directory every five minutes to determine if there are any changes in Active Directory. App Controller looks for added, removed, and modified users in Active Directory. App Controller also looks for group membership changes and new and removed groups. This periodic synchronization starts for domains that have previously retrieved users and groups. The earlier synchronization must successful for the periodic synchronization to run.
  • Manual synchronization. You can synchronize with Active Directory at any time by using the synchronize icon next to the Active Directory domain in the App Controller management console. When you synchronize, App Controller updates all users from Active Directory for that domain and determines any changes to the user records. This synchronization can take as long as the initial synchronization and depends on the size of Active Directory. This synchronization also returns changes to users, including group membership. You can start synchronization for all managed domains. The App Controller synchronization process runs in the background, one domain after another. When you manually synchronize, App Controller displays a progress bar so you can track the progress.
  1. In the App Controller management console, click Settings at the top of the page.
  2. In the left pane, under System Configuration, click Active Directory.
  3. In the details pane, under Actions, click the Sync icon for the domain with which you want to synchronize.