Install the AppStream 2.0 Client And Customize the Client Experience for Your Users

The following sections describe how to install the AppStream 2.0 client and customize the client experience for your users. If you plan to download and install the client for your users, first download the Enterprise Deployment Tool. You can then run PowerShell scripts to install the AppStream 2.0 client and configure client settings remotely.

Download the Enterprise Deployment Tool

The Enterprise Deployment Tool includes the AppStream 2.0 client installation files and a Group Policy administrative template.

1. To download the Enterprise Deployment Tool, on the bottom right of the AppStream 2.0 supported clients page, select the Enterprise Deployment Tool link. This link opens a .zip file that contains the required files for the latest version of the tool.

2. To extract the required files, navigate to the location where you downloaded the tool, right-click the AmazonAppStreamClient_EnterpriseSetup_<version> folder, and choose Extract All. The folder contains two installation programs and a Group Policy administrative template:

   • AppStream 2.0 client installer (AmazonAppStreamClientSetup_<version>.msi) — Installs the AppStream 2.0 client.

   • AppStream 2.0 USB driver installer (AmazonAppStreamUsbDriverSetup_<version>.exe) — Installs the AppStream 2.0 USB driver that is required to use USB devices with applications streamed through AppStream 2.0.

   • AppStream 2.0 client Group Policy administrative template (as2_client_config.adm) — Lets you configure the AppStream 2.0 client through Group Policy.

Install the AppStream 2.0 Client and USB Driver

After you download the AppStream 2.0 client installation files, run the following PowerShell script on users' computers to install the AppStream 2.0 client installation file, AppStreamClient.exe, and the USB driver silently.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

Start-Process msiexec.exe -Wait -ArgumentList  '/i AmazonAppStreamClientSetup_<version>.msi /quiet'

Start-Process AmazonAppStreamUsbDriverSetup_<version>.exe -Wait -ArgumentList  '/quiet'

After you install the Enterprise Deployment Tool on a user's computer, the AppStream 2.0 client is installed as follows:

1. The AppStream 2.0 client installation file is copied to the following path on the user's computer: C:\Program Files (x86)\Amazon AppStream 2.0 Client Installer\AppStreamClient.exe.

2. The first time the user logs on to their computer after the Enterprise Deployment Tool is installed, the AppStream 2.0 client is installed.

   Note

   If the Enterprise Deployment Tool detects that the AppStream 2.0 Client folder, AppStreamClient, already exists in %localappdata%, the tool does not install the client.

If a user uninstalls the AppStream 2.0 client, the client isn’t installed again until you update the AppStream 2.0 Enterprise Deployment Tool.

Accessing AppStream 2.0 with the AppStream 2.0 Client

By default, when users launch the AppStream 2.0 client, they can connect only to URLs that include the AppStream 2.0 domain or domains that include a DNS TXT record that enables the connection. You can let client users access domains other than the AppStream 2.0 domain by doing any of the following:

• Set the StartURL registry value to specify a custom URL that users can access, such as the URL for your organization's login portal.

• Set the TrustedDomains registry value to specify trusted domains that users can access.

• Create the AS2TrustedDomains DNS TXT record to specify trusted domains that users can access. This method lets you avoid registry changes.

Note

The AppStream 2.0 client and DNS TXT record configuration do not prevent users from using other connection methods to access the domains or URLs that you specify. For example, users can access specified domains or URLs by using a web browser, if they have network access to the domains or URLs.

Set the StartURL Registry Value for AppStream 2.0 Client Users

You can use the StartUrl registry value to set a custom URL that is populated in the AppStream 2.0 client when a user launches the client. You can create this HKLM registry key while installing the client so that your users don’t need to specify a URL when they launch the client.

After the AppStream 2.0 client is installed, you can run the following PowerShell script to create this registry key, or you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Replace the StartUrl value with a URL for your identity provider (IdP). The URL must use a certificate that is trusted by the device. This means that the certificate that is used by the StartUrl webpage must contain a Subject Alternative Name (SAN) that includes the URL's domain name. For example, if your StartUrl is set to https://appstream.example.com, the SSL certificate must have a SAN that includes appstream.example.com.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force

New-ItemProperty -Path $registryPath -Name "StartUrl" -Value "https://www.example.com" -PropertyType String -Force | Out-Null

Set the TrustedDomains Registry Value to Enable Other Domains for the AppStream 2.0 Client

You can configure the AppStream 2.0 client to connect to URLs in trusted domains that you specify. For example, you might want to let users connect to any URL in your organizational domain or to any URL in one or more of your IdP domains. When you specify the URL, use the following format: *.example-idp.com.

You can specify a list of trusted domains in a comma-separated format. Add this list as a registry value to the AppStream 2.0 TrustedDomains HKLM registry key. We recommend that you create this registry key and specify the list of trusted domains when you install the AppStream 2.0 client or, if you are using Microsoft Active Directory, through Group Policy. That way, your users can connect to a URL in any trusted domain immediately after the client is installed.

After the AppStream 2.0 client is installed, you can run the following PowerShell script to create this registry key. Or, you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Replace the TrustedDomains value with a comma-separated list for one or more of your organizational or IdP domains. The certificate used by the trusted domain webpage must contain a SAN that includes the URL's domain. For example, if your trusted domain includes *.example.com, and users specify https://appstream.example.com, the SSL certificate must have a SAN that includes appstream.example.com.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force

New-ItemProperty -Path $registryPath -Name "TrustedDomains" -Value "*.example1.com, *.example2.com, aws.amazon.com" -PropertyType String -Force | Out-Null

The following are requirements and considerations for formatting trusted domain names.

• The following characters are supported: a-z, 0-9, -, *

• DNS treats the * character either as a wildcard or as an asterisk character (ASCII 42), depending on where it appears in the domain name. Following are restrictions when using * as a wildcard in the name of a DNS record:

  • The * must replace the leftmost label in a domain name. For example, *.example.com or *.prod.example.com. If you include * in any other position, such as prod.*.example.com, DNS treats it as an asterisk character (ASCII 42), not as a wildcard.

  • The * must replace the entire label. For example, you can't specify *prod.example.com or prod*.example.com.

  • The * applies to the subdomain level that includes the *, and to all the subdomains of that subdomain. For example, if an entry is named *.example.com, the AppStream 2.0 client allows zenith.example.com, acme.zenith.example.com, and pinnacle.acme.zenith.example.com.

Create the AS2TrustedDomains DNS TXT Record to Enable Your Domain for the AppStream 2.0 Client Without Registry Changes

You can enable users to connect to any URL in your organizational domain (for example, *.example.com) or to any URL in your IdP domains (for example, *.example-idp.com) by creating a DNS TXT record in that domain. When you create the DNS TXT record, the StartURL or TrustedDomains registry values are not required to allow a user to connect to a URL.

You can specify a list of trusted subdomains in a comma-separated format, prefixed with AS2TrustedDomains=. Then, create a DNS TXT record for the appropriate domain. The AS2TrustedDomains DNS TXT record can only enable the same domain, or subdomains, of the domain in which the DNS TXT record is created. You cannot use the DNS TXT record to enable other domains.

For more information about setting up the DNS record, see Enable your organizational domain for the AppStream 2.0 client with a Route 53 DNS TXT record and Creating an AS2TrustedDomains DNS TXT record to redirect the AppStream 2.0 native client to a third-party identity provider.

Note

When you create DNS TXT records, any users can stream from enabled domains that are not included in the StartURL or TrustedDomains registry values. The AppStream 2.0 client and DNS TXT record configuration do not prevent users from using other connection methods to access the domains or URLs that you specify. For example, users can access specified domains or URLs by using a web browser, if they have network access to the domains or URLs.

DNS TXT Record Configuration Example

The following is an example of a DNS TXT record configuration. With the configuration for this example, users can launch the AppStream 2.0 client and connect to appstream.example.com or appstream-dev.example.com. However, they cannot connect to example.com.

• Domains to enable — appstream.example.com, appstream-dev.example.com

• DNS TXT record location — example.com

• DNS TXT record value — AS2TrustedDomains=appstream.example.com,appstream-dev.example.com

Requirements and Considerations

Keep in mind the following requirements and considerations for creating a DNS TXT record:

• You must create the TXT record at the second-level domain. For example, if your domain is prod.appstream.example.com, you must create the DNS TXT record at example.com.

• The TXT record value must start with AS2TrustedDomains=

• The following characters are supported: a-z, 0-9, -, *

• DNS treats the * character either as a wildcard or as an asterisk character (ASCII 42), depending on where it appears in the domain name. Following are restrictions when using * as a wildcard in the name of a DNS record:

  • The * must replace the leftmost label in a domain name. For example, *.example.com or *.prod.example.com. If you include * in any other position, such as prod.*.example.com, DNS treats it as an asterisk character (ASCII 42), not as a wildcard.

  • The * must replace the entire label. For example, you can't specify *prod.example.com or prod*.example.com.

  • The * applies to the subdomain level that includes the *, and to all the subdomains of that subdomain. For example, if an entry is named *.example.com, the AppStream 2.0 client allows connections to the following domains: zenith.example.com, acme.zenith.example.com, and pinnacle.acme.zenith.example.com.

Disable DNS TXT Record Lookup for Trusted Domains

By default, when users launch the AppStream 2.0 and specify a URL that is not an AppStream 2.0 domain, the client performs a DNS TXT record lookup. The lookup is performed on the second-level domain of the URL so that the client can determine whether the domain is included in the AS2TrustedDomains list. This behavior lets users connect to domains that are not specified in the StartURL or TrustedDomains registry keys, or AppStream 2.0 domains.

You can disable this behavior by setting the value for the DnsTxtRecordQueryDisabled registry key to true. You can create this registry key when you install the AppStream 2.0 client. That way, the client connects only to URLs that are specified by the StartURL or TrustedDomains registry keys.

After the AppStream 2.0 client is installed, you can run the following PowerShell script to create this registry key. Or, you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force
 
New-ItemProperty -Path $registryPath -Name "DnsTxtRecordQueryDisabled" -Value "true" -PropertyType String -Force | Out-Null

Choose Whether to Disable Automatic Client Updates

By default, when a new version of the AppStream 2.0 client is available, the client updates automatically to the latest version. You can disable automatic updates by setting the value for the AutoUpdateDisabled registry key to true. You can create this registry key when you install the AppStream 2.0 client. That way, the client is not updated automatically whenever a new version is available.

After the AppStream 2.0 client is installed, you can run the following PowerShell script to create this registry key. Or, you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force

New-ItemProperty -Path $registryPath -Name "AutoUpdateDisabled" -Value "True" -PropertyType String -Force | Out-Null

Choose Whether to Disable On-Demand Diagnostic Log Uploads

By default, the AppStream 2.0 client allows users to upload diagnostic logs and minidumps on demand to AppStream 2.0 (AWS). In addition, if an exception occurs or the AppStream 2.0 client stops responding, users are prompted to choose whether they want to upload the minidump and associated logs. For more information about on-demand diagnostic logging, see Automatic and On-Demand Diagnostic Log Uploads.

You can disable these behaviors by setting the value for the UserUploadOfClientLogsAllowed registry key to false. You can create this HKLM registry key when you install the AppStream 2.0 client.

After the AppStream 2.0 client is installed, you can run the following PowerShell script to create this registry key. Or, you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force

New-ItemProperty -Path $registryPath -Name "UserUploadOfClientLogsAllowed" -Value "false" -PropertyType String -Force | Out-Null

Choose Whether to Disable Native Application Mode

By default, the AppStream 2.0 client can run in either classic mode or native application mode. You can disable native application mode by setting the value for the NativeAppModeDisabled registry key to true. You can create this HKLM registry key when you install the AppStream 2.0 client. If the value is set to true, the client runs in classic mode only. For information about native application mode, see Native Application Mode.

After the AppStream 2.0 client is installed, you can run the following PowerShell script to create this registry key. Or, you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force

New-ItemProperty -Path $registryPath -Name "NativeAppModeDisabled" -Value "True" -PropertyType String -Force | Out-Null

Choose Whether to Disable Local Printer Redirection

By default, the AppStream 2.0 client enables users to redirect print jobs from their streaming applications to a printer that is connected to their local computer. You can disable local printer redirection by setting the value for the PrinterRedirectionDisabled registry key to true. You can create this HKLM registry key when you install the AppStream 2.0 client. If the value is set to true, the client does not redirect print jobs from users’ streaming applications to a printer that is connected to their local computer.

After you install the AppStream 2.0 client, you can run the following PowerShell script to create this registry key. Or, you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force

New-ItemProperty -Path $registryPath -Name "PrinterRedirectionDisabled" -Value "True" -PropertyType String -Force | Out-Null

Choose Whether to Disable Smart Card Redirection

By default, smart card redirection is enabled for the AppStream 2.0 client. When this feature is enabled, users can use smart card readers that are connected to their local computers and their smart cards during AppStream 2.0 streaming sessions without USB redirection. During AppStream 2.0 streaming sessions, users' smart card readers and smart cards remain accessible for use with local applications. The client redirects the smart card API calls from users’ streaming applications to their local smart card. You can disable smart card redirection by setting the value for the SmartCardRedirectionDisabled registry key to true. You can create this HKLM registry key when you install the AppStream 2.0 client.

If the value is set to true, your users can't use their smart card readers and smart cards during an AppStream 2.0 streaming session without USB redirection. In this case, users can't sign in to their streaming applications by using a smart card that is connected to their local computer unless you qualify the device. After you qualify the device, users must share the device with AppStream 2.0. When smart card redirection is disabled, during users' AppStream 2.0 streaming sessions, their smart card readers and smart cards are not accessible for use with local applications.

After you install the AppStream 2.0 client, you can run the following PowerShell script to create this registry key. Or, you can use the administrative template that is included in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Note

To run this script, you must be logged in to the applicable computer with Administrator permissions. You can also run the script remotely under the System account on startup.

$registryPath="HKLM:\Software\Amazon\AppStream Client"
New-Item -Path "HKLM:\Software\Amazon" -Name "AppStream Client" -Force

New-ItemProperty -Path $registryPath -Name "SmartCardRedirectionDisabled" -Value "True" -PropertyType String -Force | Out-Null

Configure Additional AppStream 2.0 Client Settings for Your Users

The AppStream 2.0 client uses registry keys to configure the following additional client settings:

• AppStream 2.0 client End-User License Agreement (EULA) acceptance

• AppStream 2.0 client EULA version accepted

• Automatic diagnostic log uploads for the AppStream 2.0 client

• Automatic updates for the USB driver that is used to pass USB drivers to AppStream 2.0

• Enabling hardware rendering in the AppStream 2.0 client

• Setting custom folder paths for file system redirection in the AppStream 2.0 client

The following table summarizes the registry values for additional client settings that you can use to customize the AppStream 2.0 client experience for your users.

Note

These values are case sensitive.

Value	Registry path	Type	Description	Data
EULAAccepted	HKCU\Software\Amazon\Appstream Client	String	Set this value to true to accept the AppStream 2.0 client EULA on behalf of your users.	true/false
AcceptedEULAVersion	HKCU\Software\Amazon\Appstream Client	String	The version of EULA that is accepted. If the current version of the AppStream 2.0 client EULA is different from the version of the EULA that is accepted, users are prompted to accept the current version of the EULA.	1.0
DiagnosticInfoCollectionAllowed	HKCU\Software\Amazon\Appstream Client	String	Set this value to true to enable AppStream 2.0 to automatically send diagnostic logs from the AppStream 2.0 client to AppStream 2.0 (AWS).	true/false
USBDriverOptIn	HKCU\Software\Amazon\Appstream Client	String	Set this value to true to enable AppStream 2.0 to automatically update the USB driver that is used to pass USB drivers to AppStream 2.0.	true/false
HardwareRenderingEnabled	HKCU\Software\Amazon\Appstream Client	String	Set this value to true to enable hardware rendering in the AppStream 2.0 client.	true/false
FileRedirectionCustomDefaultFolders	HKCU\Software\Amazon\Appstream Client	String	Set this value to include at least one folder path for file system redirection. Separate multiple folder paths by using '|'. By default, the following folder paths are specified: %USERPROFILE%\Desktop|%USERPROFILE%\Documents|%USERPROFILE%\Downloads	Valid folder path

After the AppStream 2.0 client is installed, you can run the following PowerShell script to create these registry keys. If you don’t want to create all of the registry keys, modify the script as needed to create only the registry keys that you want. Or, you can use the administrative template that is provided in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy.

Note

You must set the following entries for each user.

$registryPath="HKCU:\Software\Amazon\AppStream Client"
New-Item -Path "HKCU:\Software\Amazon" -Name "AppStream Client" -Force
New-ItemProperty -Path $registryPath -Name "EULAAccepted" -Value "true" -PropertyType String -Force | Out-Null
New-ItemProperty -Path $registryPath -Name "AcceptedEULAVersion" -Value "1.0" -PropertyType String -Force | Out-Null
New-ItemProperty -Path $registryPath -Name "DiagnosticInfoCollectionAllowed" -Value "true" -PropertyType String -Force | Out-Null
New-ItemProperty -Path $registryPath -Name "USBDriverOptIn" -Value "true" -PropertyType String -Force | Out-Null
New-ItemProperty -Path $registryPath -Name "HardwareRenderingEnabled" -Value "true" -PropertyType String -Force | Out-Null
New-ItemProperty -Path $registryPath -Name "FileRedirectionCustomDefaultFolders" -Value "%USERPROFILE%\Desktop|%USERPROFILE%\Documents|%USERPROFILE%\Downloads" -PropertyType String -Force | Out-Null

Using Group Policy to Customize AppStream 2.0 Client Experience

You can use the administrative template that is provided in the AppStream 2.0 client Enterprise Deployment Tool to configure the client through Group Policy. To learn how to load administrative templates into the Group Policy Management Console, see Recommendations for managing Group Policy administrative template (.adm) files in the Microsoft Support documentation.