# Use and manage WorkSpaces Personal
<a name="managing-wsp-personal"></a>

WorkSpaces Personal offers persistent virtual desktops that are tailored for users who need a highly-personalized desktop provisioned for their exclusive use, similar to a physical desktop computer assigned to an individual.

Each WorkSpace is associated with a virtual private cloud (VPC), and a directory to store and manage information for your WorkSpaces and users. For more information, see [Configure a VPC for WorkSpaces Personal](amazon-workspaces-vpc.md). Directories are either managed by the WorkSpaces service, or through the Directory Service, which offers the following options: Simple AD, AD Connector, or AWS Directory Service for Microsoft Active Directory, also known as AWS Managed Microsoft AD. For more information, see the [AWS Directory Service Administration Guide](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/).

WorkSpaces uses your IAM Identity Center (for directories managed by Amazon WorkSpaces), Simple AD, AD Connector, or AWS Managed Microsoft AD directory to authenticate users. Users access their WorkSpaces by using a client application from a supported device or, for Windows WorkSpaces, a web browser, and they log in by using their directory credentials. The login information is sent to an authentication gateway, which forwards the traffic to the directory for the WorkSpace. After the user is authenticated, streaming traffic is initiated through the streaming gateway.

Client applications use HTTPS over port 443 for all authentication and session-related information. Client applications use port 4172 (PCoIP) and port 4195 (DCV) for pixel streaming to the WorkSpace and ports 4172 and 4195 for network health checks. For more information, see [Ports for client applications](workspaces-port-requirements.md#client-application-ports).

Each WorkSpace has two elastic network interfaces associated with it: a network interface for management and streaming (eth0) and a primary network interface (eth1). The primary network interface has an IP address provided by your VPC, from the same subnets used by the directory. This ensures that traffic from your WorkSpace can easily reach the directory. Access to resources in the VPC is controlled by the security groups assigned to the primary network interface. For more information, see [Network interfaces](workspaces-port-requirements.md#network-interfaces).

The following diagram shows the architecture of WorkSpaces that use AD Connector.

![\[WorkSpaces architecture diagram showing user connections, gateways, and AWS services integration.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/architectural-diagram-new-2.png)


# What is Amazon WorkSpaces Advisor?
<a name="workspaces-advisor"></a>

Amazon WorkSpaces Advisor is an AI-powered feature that helps you identify and resolve issues impacting your WorkSpaces Personal resources. WorkSpaces Advisor reviews telemetry, knowledge bases, and best practices to surface issues with recommended remediation actions — directly in the Amazon WorkSpaces console.

With WorkSpaces Advisor, you can:
+ Investigate a WorkSpace and receive a list of identified issues
+ Review supporting telemetry data, including Amazon CloudWatch metrics, for each issue
+ Take recommended remediation actions
+ Chat with WorkSpaces Advisor for follow-up questions through Amazon Q Developer
+ Create a support case pre-populated with investigation context

WorkSpaces Advisor is available in all AWS Regions that support Amazon WorkSpaces Personal at no additional cost.

**Topics**
+ [How investigations work](#workspaces-advisor-how-it-works)
+ [Investigate a WorkSpace](#workspaces-advisor-investigate)
+ [Required permissions](#workspaces-advisor-permissions)
+ [Cross-Region Inference](#workspaces-advisor-cross-region-inference)
+ [Opting out of using your data for service improvement](#workspaces-advisor-opt-out)

## How investigations work
<a name="workspaces-advisor-how-it-works"></a>

When you initiate an investigation, WorkSpaces Advisor deploys AI agents to analyze data from the selected WorkSpace over the past 3 days. The analysis typically completes in under 60 seconds.

WorkSpaces Advisor returns a list of identified issues ordered by severity. For each issue, WorkSpaces Advisor provides at least one recommended action along with alternatives. Each action includes a severity level (Critical, High, Medium, or Low) and describes the risk and impact to your resources.

If WorkSpaces Advisor does not identify your issue, you can provide feedback through the console or create a support case with AWS Support.

### Investigation limits
<a name="workspaces-advisor-limits"></a>
+ You can investigate one WorkSpace at a time.

### Issue severity levels
<a name="workspaces-advisor-severity"></a>

WorkSpaces Advisor categorizes issues by the following severity levels (for example):
+ **Critical** — The user cannot connect to the WorkSpace or the WorkSpace is unresponsive.
+ **High** — The user experience is significantly degraded (for example, high latency or frequent disconnections).
+ **Medium** — The WorkSpace is functional but performance is below optimal levels (for example, elevated CPU or memory usage).
+ **Low** — A potential issue or configuration gap that may not currently affect the user.

### Data accessed by WorkSpaces Advisor
<a name="workspaces-advisor-data"></a>

WorkSpaces Advisor accesses the following data to perform investigations:
+ [Amazon CloudWatch metrics](https://docs.aws.amazon.com/workspaces/latest/adminguide/cloudwatch-metrics.html) (for example, CPU usage, memory usage, and disk usage)
+ WorkSpaces resource configuration (WorkSpace ID, VPC, subnet, bundle type)
+ Service telemetry
+ Application names running on the WorkSpace, including their CPU and memory usage
+ AWS documentation and knowledge bases

## Investigate a WorkSpace
<a name="workspaces-advisor-investigate"></a>

1. Open the [Amazon WorkSpaces console](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**, then **Personal**.

1. Select the WorkSpace that you want to investigate.

1. Choose **Investigate**.

1. Review the list of identified issues. Choose an issue to view details, including supporting telemetry and recommended actions.

1. Review the risk and impact information for the recommended action, then choose the action to initiate it.

### Get additional help with Amazon Q Developer
<a name="workspaces-advisor-additional-help"></a>
+ **Chat with WorkSpaces Advisor** — Choose **Chat with WorkSpaces Advisor** on the issue details page to ask follow-up questions through AWS Console chat. The chat session automatically includes the full context of the issue.
+ **Create a support case** — Choose **Create support case** to contact AWS Support. The support case is pre-populated with the investigation context.
+ In both cases you will need [permissions to use Amazon Q Developer](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/security_iam_permissions.html) in the console. For more information about using Amazon Q Developer, see [Chatting with Amazon Q Developer about AWS](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/chat-with-q.html).

## Required permissions
<a name="workspaces-advisor-permissions"></a>

WorkSpaces Advisor uses [Forward access sessions (FAS)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html) to perform actions using your IAM identity and permissions.

### Permissions for investigations
<a name="workspaces-advisor-permissions-read"></a>

Your IAM role must have the following [permissions for WorkSpaces Advisor](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonworkspaces.html) to initiate investigations and retrieve recommendations. These include `workspaces:InvokeTroubleshootingInvestigation`, `workspaces:GetTroubleshootingRecommendation`, and `workspaces:ListTroubleshootingRecommendations`.

Your IAM role must have read permissions for WorkSpaces and Amazon CloudWatch APIs, such as `workspaces:DescribeWorkSpaces` and `cloudwatch:GetMetricData`. If your role is missing permissions for specific checks, WorkSpaces Advisor skips those checks and displays a message so you can update your permissions.

### Permissions for remediation actions
<a name="workspaces-advisor-permissions-write"></a>

Your IAM role must have permission to perform the specific action (for example, `workspaces:RebootWorkSpaces` or `workspaces:ModifyWorkSpaceProperties`). If your role does not have the required permission, WorkSpaces Advisor returns an error.

## Cross-Region Inference
<a name="workspaces-advisor-cross-region-inference"></a>

Model inference is the process of a model generating an output (response) from a given input (prompt). To use an optimal model for each feature, WorkSpaces Advisor may use [cross-region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) for data processing. This means WorkSpaces Advisor will automatically select the optimal AWS Region to process inference requests. The available AWS Regions vary based on the region of your WorkSpaces resource. All data is transmitted encrypted across Amazon's secure network and does not traverse the public internet.

The following table lists the inference regions that WorkSpaces Advisor may use:


| Amazon WorkSpaces resource Region | Inference Regions | 
| --- | --- | 
| US East (N. Virginia) (us-east-1) US East (Ohio) (us-east-2) US West (Oregon) (us-west-2) | US East (N. Virginia) (us-east-1) US East (Ohio) (us-east-2) US West (Oregon) (us-west-2) | 
| Africa (Cape Town) (af-south-1) | Africa (Cape Town) (af-south-1) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| Asia Pacific (Malaysia) (ap-southeast-5) | Asia Pacific (Malaysia) (ap-southeast-5) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| Asia Pacific (Mumbai) (ap-south-1) | Asia Pacific (Mumbai) (ap-south-1) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| Asia Pacific (Seoul) (ap-northeast-2) | Asia Pacific (Seoul) (ap-northeast-2) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| Asia Pacific (Singapore) (ap-southeast-1) | Asia Pacific (Singapore) (ap-southeast-1) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| Asia Pacific (Sydney) (ap-southeast-2) | Asia Pacific (Sydney) (ap-southeast-2) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| Asia Pacific (Tokyo) (ap-northeast-1) | Asia Pacific (Tokyo) (ap-northeast-1) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| Canada (Central) (ca-central-1) | Canada (Central) (ca-central-1) US East (N. Virginia) (us-east-1) US East (Ohio) (us-east-2) US West (Oregon) (us-west-2) | 
| Europe (Frankfurt) (eu-central-1) Europe (Ireland) (eu-west-1) Europe (Paris) (eu-west-3) | Europe (Frankfurt) (eu-central-1) Europe (Ireland) (eu-west-1) Europe (Milan) (eu-south-1) Europe (Paris) (eu-west-3) Europe (Spain) (eu-south-2) Europe (Stockholm) (eu-north-1) | 
| Europe (London) (eu-west-2) | Europe (London) (eu-west-2) Europe (Frankfurt) (eu-central-1) Europe (Ireland) (eu-west-1) Europe (Milan) (eu-south-1) Europe (Paris) (eu-west-3) Europe (Spain) (eu-south-2) Europe (Stockholm) (eu-north-1) | 
| Israel (Tel Aviv) (il-central-1) | Israel (Tel Aviv) (il-central-1) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 
| South America (Sao Paulo) (sa-east-1) | South America (Sao Paulo) (sa-east-1) [Commercial AWS Regions](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions) | 

## Opting out of using your data for service improvement
<a name="workspaces-advisor-opt-out"></a>

You can choose to opt out of having your data used to develop and improve WorkSpaces Advisor and its underlying technology by using the AWS Organizations opt-out policy. You can choose to opt out even if WorkSpaces Advisor doesn't currently collect any such data. For more information about how to opt out, see [AI services opt-out policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html) in the *AWS Organizations User Guide*.

**Note**  
For you to use the opt-out policy, your AWS accounts must be centrally managed by AWS Organizations. If you haven't already created an organization for your AWS accounts, see [Creating and managing an organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org.html) in the *AWS Organizations User Guide*.

Opting out has the following effects:
+ WorkSpaces Advisor will delete the data that it collected and stored for service improvement purposes prior to your opt out (if any).
+ After you opt out, WorkSpaces Advisor will no longer collect or store this data for service improvement purposes.

# Options for creating a WorkSpace with WorkSpaces Personal
<a name="how-to-start"></a>

There are several methods to create a WorkSpace. You can use the quick setup instructions, the advanced setup instructions, or choose from the following options:
+ [Create an AWS Managed Microsoft AD directory for WorkSpaces Personal](launch-workspace-microsoft-ad.md)
+ [Create a Simple AD directory for WorkSpaces Personal](launch-workspace-simple-ad.md)
+ [Create an AD Connector for WorkSpaces Personal](launch-workspace-ad-connector.md)
+ [Create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain for WorkSpaces Personal](launch-workspace-trusted-domain.md)
+ [Create a dedicated Microsoft Entra ID directory with WorkSpaces Personal](launch-entra-id.md)
+ [Create a dedicated Custom directory with WorkSpaces Personal](launch-custom.md)

## Get started with WorkSpaces Personal
<a name="getting-started"></a>

As a first-time WorkSpaces user, you can choose to set up your WorkSpaces Personal with quick setup or advanced setup. The following tutorials describe how to provision a cloud-based desktop, known as a *WorkSpace* using WorkSpaces and Directory Service. 

**Note**  
To get started with WorkSpaces Pools, see [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md).

### WorkSpaces Personal quick setup
<a name="getting-started-quick-setup"></a>

In this tutorial, you learn how to provision a virtual, cloud-based Microsoft Windows, Amazon Linux 2, Ubuntu Linux, Rocky Linux, or Red Hat Enterprise Linux desktop, known as a *WorkSpace*, by using WorkSpaces and Directory Service.

This tutorial uses the quick setup option to launch your WorkSpace. This option is available only if you have never launched a WorkSpace. Alternatively, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

**Note**  
This quick setup option and tutorial does not apply to WorkSpaces Pools.

**Note**  
Quick setup is supported in the following AWS Regions:   
US East (N. Virginia)
US West (Oregon)
Europe (Ireland)
Asia Pacific (Singapore)
Asia Pacific (Sydney)
Asia Pacific (Tokyo)
To change your Region, see [Choosing a Region](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/select-region.html).

**Topics**
+ [Before you begin](#quick-setup-prereqs)
+ [What quick setup does](#quick-setup-what-it-does)
+ [Step 1: Launch the WorkSpace](#quick-setup-launch-workspace)
+ [Step 2: Connect to the WorkSpace](#quick-setup-connect-workspace)
+ [Step 3: Clean up (Optional)](#quick-setup-clean-up)
+ [Next steps](#quick-setup-next-steps)

#### Before you begin
<a name="quick-setup-prereqs"></a>

Before you begin, make sure that you meet the following requirements:
+ You must have an AWS account to create or administer a WorkSpace. Users do not need an AWS account to connect to and use their WorkSpaces.
+ WorkSpaces is not available in every Region. Verify the supported Regions and [ select a Region](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/getting-started.html#select-region) for your WorkSpaces. For more information about the supported Regions, see [WorkSpaces Pricing by AWS Region](https://aws.amazon.com/workspaces/pricing/#Amazon_WorkSpaces_Pricing_by_AWS_Region).

It's also helpful to review and understand the following before you proceed:
+ When you launch a WorkSpace, you must select a WorkSpace bundle. For more information, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles) and [Amazon WorkSpaces Pricing](https://aws.amazon.com/workspaces/pricing/).
+ When you launch a WorkSpace, you must select which protocol (PCoIP or DCV) you want to use with your bundle. For more information, see [Protocols for WorkSpaces Personal](amazon-workspaces-networking.md#amazon-workspaces-protocols).
+ When you launch a WorkSpace, you must specify profile information for the user, including a user name and email address. Users complete their profiles by specifying a password. Information about WorkSpaces and users is stored in a directory. For more information, see [Manage directories for WorkSpaces Personal](manage-workspaces-directory.md).

#### What quick setup does
<a name="quick-setup-what-it-does"></a>

Quick setup completes the following tasks on your behalf:
+ **Creates an IAM role** to allow the WorkSpaces service to create elastic network interfaces and list your WorkSpaces directories. This role has the name `workspaces_DefaultRole`.
+ **Creates a virtual private cloud (VPC)**. If you want to use an existing VPC instead, make sure it meets the requirements noted in [Configure a VPC for WorkSpaces Personal](amazon-workspaces-vpc.md), and then follow the steps in one of the tutorials listed in [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md). Choose the tutorial that corresponds to the type of Active Directory that you want to use.
+ **Sets up a Simple AD directory** in the VPC and enables it for WorkDocs. This Simple AD directory is used to store user and WorkSpace information. The first AWS account created by quick setup is your admin AWS account. † The directory also has an Administrator account. For more information, see [What gets created](https://docs.aws.amazon.com/) in the *AWS Directory Service Administration Guide*.
+ **Creates the specified AWS accounts and adds them to the directory**.
+ **Creates WorkSpaces**. Each WorkSpace receives a public IP address to provide internet access. The running mode is AlwaysOn. For more information, see [Manage the running mode in WorkSpaces Personal](running-mode.md).
+ **Sends invitation emails to the specified users**. If your users don't receive their invitation emails, see [Send an invitation email](manage-workspaces-users.md#send-invitation). 

† The first AWS account created by quick setup is your admin AWS account. You can't update this AWS account from the WorkSpaces Console. Don't share the information for this account with anyone else. To invite other users to use WorkSpaces, create new AWS accounts for them.

#### Step 1: Launch the WorkSpace
<a name="quick-setup-launch-workspace"></a>

Using quick setup, you can launch your first WorkSpace in minutes.

**To launch a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. Choose **Quick setup**. If you don't see this button, either you have already launched a WorkSpace in this Region, or you aren't using one of the [Regions that support quick setup](#quick-setup-regions). In this case, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).   
![\[Amazon WorkSpaces dashboard showing service description and setup options.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/quick-setup.png)

1. For **Identify users**, enter the **Username**, **First Name**. **Last Name**, and **Email**. Then choose **Next**.
**Note**  
If this is your first time using WorkSpaces, we recommend creating a user for yourself for testing purposes.  
![\[User creation form for WorkSpaces with fields for username, first name, last name, and email.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/identify-users.png)

1. For **Bundles**, select a bundle (hardware and software) for the user with the appropriate protocol (PCoIP or DCV). For more information about the various public bundles available for Amazon WorkSpaces, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles).  
![\[WorkSpaces bundle selection interface showing various Amazon Linux and Windows options with storage specifications.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/select-bundle.png)

1. Review your information. Then choose **Create WorkSpace**.

1. It takes approximately 20 minutes for your WorkSpace to launch. To monitor the progress, go to the left navigation pane and choose **Directories**. You will see a directory being created with an initial status of `REQUESTED` and then `CREATING`. 

   After the directory has been created and has a status of `ACTIVE`, you can choose **WorkSpaces** in the left navigation pane to monitor the progress of the WorkSpace launch process. The initial status of the WorkSpace is `PENDING`. When the launch is complete, the status is `AVAILABLE` and an invitation is sent to the email address that you specified for each user. If your users don't receive their invitation emails, see [Send an invitation email](manage-workspaces-users.md#send-invitation).

#### Step 2: Connect to the WorkSpace
<a name="quick-setup-connect-workspace"></a>

After you receive the invitation email, you can connect to the WorkSpace using the client of your choice. After you sign in, the client displays the WorkSpace desktop.

**To connect to the WorkSpace**

1. If you haven't set up credentials for the user already, open the link in the invitation email and follow the directions. Remember the password that you specify as you will need it to connect to your WorkSpace.
**Note**  
Passwords are case-sensitive and must be between 8 and 64 characters in length, inclusive. Passwords must contain at least one character from each of the following categories: lowercase letters (a-z), uppercase letters (A-Z), numbers (0-9), and the set \$1\$1@\$1\$1%^&\$1\$1-\$1=`\$1\$1()\$1\$1[]:;"'<>,.?/.

1. Review [WorkSpaces Clients](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-clients.html) in the *Amazon WorkSpaces User Guide* for more information about the requirements for each client, and then do one of the following: 
   + When prompted, download one of the client applications or launch **Web Access**.
   + If you aren't prompted and you haven't installed a client application already, open [https://clients.amazonworkspaces.com/](https://clients.amazonworkspaces.com/) and download one of the client applications or launch **Web Access**.
**Note**  
You cannot use a web browser (Web Access) to connect to Amazon Linux WorkSpaces.

1. Start the client, enter the registration code from the invitation email, and choose **Register**.

1. When prompted to sign in, enter the sign-in credentials, and then choose **Sign In**.

1. (Optional) When prompted to save your credentials, choose **Yes**.

For more information about using the client applications, such as setting up multiple monitors or using peripheral devices, see [WorkSpaces Clients](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-clients.html) and [Peripheral Device Support](https://docs.aws.amazon.com/workspaces/latest/userguide/peripheral_devices.html) in the *Amazon WorkSpaces User Guide*.

#### Step 3: Clean up (Optional)
<a name="quick-setup-clean-up"></a>

If you are finished with the WorkSpace that you created for this tutorial, you can delete it. For more information, see [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md).

**Note**  
Simple AD is made available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your Simple AD directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).  
To delete empty directories, see [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md). If you delete your Simple AD directory, you can always create a new one when you want to start using WorkSpaces again.

#### Next steps
<a name="quick-setup-next-steps"></a>

You can continue to customize the WorkSpace that you just created. For example, you can install software and then create a custom bundle from your WorkSpace. You can also perform various administrative tasks for your WorkSpaces and your WorkSpaces directory. For more information, see the following documentation.
+ [Create a custom WorkSpaces image and bundle for WorkSpaces Personal](create-custom-bundle.md)
+ [Administer WorkSpaces Personal](administer-workspaces.md)
+ [Manage directories for WorkSpaces Personal](manage-workspaces-directory.md)

To create additional WorkSpaces, do one of the following:
+ If you want to continue using the VPC and the Simple AD directory that were created by quick setup, you can add WorkSpaces for additional users by following the steps in the [Create a WorkSpace in WorkSpaces Personal](create-workspaces-personal.md) section of the Launch a WorkSpace Using Simple AD tutorial.
+ If you need to use another directory type or if you need to use an existing Active Directory, see the appropriate tutorial in [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

For more information about using the WorkSpaces client applications, such as setting up multiple monitors or using peripheral devices, see [WorkSpaces Clients](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-clients.html) and [Peripheral Device Support](https://docs.aws.amazon.com/workspaces/latest/userguide/peripheral_devices.html) in the *Amazon WorkSpaces User Guide*.

### Get started with WorkSpaces Personal advanced setup
<a name="getting-started-advanced"></a>

In this tutorial, you learn how to provision a virtual, cloud-based Microsoft Windows, Amazon Linux, Ubuntu Linux, or Red Hat Enterprise Linux desktop, known as a *WorkSpace*, by using WorkSpaces and Directory Service.

This tutorial uses the advanced setup option to launch your WorkSpace.

**Note**  
Advanced setup is supported in all Regions for WorkSpaces. 

**Topics**
+ [Before you begin](#advanced-setup-prereqs)
+ [Using advanced setup to launch your WorkSpace](#advanced-setup-procedure)

#### Before you begin
<a name="advanced-setup-prereqs"></a>

Before you begin, make sure you have an AWS account that you can use to create or administer a WorkSpace. Users don't need an AWS account to connect to and use their WorkSpaces.

Review and understand the following concepts before you proceed:
+ When you launch a WorkSpace, you must select a WorkSpace bundle. For more information, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles).
+ When you launch a WorkSpace, you must select which protocol (PCoIP or DCV) you want to use with your bundle. For more information, see [Protocols for WorkSpaces Personal](amazon-workspaces-networking.md#amazon-workspaces-protocols).
+ When you launch a WorkSpace, you must specify profile information for the user, including a user name and email address. Users complete their profiles by specifying a password. Information about WorkSpaces and users is stored in a directory. For more information, see [Manage directories for WorkSpaces Personal](manage-workspaces-directory.md).

#### Using advanced setup to launch your WorkSpace
<a name="advanced-setup-procedure"></a>

**To use advanced setup to launch your WorkSpace:**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. Choose one of the following directory types, and then choose **Next**:
   + AWS Managed Microsoft AD
   + Simple AD
   + AD Connector

   

1. Enter the directory information.

1. Choose two subnets in a VPC from two different availability zones. For more information, see [ Configure a VPC with public subnets](https://docs.aws.amazon.com/workspaces/latest/adminguide/amazon-workspaces-vpc.html#configure-vpc-public-subnets).

1. Review your directory's information and choose **Create directory**.

# Create a WorkSpace in WorkSpaces Personal
<a name="create-workspaces-personal"></a>

WorkSpaces enables you to provision virtual, cloud-based Windows and Linux desktops for your users, known as *WorkSpaces*.

Before creating a personal WorkSpace, create a directory by doing one of the following:
+ Create a Simple AD directory.
+ Create an AWS Directory Service for Microsoft Active Directory, also known as AWS Managed Microsoft AD.
+ Connect to an existing Microsoft Active Directory by using Active Directory Connector.
+ Create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain.
+ Create a dedicated directory that uses Microsoft Entra ID as the identity source (through IAM Identity Center). WorkSpaces in the directory are native Entra ID-joined and enrolled into Microsoft Intune through Microsoft Windows Autopilot user-driven mode.
**Note**  
Such directories currently only support Windows 10 and 11 Bring Your Own Licenses personal WorkSpaces.
+ Create a dedicated directory that uses an identity provider of your choice as the identity source (through IAM Identity Center). WorkSpaces in the directory are native Entra ID-joined and enrolled into Microsoft Intune through Microsoft Windows Autopilot user-driven mode.
**Note**  
Such directories currently only support Windows 10 and 11 Bring Your Own Licenses personal WorkSpaces.

Now that you have created a directory, you are ready to create a personal WorkSpace.

**To create a personal WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Choose **Launch WorkSpaces**, **Personal**.

1. Choose **Create WorkSpaces**

1. Under **Onboarding** (optional), you can choose **Recommend options to me based on my use case** to get recommendations on the type of WorkSpace you want to use. You can skip this step if you know that you want to use personal WorkSpaces.

1. Choose **Next**. WorkSpaces registers your AD Connector.

1. Under **Configure WorkSpaces**, enter the following details:
   + For **Bundle**, choose from the following the bundle type that you want to use for your WorkSpaces.
     + **Use a base WorkSpaces bundle** - Choose one of the bundles from the drop down. For more information about the bundle type you selected, choose **Bundle details**. To compare bundles offered for pools, choose **Compare all bundles**.
     + **Use your own custom or BYOL bundle** - Choose a bundle that you previously created. To create a custom bundle, see [Create a custom WorkSpaces image and bundle for WorkSpaces Personal](create-custom-bundle.md).
**Note**  
Review the recommended uses and specifications of each bundle to help ensure you select the bundle that works best for your users. For more information about each use case, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles). For more information about bundle specifications, recommended uses, and pricing, see [Amazon WorkSpaces pricing](https://aws.amazon.com/workspaces/pricing/).
   + For **Running mode**, choose from the following to configure your personal WorkSpace’s immediate availability and how you pay for it (monthly or hourly):
     + **AlwaysOn** — Bills monthly fee for unlimited usage of your WorkSpaces. This mode is best for users who use their WorkSpace full time as their primary desktop.
     + **AutoStop** — Bills by the hour. With this mode, your WorkSpaces stop after a specified period of disconnection, and the state of apps and data is saved.
   + For **Tags**, specify the key pair value that you want to use. A key can be a general category, such as "project," "owner," or "environment," with specific associated values.

1. Under **Select directory**, enter the following details:
   + Choose the directory that you created. To create a directory, choose **Create directory**. For more information about creating personal directories, see [Register an existing Directory Service directory with WorkSpaces Personal](register-deregister-directory.md).
   + Choose the users from that directory you want to provision personal WorkSpaces for by doing the following.

     1. Choose **Create users**.

     1. Enter the user’s **Username**, **First name**, **Last name**, and **Email**. To add additional users, choose **Create additional user** and enter their information.

1. Under **Customization** (optional), you can customize bundles, root and user volume encryption, and user volume for all users or specific users.

1. Choose Create WorkSpaces. The initial status of the WorkSpace is PENDING. When the creation is complete, the status is AVAILABLE and an invitation is sent to the email address that you specified for the users.

1. Send invitations to the email address for each user. For more information, see [Send an invitation email](manage-workspaces-users.md#send-invitation).
**Note**  
These invitations aren't sent automatically if you're using AD Connector or a trust relationship.
Invitation emails aren't sent if the user already exists in Active Directory. Instead, make sure you manually send the user an invitation email. For more information, see [Send an invitation email](manage-workspaces-users.md#send-invitation).
In all Regions, the text of the invitation email is in English (US). In the following Regions, the English text is preceded by a second language:  
Asia Pacific (Seoul): Korean
Asia Pacific (Tokyo): Japanese
Canada (Central): French (Canadian)
China (Ningxia): Simplified Chinese

## Connect to the WorkSpace
<a name="connect-workspace-ad-connector"></a>

You can connect to your WorkSpace using the client of your choice. After you sign in, the client displays the WorkSpace desktop.

**To connect to the WorkSpace**

1. Open the link in the invitation email.

1. Review [WorkSpaces Clients](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-clients.html) in the *Amazon WorkSpaces User Guide* for more information about the requirements for each client, and then do one of the following: 
   + When prompted, download one of the client applications or launch Web Access.
   + If you aren't prompted and you haven't installed a client application already, open [https://clients.amazonworkspaces.com/](https://clients.amazonworkspaces.com/) and download one of the client applications or launch Web Access.
**Note**  
You cannot use a web browser (Web Access) to connect to Amazon Linux WorkSpaces.

1. Start the client, enter the registration code from the invitation email, and choose **Register**.

1. When prompted to sign in, enter the user's sign-in credentials, and then choose **Sign In**.

1. (Optional) When prompted to save your credentials, choose **Yes**.

**Note**  
Because you're using AD Connector, your users won't be able to reset their own passwords. (The **Forgot password?** option on the WorkSpaces client application login screen won't be available.) For information about how to reset user passwords, see [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md).

## Next steps
<a name="next-steps-ad-connector"></a>

You can continue to customize the WorkSpace that you just created. For example, you can install software and then create a custom bundle from your WorkSpace. You can also perform various administrative tasks for your WorkSpaces and your WorkSpaces directory. If you are finished with your WorkSpace, you can delete it. For more information, see the following documentation.
+ [Create a custom WorkSpaces image and bundle for WorkSpaces Personal](create-custom-bundle.md)
+ [Administer WorkSpaces Personal](administer-workspaces.md)
+ [Manage directories for WorkSpaces Personal](manage-workspaces-directory.md)
+ [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md)

For more information about using the WorkSpaces client applications, such as setting up multiple monitors or using peripheral devices, see [WorkSpaces Clients](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-clients.html) and [Peripheral Device Support](https://docs.aws.amazon.com/workspaces/latest/userguide/peripheral_devices.html) in the *Amazon WorkSpaces User Guide*.

# Networking protocols and access for WorkSpaces Personal
<a name="amazon-workspaces-networking"></a>

As a WorkSpace administrator, you must understand how to manage WorkSpaces networking and access, beginning with protocols.

## Protocols for WorkSpaces Personal
<a name="amazon-workspaces-protocols"></a>

Amazon WorkSpaces supports two protocols: PCoIP and DCV. The protocol that you choose depends on several factors, such as the type of devices your users will be accessing their WorkSpaces from, which operating system is on your WorkSpaces, what network conditions your users will be facing, and whether your users require bidirectional video support.

### Requirements
<a name="w2aac11c25b5b5"></a>

DCV WorkSpaces are only supported with the following minimum requirements.

Host agent requirements:
+ Windows host agent version 2.0.0.312 or above
+ Ubuntu host agent version 2.1.0.501 or above
+ Amazon Linux 2 host agent version 2.0.0.596 or above
+ Rocky Linux host agent version 2.1.0.1628 or above
+ Red Hat Enterprise Linux host agent version 2.1.0.1628 or above

Client requirements:
+ Windows native client version 5.1.0.329 or higher
+ macOS native client version 5.5.0 or higher
+ Ubuntu 22.04 client version 2024.x or higher
+ Amazon WorkSpaces Thin Client (For more information, see the [Amazon WorkSpaces Thin Client Documentation](https://docs.aws.amazon.com/workspaces-thin-client/))
+ Web Access

For more information about how to check your WorkSpace client version and host agent version, see the [FAQ](https://aws.amazon.com/workspaces/faqs/#:~:text=Q%3A%20How%20do%20I%20find%20my%20WSP%20host%20agent%20version%3F).

### When to use DCV
<a name="w2aac11c25b5b7"></a>
+ If you need higher loss/latency tolerance to support your end user network conditions. For example, you have users who are accessing their WorkSpaces across global distances or using unreliable networks.
+ If you need your users to authenticate with smart cards or to use smart cards in-session.
+ If you need webcam support capabilities in-session.
+ If you need to use Web Access with the Windows Server 2022 or Windows Server 2025-powered WorkSpaces bundle.
+ If you need to use Ubuntu WorkSpaces.
+ If you need to use Windows 11 BYOL WorkSpaces.
+ If you need to use GPU-enabled WorkSpaces bundles with Windows.
+ If you need to use Windows GPU-based bundles (Graphics.g6, Graphics.g4dn and GraphicsPro.g4dn) or Ubuntu GPU-based bundles (Graphics.g4dn and GraphicsPro.g4dn).
+ If you need your users to authenticate in-session with WebAuthn authenticators such as YubiKey or Windows Hello.

### When to use PCoIP
<a name="w2aac11c25b5b9"></a>
+ If you want to use the iPad or Android Linux clients.
+ If you use Teradici zero client devices.
+ If you need to use a Linux bundle for non-smart card use cases.
+ If you need to use WorkSpaces in the China (Ningxia) Region.

**Note**  
A directory can have a mix of PCoIP and DCV WorkSpaces in it.
A user can have both a PCoIP and a DCV WorkSpace as long as the two WorkSpaces are located in separate directories. The same user cannot have a PCoIP and a DCV WorkSpace in the same directory. For more information about creating multiple WorkSpaces for a user, see [Create multiple WorkSpaces for a user in WorkSpaces Personal](create-multiple-workspaces-for-user.md).
You can migrate a WorkSpace between the two protocols by using the WorkSpaces migration feature, which requires a rebuild of the WorkSpace. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md).
If your WorkSpace was created with PCoIP bundles you can modify the streaming protocol to migrate between the two protocols without requiring a rebuild, while retaining the root volume. For more information, see [ Modify protocols](https://docs.aws.amazon.com/workspaces/latest/adminguide/modify-workspaces.html#modify_protocols).
For the best experience with video conferencing we recommend using Power, PowerPro, GeneralPurpose.4xlarge, or GeneralPurpose.8xlarge bundles only.

The following topics offer additional detail about how to manage networking and access for WorkSpaces Personal:

# Configure a VPC for WorkSpaces Personal
<a name="amazon-workspaces-vpc"></a>

WorkSpaces launches your WorkSpaces in a virtual private cloud (VPC).

You can create a VPC with two private subnets for your WorkSpaces and a NAT gateway in a public subnet. Alternatively, you can create a VPC with two public subnets for your WorkSpaces and associate a public IP address or Elastic IP address with each WorkSpace.

For more information about VPC design considerations, see [Best Practices for VPCs and Networking in Amazon WorkSpaces Deployments](https://d1.awsstatic.com/whitepapers/best-practices-vpcs-networking-amazon-workspaces-deployments.pdf) and [Best Practices for Deploying WorkSpaces - VPC Design](https://docs.aws.amazon.com/whitepapers/latest/best-practices-deploying-amazon-workspaces/vpc-design.html).

**Topics**
+ [Requirements](#configure-vpc-requirements)
+ [Configure a VPC with private subnets and a NAT gateway](#configure-vpc-nat-gateway)
+ [Configure a VPC with public subnets](#configure-vpc-public-subnets)

## Requirements
<a name="configure-vpc-requirements"></a>

Your VPC's subnets must reside in different Availability Zones in the Region where you're launching WorkSpaces. Availability Zones are distinct locations that are engineered to be isolated from failures in other Availability Zones. By launching instances in separate Availability Zones, you can protect your applications from the failure of a single location. Each subnet must reside entirely within one Availability Zone and cannot span zones.

**Note**  
Amazon WorkSpaces is available in a subset of the Availability Zones in each supported Region. To determine which Availability Zones you can use for the subnets of the VPC that you're using for WorkSpaces, see [Availability Zones for WorkSpaces Personal](azs-workspaces.md). 

## Configure a VPC with private subnets and a NAT gateway
<a name="configure-vpc-nat-gateway"></a>

If you use Directory Service to create an AWS Managed Microsoft or a Simple AD, we recommend that you configure the VPC with one public subnet and two private subnets. Configure your directory to launch your WorkSpaces in the private subnets. To provide internet access to WorkSpaces in a private subnet, configure a NAT gateway in the public subnet.

![\[Configure your WorkSpaces VPC\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/vpc-configuration-new.png)


**To create a VPC with one public subnet and two private subnets**

1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).

1. Choose **Create VPC**.

1. Under **Resources to create**, choose **VPC and more**.

1. For **Name tag auto-generation**, enter a name for the VPC.

1. To configure the subnets, do the following:

   1. For **Number of Availability Zones**, choose **1** or **2**, depending on your needs.

   1. Expand **Customize AZs** and choose your Availability Zones. Otherwise, AWS selects them for you. To make an appropriate selection, see [Availability Zones for WorkSpaces Personal](azs-workspaces.md).

   1. For **Number of public subnets**, ensure that you have one public subnet per Availability Zone.

   1. For **Number of private subnets**, ensure that you have at least one private subnet per Availability Zone.

   1. Enter a CIDR block for each subnet. For more information, see [Subnet sizing](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-sizing) in the *Amazon VPC User Guide*.

1. For **NAT gateways**, choose **1 per AZ**.

1. Choose **Create VPC**.

**IPv6 CIDR blocks**  
You can associate IPv6 CIDR blocks with your VPC and its subnets, and configure those subnets to automatically assign IPv6 addresses to newly launched instances. For customer-created subnets, auto-assign IPv6 addressing is disabled by default. To view or update this setting in the Amazon VPC console, choose Subnets in the navigation pane, select the target subnet, and then choose **Actions**, **Modify auto-assign IP settings**.

## Configure a VPC with public subnets
<a name="configure-vpc-public-subnets"></a>

If you prefer, you can create a VPC with two public subnets. To provide internet access to WorkSpaces in public subnets, configure the directory to assign Elastic IP addresses automatically or manually assign an Elastic IP address to each WorkSpace.

**Topics**
+ [Step 1: Create a VPC](#create-vpc-public-subnet)
+ [Step 2: Assign public IP addresses to your WorkSpaces](#assign-eip)

### Step 1: Create a VPC
<a name="create-vpc-public-subnet"></a>

Create a VPC with one public subnet as follows.

**To create the VPC**

1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/).

1. Choose **Create VPC**.

1. Under **Resources to create**, choose **VPC and more**.

1. For **Name tag auto-generation**, enter a name for the VPC.

1. To configure the subnets, do the following:

   1. For **Number of Availability Zones**, choose **2**.

   1. Expand **Customize AZs** and choose your Availability Zones. Otherwise, AWS selects them for you. To make an appropriate selection, see [Availability Zones for WorkSpaces Personal](azs-workspaces.md).

   1. For **Number of public subnets**, choose **2**.

   1. For **Number of private subnets**, choose **0**.

   1. Enter a CIDR block for each public subnet. For more information, see [Subnet sizing](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-sizing) in the *Amazon VPC User Guide*.

1. Choose **Create VPC**.

**IPv6 CIDR blocks**  
You can associate IPv6 CIDR blocks with your VPC and its subnets, and configure those subnets to automatically assign IPv6 addresses to newly launched instances. For customer-created subnets, auto-assign IPv6 addressing is disabled by default. To view or update this setting in the Amazon VPC console, choose Subnets in the navigation pane, select the target subnet, and then choose **Actions**, **Modify auto-assign IP settings**.

### Step 2: Assign public IP addresses to your WorkSpaces
<a name="assign-eip"></a>

You can assign public IP addresses to your WorkSpaces automatically or manually. To use automatic assignment, see [Configure automatic public IP addresses for WorkSpaces Personal](automatic-assignment.md). To assign public IP addresses manually, use the following procedure.

**To assign a public IP address to a WorkSpace manually**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Expand the row (choose the arrow icon) for the WorkSpace and note the value of **WorkSpace IP**. This is the primary private IP address of the WorkSpace.

1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

1. In the navigation pane, choose **Elastic IPs**. If you do not have an available Elastic IP address, choose **Allocate Elastic IP address** and choose **Amazon's pool of IPv4 addresses** or **Customer owned pool of IPv4 addresses**, and then choose **Allocate**. Make note of the new IP address.

1. In the navigation pane, choose **Network Interfaces**.

1. Select the network interface for your WorkSpace. To find the network interface for your WorkSpace, enter the **WorkSpace IP** value (which you noted earlier) in the search box, and then press **Enter**. The **WorkSpace IP** value matches the primary private IPv4 address for the network interface. Note that the VPC ID of the network interface matches the ID of your WorkSpaces VPC.

1. Choose **Actions**, **Manage IP Addresses**. Choose **Assign new IP**, and then choose **Yes, Update**. Make note of the new IP address.

1. Choose **Actions**, **Associate Address**.

1. On the **Associate Elastic IP Address** page, choose an Elastic IP address from **Address**. For **Associate to private IP address**, specify the new private IP address, and then choose **Associate Address**.

# Configure AWS Global Accelerator (AGA) for WorkSpaces Personal
<a name="amazon-workspaces-aga"></a>

You can enable AWS Global Accelerator (AGA) either at the WorkSpaces directory level or for individual WorkSpaces running DCV protocol. When enabled, the service automatically routes the streaming traffic through the nearest AWS edge location and across the AWS global network, which is congestion-free and redundant. This helps deliver a more responsive and stable streaming experience. The WorkSpaces service fully manages AGA usage and is subject to outbound data volume limits.

**Topics**
+ [Requirements](#configure-aga-requirements)
+ [Limitations](#configure-aga-limitations)
+ [Outbound data limits](#configure-aga-outbound-data-limits)
+ [Enable AGA for a WorkSpaces directory](#enabling-aga-directory)
+ [Enable AGA for individual WorkSpaces](#enabling-aga-individual)

## Requirements
<a name="configure-aga-requirements"></a>
+ WorkSpaces use a range of public IPv4 addresses for the dedicated AWS Global Accelerator (AGA) endpoints. Make sure to configure your firewall policies for devices that access WorkSpaces through AGA. If the AGA endpoints are blocked by the firewall, WorkSpaces streaming traffic won't be routed through AGA. For more information about the AGA endpoint IP ranges in each AWS region, see [DCV gateway servers](workspaces-port-requirements.md#gateway_WSP).
+ To access WorkSpaces through AGA, users must use WorkSpaces client versions 5.23 or later.

## Limitations
<a name="configure-aga-limitations"></a>
+ You can enable AGA for DCV WorkSpaces only. If you enable AGA at WorkSpaces directory level, it will only apply to the DCV WorkSpaces in the directory.
+ You can't enable AGA for a directory (or the WorkSpaces in the directory) that has both FIPS and IP access control groups enabled. You must disable FIPS or IP access control groups before enabling AGA for the directory.

## Outbound data limits
<a name="configure-aga-outbound-data-limits"></a>

The following are applicable data volume limits for WorkSpaces bundles.
+ **Value, Standard, and Performance bundles:** Includes 20 GB of AGA outbound data per user per month.
+ **Power, PowerPro, and Graphics bundles:** Includes 50 GB of AGA outbound data per user per month.

These outbound data limits are intended to cover the data usage of users streaming from their WorkSpaces. Beyond the limits, the WorkSpaces service might restrict AGA usage and route WorkSpaces traffic off of AGA on a case-by-case basis.

## Enable AGA for a WorkSpaces directory
<a name="enabling-aga-directory"></a>

You can configure AGA settings on a directory level. The settings will apply to all the DCV WorkSpaces in the directory unless overridden by the individual WorkSpaces.

**To enable AGA for a directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Under the **Directory ID** column, choose the directory ID of the directory you want to configure AGA settings for.

1. On the Directory Details page, scroll down to the AWS Global Accelerator (AGA) configuration section and choose **Edit**.

1. Choose **Enable AGA (automatic)**.

1. **Always use TCP with AGA** is selected by default. If you unselect it, your WorkSpaces client will determine whether TCP or UDP is used with AGA based on the DCV streaming protocol settings on your clients.

1. Choose **Save**.

After you enable AGA for a WorkSpaces directory, DCV WorkSpaces in the directory use AGA for streaming starting from the next session. No reboot is needed.

## Enable AGA for individual WorkSpaces
<a name="enabling-aga-individual"></a>

You can configure AGA settings for individual WorkSpaces, which overrides the settings inherited from the directory that the WorkSpaces are associated with.

**To enable AGA for individual WorkSpaces**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**, **Personal**.

1. Under the **WorkSpace ID** column, choose the WorkSpace ID of the WorkSpace you want to configure AGA settings for.

1. On the WorkSpaces Details page, scroll down to the AWS Global Accelerator (AGA) configuration section and choose **Edit**.

1. Choose **Manually override AGA configurations for this WorkSpace**.

1. Choose **Enable AGA (automatic)**.

1. **Always use TCP with AGA** is selected by default. If you unselect it, your WorkSpaces client will determine whether TCP or UDP is used with AGA based on the DCV streaming protocol settings on your clients.

1. Choose **Save**.

# Availability Zones for WorkSpaces Personal
<a name="azs-workspaces"></a>

When you are creating a virtual private cloud (VPC) for use with Amazon WorkSpaces, your VPC's subnets must reside in different Availability Zones in the Region where you're launching WorkSpaces. Availability Zones are distinct locations that are engineered to be isolated from failures in other Availability Zones. By launching instances in separate Availability Zones, you can protect your applications from the failure of a single location. Each subnet must reside entirely within one Availability Zone and cannot span zones.

An Availability Zone is represented by a Region code followed by a letter identifier; for example, `us-east-1a`. To ensure that resources are distributed across the Availability Zones for a Region, we independently map Availability Zones to names for each AWS account. For example, the Availability Zone `us-east-1a` for your AWS account might not be the same location as `us-east-1a` for another AWS account.

To coordinate Availability Zones across accounts, you must use the *AZ ID*, which is a unique and consistent identifier for an Availability Zone. For example, `use1-az2` is an AZ ID for the `us-east-1` Region and it has the same location in every AWS account.

Viewing AZ IDs enables you to determine the location of resources in one account relative to the resources in another account. For example, if you share a subnet in the Availability Zone with the AZ ID `use1-az2` with another account, this subnet is available to that account in the Availability Zone whose AZ ID is also `use1-az2`. The AZ ID for each VPC and subnet is displayed in the Amazon VPC console.

Amazon WorkSpaces is only available in a subset of the Availability Zones for each supported Region. The following table lists the AZ IDs that you can use for each Region. To see the mapping of AZ IDs to Availability Zones in your account, see [ AZ IDs for Your Resources](https://docs.aws.amazon.com/ram/latest/userguide/working-with-az-ids.html) in the *AWS RAM User Guide*.


| Region name | Region code | Supported AZ IDs | 
| --- | --- | --- | 
| US East (N. Virginia) | us-east-1 | use1-az2, use1-az4, use1-az6 | 
| US East (Ohio) | us-east-2 | use2-az1, use2-az2, use2-az3 | 
| US West (Oregon) | us-west-2 | usw2-az1, usw2-az2, usw2-az3 | 
| Asia Pacific (Mumbai) | ap-south-1 | aps1-az1, aps1-az2, aps1-az3 | 
| Asia Pacific (Seoul) | ap-northeast-2 | apne2-az1, apne2-az3 | 
| Asia Pacific (Singapore) | ap-southeast-1 | apse1-az1, apse1-az2 | 
| Asia Pacific (Sydney) | ap-southeast-2 | apse2-az1, apse2-az3 | 
| Asia Pacific (Malaysia) | ap-southeast-5 | apse5-az1, apse5-az2, apse5-az3 | 
| Asia Pacific (Tokyo) | ap-northeast-1 | apne1-az1, apne1-az4 | 
| Canada (Central) | ca-central-1 | cac1-az1, cac1-az2 | 
| Europe (Frankfurt) | eu-central-1 | euc1-az2, euc1-az3 | 
| Europe (Ireland) | eu-west-1 | euw1-az1, euw1-az2, euw1-az3 | 
| Europe (London) | eu-west-2 | euw2-az2, euw2-az3 | 
| Europe (Paris) | eu-west-3 | euw3-az1, euw3-az2, euw3-az3 | 
| South America (São Paulo) | sa-east-1 | sae1-az1, sae1-az3 | 
| Africa (Cape Town) | af-south-1 | afs1-az1, afs1-az2, afs1-az3 | 
| Israel (Tel Aviv) | il-central-1 | ilc1-az1, ilc1-az2, ilc1-az3 | 
| AWS GovCloud (US-West) | us-gov-west-1 | usgw1-az1, usgw1-az2, usgw1-az3 | 
| AWS GovCloud (US-East) | us-gov-east-1 | usge1-az1, usge1-az2, usge1-az3 | 

For more information about Availability Zones and AZ IDs, see [ Regions, Availability Zones, and Local Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in the *Amazon EC2 User Guide*.

# IP address and port requirements for WorkSpaces Personal
<a name="workspaces-port-requirements"></a>

To connect to your WorkSpaces, the network that your WorkSpaces clients are connected to must have certain ports open to the IP address ranges for the various AWS services (grouped in subsets). These address ranges vary by AWS Region. These same ports must also be open on any firewall running on the client. For more information about the AWS IP address ranges for different Regions, see [AWS IP Address Ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html) in the *Amazon Web Services General Reference*.

For additional architecture diagrams, see [Best Practices for Deploying Amazon WorkSpaces](https://docs.aws.amazon.com/whitepapers/latest/best-practices-deploying-amazon-workspaces/best-practices-deploying-amazon-workspaces.html).

## Ports for client applications
<a name="client-application-ports"></a>

The WorkSpaces client application requires outbound access on the following ports:

Port 53 (UDP)  
This port is used to access DNS servers. It must be open to your DNS server IP addresses so that the client can resolve public domain names. This port requirement is optional if you are not using DNS servers for domain name resolution.

Port 443 (UDP and TCP)  
This port is used for client application updates, registration, and authentication. The desktop client applications support the use of a proxy server for port 443 (HTTPS) traffic. To enable the use of a proxy server, open the client application, choose **Advanced Settings**, select **Use Proxy Server**, specify the address and port of the proxy server, and choose **Save**.  
This port must be open to the following IP address ranges:  
+ The `AMAZON` subset in the `GLOBAL` Region.
+ The `AMAZON` subset in the Region that the WorkSpace is in.
+ The `AMAZON` subset in the `us-east-1` Region.
+ The `AMAZON` subset in the `us-west-2` Region.
+ The `S3` subset in the `us-west-2` Region.

Port 4172 (UDP and TCP)  
This port is used for streaming the WorkSpace desktop and health checks for PCoIP WorkSpaces. This port must be open to the PCoIP Gateway and to the health check servers in the Region that the WorkSpace is in. For more information, see [Health check servers](#health_check) and [PCoIP gateway servers](#gateway_IP).  
For PCoIP WorkSpaces, the desktop client applications do not support the use of a proxy server nor TLS decryption and inspection for port 4172 traffic in UDP (for desktop traffic). They require a direct connection to ports 4172. 

Port 4195 (UDP and TCP)  
This port is used for streaming the WorkSpace desktop and health checks for DCV WorkSpaces. This port must be open to the DCV Gateway IP address ranges and the health check servers in the Region that the WorkSpace is in. For more information, see [Health check servers](#health_check) and [DCV gateway servers](#gateway_WSP).  
For DCV WorkSpaces, the WorkSpaces Windows client application (version 5.1 and above) and macOS client application (version 5.4 and above) support the use of HTTP proxy servers for port 4195 TCP traffic, but the use of a proxy is not recommended. TLS decryption and inspection are not supported. For more information, see **Configure device proxy server settings for internet access** for [ Windows WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/group_policy.html#gp_device_proxy), [ Amazon Linux WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/group_policy.html#gp_device_proxy_linux), and [ Ubuntu WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/group_policy.html#gp_device_proxy_ubuntu).

**Note**  
If your firewall uses stateful filtering, ephemeral ports (also known as dynamic ports) are automatically opened to allow return communication. If your firewall uses stateless filtering, you must open ephemeral ports explicitly to allow return communication. The required ephemeral port range that you must open will vary depending on your configuration.
Proxy server function is not supported for UDP traffic. If you choose to use a proxy server, the API calls that the client application makes to the Amazon WorkSpaces services are also proxied. Both API calls and desktop traffic should pass through the same proxy server.
The WorkSpaces client application first attempts to stream using UDP (QUIC) for optimal performance. If the client network only allows TCP, then TCP will be used. The WorkSpaces web client will connect over TCP port 4195 or 443. If port 4195 is blocked, the client will only attempt to connect to over port 443. 

## Ports for Web Access
<a name="web-access-ports"></a>

WorkSpaces Web Access requires outbound access for the following ports:

Port 53 (UDP)  
This port is used to access DNS servers. It must be open to your DNS server IP addresses so that the client can resolve public domain names. This port requirement is optional if you are not using DNS servers for domain name resolution.

Port 80 (UDP and TCP)  
This port is used for initial connections to `https://clients.amazonworkspaces.com`, which then switch to HTTPS. It must be open to all IP address ranges in the `EC2` subset in the Region that the WorkSpace is in. 

Port 443 (UDP and TCP)  
This port is used for registration and authentication using HTTPS. It must be open to all IP address ranges in the `EC2` subset in the Region that the WorkSpace is in.

Port 4195 (UDP and TCP)  
For WorkSpaces that are configured for DCV, this port is used for streaming the WorkSpaces desktop traffic. This port must be open to the DCV Gateway IP address ranges. For more information, see [DCV gateway servers](#gateway_WSP).  
DCV web access supports the use of a proxy server for port 4195 TCP traffic, but it’s not recommended. For more information, see **Configure device proxy server settings for internet access** for [ Windows WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/group_policy.html#gp_device_proxy), [ Amazon Linux WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/group_policy.html#gp_device_proxy_linux), or [ Ubuntu WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/group_policy.html#gp_device_proxy_ubuntu).

**Note**  
If your firewall uses stateful filtering, ephemeral ports (also known as dynamic ports) are automatically opened to allow return communication. If your firewall uses stateless filtering, you must open ephemeral ports explicitly to allow return communication. The required ephemeral port range that you must open varies depending on your configuration.
The WorkSpaces client application first attempts to stream using UDP (QUIC) for optimal performance. If the client network only allows TCP, then TCP will be used. The WorkSpaces web client will connect over TCP port 4195 or 443. If port 4195 is blocked, the client will only attempt to connect to over port 443. 

Typically, the web browser randomly selects a source port in the high range to use for streaming traffic. WorkSpaces Web Access does not have control over the port that the browser selects. You must ensure that return traffic to this port is allowed.

## Domains and IP addresses to add to your allow list
<a name="whitelisted_ports"></a>

For the WorkSpaces client application to be able to access the WorkSpaces service, you must add the following domains and IP addresses to the allow list on the network from which the client is trying to access the service.


**Domains and IP addresses to add to your allow list**  

| Category | Domain or IP address | 
| --- | --- | 
| CAPTCHA |  https://opfcaptcha-prod.s3.amazonaws.com/  | 
| Client Auto-update |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  |  https://fls-na.amazon.com/  | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| User Login Pages |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) https://*directory\$1id*.awsapps.com/ **directory id** is the customer's domain. In the AWS GovCloud (US-West) and AWS GovCloud (US-East) Regions: https://login.us-gov-home.awsapps.com/directory/*directory id*/  **directory id** is the customer's domain.  | 
| WS Broker |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces Endpoints for SAML Single Sign-On (SSO) |  Domains: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 


**Domains and IP addresses to add to your allow list for PCoIP**  

| Category | Domain or IP address | 
| --- | --- | 
| PCoIP Session Gateway (PSG) | [PCoIP gateway servers](#gateway_IP) | 
| Session Broker (PCM) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Web Access TURN Servers for PCoIP |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 


**Domains and IP addresses to add to your allow list for DCV**  

| Category | Domain or IP address | 
| --- | --- | 
| DCV Session Gateway (WSG) |  [DCV gateway servers](#gateway_WSP)  | 
| Web Access TURN Servers for DCV |  [DCV gateway servers](#gateway_WSP)  | 

## Health check servers
<a name="health_check"></a>

The WorkSpaces client applications perform health checks over ports 4172 and 4195. These checks validate whether TCP or UDP traffic streams from the WorkSpaces servers to the client applications. For these checks to finish successfully, your firewall policies must allow outbound traffic to the IP addresses of the following Regional health check servers.


| Region | Health check hostname | IP addresses | 
| --- | --- | --- | 
| US East (N. Virginia) |  IPv4: drp-iad.amazonworkspaces.com IPv6: drp-workspaces.us-east-1.api.aws  |  IPv4: 3.209.215.252 3.212.50.30 3.225.55.35 3.226.24.234 34.200.29.95 52.200.219.150 IPv6: 2600:1f18:74e9:4400::/56  | 
| US West (Oregon) |  IPv4: drp-pdx.amazonworkspaces.com IPv6: drp-workspaces.us-west-2.api.aws  |  IPv4: 34.217.248.177 52.34.160.80 54.68.150.54 54.185.4.125 54.188.171.18 54.244.158.140 IPv6: 2600:1f14:278e:5700::/56  | 
| Asia Pacific (Mumbai) |  IPv4: drp-bom.amazonworkspaces.com IPv6: drp-workspaces.ap-south-1.api.aws  |  IPv4: 13.127.57.82 13.234.250.73 IPv6: 2406:da1a:502:b800::/56  | 
| Asia Pacific (Seoul) |  IPv4: drp-icn.amazonworkspaces.com IPv6: drp-workspaces.ap-northeast-2.api.aws  |  IPv4: 13.124.44.166 13.124.203.105 52.78.44.253 52.79.54.102 IPv6: 2406:da12:c8c:4900::/56  | 
| Asia Pacific (Singapore) |  IPv4: drp-sin.amazonworkspaces.com IPv6: drp-workspaces.ap-southeast-1.api.aws  |  IPv4: 3.0.212.144 18.138.99.116 18.140.252.123 52.74.175.118 IPv6: 2406:da18:991:4a00::/56  | 
| Asia Pacific (Sydney) |  IPv4: drp-syd.amazonworkspaces.com IPv6: drp-workspaces.ap-southeast-2.api.aws  |  IPv4: 3.24.11.127 13.237.232.125 IPv6: 2406:da1c:9b5:9d00::/56  | 
| Asia Pacific (Tokyo) |  IPv4: drp-nrt.amazonworkspaces.com IPv6: drp-workspaces.ap-northeast-1.api.aws  |  IPv4: 18.178.102.247 54.64.174.128 IPv6: 2406:da14:785:5300::/56  | 
| Canada (Central) |  IPv4: drp-yul.amazonworkspaces.com IPv6: drp-workspaces.ca-central-1.api.aws  |  IPv4: 52.60.69.16 52.60.80.237 52.60.173.117 52.60.201.0 IPv6: 2600:1f11:759:d900::/56  | 
| Europe (Frankfurt) |  IPv4: drp-fra.amazonworkspaces.com IPv6: drp-workspaces.eu-central-1.api.aws  |  IPv4: 52.59.191.224 52.59.191.225 52.59.191.226 52.59.191.227 IPv6: 2a05:d014:b5c:500::/56  | 
| Europe (Ireland) |  IPv4: drp-dub.amazonworkspaces.com IPv6: drp-workspaces.eu-west-1.api.aws  |  IPv4: 18.200.177.86 52.48.86.38 54.76.137.224 IPv6: 2a05:d018:10ca:f400::/56  | 
| Europe (London) |  IPv4: drp-lhr.amazonworkspaces.com IPv6: drp-workspaces.eu-west-2.api.aws  |  IPv4: 35.176.62.54 35.177.255.44 52.56.46.102 52.56.111.36 IPv6: 2a05:d01c:263:f400::/56  | 
| Europe (Paris) |  IPv4: drp-cdg.amazonworkspaces.com IPv6: drp-workspaces.eu-west-3.api.aws  |  IPv4: 51.17.52.90 51.17.109.231 51.16.190.43 IPv6: 2a05:d012:16:8600::/56  | 
| South America (São Paulo) |  IPv4: drp-gru.amazonworkspaces.com IPv6: drp-workspaces.sa-east-1.api.aws  |  IPv4: 18.231.0.105 52.67.55.29 54.233.156.245 54.233.216.234 IPv6: 2600:1f1e:bbf:fa00::/56  | 
| Africa (Cape Town) |  IPv4: drp-cpt.amazonworkspaces.com/ IPv6: drp-workspaces.af-south-1.api.aws  |  IPv4: 13.244.128.155 13.245.205.255 13.245.216.116 IPv6: 2406:da11:685:2400::/56  | 
| Israel (Tel Aviv) |  IPv4: drp-tlv.amazonworkspaces.com/ IPv6: drp-workspaces.il-central-1.api.aws  |  IPv4: 51.17.52.90 51.17.109.231 51.16.190.43 IPv6: 2a05:d025:c78:fc00::/56  | 
| AWS GovCloud (US-West) |  IPv4: drp-pdt.amazonworkspaces.com IPv6: drp-workspaces.us-gov-west-1.api.aws  |  IPv4: 52.61.60.65 52.61.65.14 52.61.88.170 52.61.137.87 52.61.155.110 52.222.20.88 IPv6: 2600:1f12:28f:af00::/56  | 
| AWS GovCloud (US-East) |  IPv4: drp-osu.amazonworkspaces.com IPv6: drp-workspaces.us-gov-east-1.api.aws  |  IPv4: 18.253.251.70 18.254.0.118 IPv6: 2600:1f15:a45:3e00::/56  | 

## PCoIP gateway servers
<a name="gateway_IP"></a>

WorkSpaces uses PCoIP to stream the desktop session to clients over port 4172. For its PCoIP gateway servers, WorkSpaces uses a small range of Amazon EC2 public IPv4 and IPv6 addresses. This enables you to set more finely grained firewall policies for devices that access WorkSpaces. Note that the WorkSpaces client prioritizes IPv6 connections when IPv6 is supported and gateways are reachable. If IPv6 is unavailable, it falls back to IPv4.


| Region | Region code | Public IP address range | 
| --- | --- | --- | 
| US East (N. Virginia) | us-east-1 |  3.217.228.0 - 3.217.231.255 3.235.112.0 - 3.235.119.255 52.23.61.0 - 52.23.62.255 2600:1f32:8000::/39   | 
| US West (Oregon) | us-west-2 |  35.80.88.0 - 35.80.95.255 44.234.54.0 - 44.234.55.255 54.244.46.0 - 54.244.47.255 2600:1f32:4000::/39   | 
| Asia Pacific (Mumbai) | ap-south-1 |  13.126.243.0 - 13.126.243.255 2406:da32:a000::/40  | 
| Asia Pacific (Seoul) | ap-northeast-2 |  3.34.37.0 - 3.34.37.255 3.34.38.0 - 3.34.39.255 13.124.247.0 - 13.124.247.255 2406:da32:2000::/40  | 
| Asia Pacific (Singapore) | ap-southeast-1 |  18.141.152.0 - 18.141.152.255 18.141.154.0 - 18.141.155.255 52.76.127.0 - 52.76.127.255 2406:da32:8000::/40  | 
| Asia Pacific (Sydney) | ap-southeast-2 |  3.25.43.0 - 3.25.43.255 3.25.44.0 - 3.25.45.255 54.153.254.0 - 54.153.254.255 2406:da32:c000::/40  | 
| Asia Pacific (Tokyo) | ap-northeast-1 |  18.180.178.0 - 18.180.178.255 18.180.180.0 - 18.180.181.255 54.250.251.0 - 54.250.251.255 2406:da32:4000::/40  | 
| Canada (Central) | ca-central-1 |  15.223.100.0 - 15.223.100.255 15.223.102.0 - 15.223.103.255 35.183.255.0 - 35.183.255.255 2600:1f32:1000::/40  | 
| Europe (Frankfurt) | eu-central-1 |  18.156.52.0 - 18.156.52.255 18.156.54.0 - 18.156.55.255 52.59.127.0 - 52.59.127.255 2a05:d032:4000::/40  | 
| Europe (Ireland) | eu-west-1 |  3.249.28.0 - 3.249.29.255 52.19.124.0 - 52.19.125.255 2a05:d032:8000::/40  | 
| Europe (London) | eu-west-2 |  18.132.21.0 - 18.132.21.255 18.132.22.0 - 18.132.23.255 35.176.32.0 - 35.176.32.255 2a05:d032:c000::/40  | 
| Europe (Paris) | eu-west-3 |  51.44.204.0-51.44.207.255  | 
| South America (São Paulo) | sa-east-1 |  18.230.103.0 - 18.230.103.255 18.230.104.0 - 18.230.105.255 54.233.204.0 - 54.233.204.255 2600:1f32:e000::/40  | 
| Africa (Cape Town) | af-south-1 |  13.246.120.0 - 13.246.123.255 2406:da32:1000::/40  | 
| Israel (Tel Aviv) | il-central-1 |   51.17.28.0-51.17.31.255 2a05:d032:5000::/40  | 
| AWS GovCloud (US-West) | us-gov-west-1 |  52.61.193.0 - 52.61.193.255 2600:1f32:2000::/40  | 
| AWS GovCloud (US-East) | us-gov-east-1 |  18.254.140.0 - 18.254.143.255 2600:1f32:5000::/40  | 

## DCV gateway servers
<a name="gateway_WSP"></a>

**Important**  
Starting in June 2020, WorkSpaces streams the desktop session for DCV WorkSpaces to clients over port 4195 instead of port 4172. If you want to use DCV WorkSpaces, make sure that port 4195 is open to traffic.

**Note**  
For non-BYOL WorkSpaces Pools, IP address ranges are not guaranteed. Instead, you must allowlist the DCV gateway domain names. For more information, see [ DCV gateway domain names](https://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html#dns-wsp). 

WorkSpaces uses a small range of Amazon EC2 public IPv4 and IPv6 addresses for its DCV gateway servers. This enables you to set more finely grained firewall policies for devices that access WorkSpaces. WorkSpaces use a separate range of public IPv4 addresses for the dedicated AWS Global Accelerator (AGA) endpoints. Make sure to configure your firewall policies to allowlist the IP ranges if you plan to enable AGA for your WorkSpaces. Note that the WorkSpaces client prioritizes IPv6 connections when IPv6 is supported and gateways are reachable. If IPv6 is unavailable, it falls back to IPv4.

If you use AGA \$1 IPv6, you need to allowlist the IPv6 CIDR ranges from the `GLOBALACCELERATOR` ranges. See [Location and IP address ranges of Global Accelerator Edge servers](https://docs.aws.amazon.com/global-accelerator/latest/dg/introduction-ip-ranges.html) in the *AWS Global Accelerator Developer Guide* for more information.


| Region | Region code | Public IP address range | 
| --- | --- | --- | 
| US East (N. Virginia) | us-east-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| US East (Ohio) | us-east-2 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| US West (Oregon) | us-west-2 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Asia Pacific (Mumbai) | ap-south-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Asia Pacific (Seoul) | ap-northeast-2 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Asia Pacific (Singapore) | ap-southeast-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Asia Pacific (Sydney) | ap-southeast-2 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Asia Pacific (Malaysia) | ap-southeast-5 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Asia Pacific (Tokyo) | ap-northeast-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Canada (Central) | ca-central-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Europe (Frankfurt) | eu-central-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Europe (Ireland) | eu-west-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Europe (London) | eu-west-2 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Europe (Paris) | eu-west-3 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| South America (São Paulo) | sa-east-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Africa (Cape Town) | af-south-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Israel (Tel Aviv) | il-central-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| AWS GovCloud (US-West) | us-gov-west-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| AWS GovCloud (US-East) | us-gov-east-1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 

## DCV gateway domain names
<a name="dns-wsp"></a>

The following table lists the DCV WorkSpace gateway domain names. These domains must be contactable, for the WorkSpaces client application to be able to access the WorkSpace DCV service. 


| Region | Domain | 
| --- | --- | 
| US East (N. Virginia) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| US West (Oregon) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Asia Pacific (Mumbai) | \$1.prod.ap-south-1.highlander.aws.a2z.com | 
| Asia Pacific (Seoul) | \$1.prod.ap-northeast-2.highlander.aws.a2z.com | 
| Asia Pacific (Singapore) | \$1.prod.ap-southeast-1.highlander.aws.a2z.com | 
| Asia Pacific (Sydney) | \$1.prod.ap-southeast-2.highlander.aws.a2z.com | 
| Asia Pacific (Tokyo) | \$1.prod.ap-northeast-1.highlander.aws.a2z.com | 
| Canada (Central) | \$1.prod.ca-central-1.highlander.aws.a2z.com | 
| Europe (Frankfurt) | \$1.prod.eu-central-1.highlander.aws.a2z.com | 
| Europe (Ireland) | \$1.prod.eu-west-1.highlander.aws.a2z.com | 
| Europe (London) | \$1.prod.eu-west-2.highlander.aws.a2z.com | 
| Europe (Paris) | \$1.prod.eu-west-3.highlander.aws.a2z.com | 
| South America (São Paulo) | \$1.prod.sa-east-1.highlander.aws.a2z.com | 
| Africa (Cape Town) | \$1.prod.af-south-1.highlander.aws.a2z.com | 
| Israel (Tel Aviv) | \$1.prod.il-central-1.highlander.aws.a2z.com | 
| AWS GovCloud (US-West) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| AWS GovCloud (US-East) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

## DCV PrivateLink domain names
<a name="dns-wsp-privatelink"></a>

If you use VPC endpoints for WorkSpaces streaming, the following domains must be allowed through your firewall or proxy. Replace <region> with your AWS Region (for example, us-east-1).


| DNS Name Type | Domain | 
| --- | --- | 
| Unique publicly resolvable DNS name | \$1.prod.highlander.<region>.vpce.amazonaws.com | 
| Generic private DNS name | privatelink.prod.<region>.highlander.aws.a2z.com | 

## Network interfaces
<a name="network-interfaces"></a>

Each WorkSpace has the following network interfaces:
+ The primary network interface (eth1) provides connectivity to the resources within your VPC and on the internet, and is used to join the WorkSpace to the directory.
+ The management network interface (eth0) is connected to a secure WorkSpaces management network. It is used for interactive streaming of the WorkSpace desktop to WorkSpaces clients, and to allow WorkSpaces to manage the WorkSpace.

WorkSpaces selects the IP address for the management network interface from various address ranges, depending on the Region that the WorkSpaces are created in. When a directory is registered, WorkSpaces tests the VPC CIDR and the route tables in your VPC to determine if these address ranges create a conflict. If a conflict is found in all available address ranges in the Region, an error message is displayed and the directory is not registered. If you change the route tables in your VPC after the directory is registered, you might cause a conflict.

**Warning**  
Do not modify or delete any of the network interfaces that are attached to a WorkSpace. Doing so might cause the WorkSpace to become unreachable or lose internet access. For example, if you have [enabled automatic assignment of Elastic IP addresses](automatic-assignment.md) at the directory level, an [ Elastic IP address](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-eips.html) (from the Amazon-provided pool) is assigned to your WorkSpace when it is launched. However, if you associate an Elastic IP address that you own to a WorkSpace, and then you later disassociate that Elastic IP address from the WorkSpace, the WorkSpace loses its public IP address, and it doesn't automatically get a new one from the Amazon-provided pool.  
To associate a new public IP address from the Amazon-provided pool with the WorkSpace, you must [rebuild the WorkSpace](rebuild-workspace.md). If you don't want to rebuild the WorkSpace, you must associate another Elastic IP address that you own to the WorkSpace.

### Management interface IP ranges
<a name="management-ip-ranges"></a>

The following table lists the IP address ranges used for the management network interface.

**Note**  
**If you're using Bring Your Own License (BYOL) Windows WorkSpaces**, the IP address ranges in the following table do not apply. Instead, PCoIP BYOL WorkSpaces use the 54.239.224.0/20 IP address range for management interface traffic in all AWS Regions. For DCV BYOL Windows WorkSpaces, both the 54.239.224.0/20 and 10.0.0.0/8 IP address ranges apply in all AWS Regions. (These IP address ranges are used in addition to the /16 CIDR block that you select for management traffic for your BYOL WorkSpaces.)
**If you're using DCV WorkSpaces created from public bundles**, the IP address range 10.0.0.0/8 also applies for management interface traffic in all AWS Regions, in addition to the PCoIP/DCV ranges shown in the following table.


| Region | IP address range | 
| --- | --- | 
| US East (N. Virginia) | PCoIP/WSP: 172.31.0.0/16, 192.168.0.0/16, 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| US West (Oregon) | PCoIP/WSP: 172.31.0.0/16, 192.168.0.0/16, and 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Asia Pacific (Mumbai) | PCoIP/WSP: 192.168.0.0/16 WSP: 10.0.0.0/8 | 
| Asia Pacific (Seoul) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Asia Pacific (Singapore) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Asia Pacific (Sydney) | PCoIP/WSP: 172.31.0.0/16, 192.168.0.0/16, and 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Asia Pacific (Tokyo) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Canada (Central) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Europe (Frankfurt) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Europe (Ireland) | PCoIP/WSP: 172.31.0.0/16, 192.168.0.0/16, and 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Europe (London) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Europe (Paris) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| South America (São Paulo) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Africa (Cape Town) | PCoIP/WSP: 172.31.0.0/16 and 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| Israel (Tel Aviv) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 
| AWS GovCloud (US-West) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 and 192.169.0.0/16 | 
| AWS GovCloud (US-East) | PCoIP/WSP: 198.19.0.0/16 WSP: 10.0.0.0/8 | 

### Management interface ports
<a name="management_ports"></a>

The following ports must be open on the management network interface of all WorkSpaces:
+ Inbound TCP on port 4172. This is used for establishment of the streaming connection on the PCoIP protocol.
+ Inbound UDP on port 4172. This is used for streaming user input on the PCoIP protocol.
+ Inbound TCP on port 4489. This is used for access using the web client.
+ Inbound TCP on port 8200. This is used for management and configuration of the WorkSpace.
+ Inbound TCP on ports 8201-8250. These ports are used for establishment of the streaming connection and for streaming user input on the DCV protocol.
+ Inbound UDP on port 8220. This port is used for establishment of the streaming connection and for streaming user input on the DCV protocol
+ Outbound TCP on ports 8443 and 9997. This is used for access using the web client.
+ Outbound UDP on ports 3478, 4172, and 4195. This is used for access using the web client.
+ Outbound UDP on ports 50002 and 55002. This is used for streaming. If your firewall uses stateful filtering, the ephemeral ports 50002 and 55002 are automatically opened to allow return communication. If your firewall uses stateless filtering, you must open ephemeral ports 49152 - 65535 to allow return communication.
+ Outbound TCP on port 80, as defined in [ Management interface IP ranges](https://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html#management-ip-ranges), to IP address 169.254.169.254 for access to the EC2 metadata service. Any HTTP proxy assigned to your WorkSpaces must also exclude 169.254.169.254.
+ Outbound TCP on port 1688 to IP addresses 169.254.169.250 and 169.254.169.251 to allow access to Microsoft KMS for Windows activation for Workspaces that are based on public bundles. If you're using Bring Your Own License (BYOL) Windows WorkSpaces, you must allow access to your own KMS servers for Windows activation.
+ Outbound TCP on port 1688 to IP address 54.239.236.220 to allow access to Microsoft KMS for Office activation for BYOL WorkSpaces.

  If you're using Office through one of the WorkSpaces public bundles, the IP address for Microsoft KMS for Office activation varies. To determine that IP address, find the IP address for the management interface of the WorkSpace, and then replace the last two octets with `64.250`. For example, if the IP address of the management interface is 192.168.3.5, the IP address for Microsoft KMS Office activation is 192.168.64.250.
+ Outbound TCP to IP address 127.0.0.2 for DCV WorkSpaces when the WorkSpace host is configured to use a proxy server.
+ Communications originating from loopback address 127.0.01.

Under normal circumstances, the WorkSpaces service configures these ports for your WorkSpaces. If any security or firewall software is installed on a WorkSpace that blocks any of these ports, the WorkSpace may not function correctly or may be unreachable.

### Primary interface ports
<a name="primary_ports"></a>

No matter which type of directory you have, the following ports must be open on the primary network interface of all WorkSpaces:
+ For internet connectivity, the following ports must be open outbound to all destinations and inbound from the WorkSpaces VPC. You need to add these manually to the security group for your WorkSpaces if you want them to have internet access.
  + TCP 80 (HTTP)
  + TCP 443 (HTTPS)
+ To communicate with the directory controllers, the following ports must be open between your WorkSpaces VPC and your directory controllers. For a Simple AD directory, the security group created by Directory Service will have these ports configured correctly. For an AD Connector directory, you might need to adjust the default security group for the VPC to open these ports.
  + TCP/UDP 53 - DNS
  + TCP/UDP 88 - Kerberos authentication
  + UDP 123 - NTP
  + TCP 135 - RPC
  + UDP 137-138 - Netlogon
  + TCP 139 - Netlogon
  + TCP/UDP 389 - LDAP
  + TCP/UDP 445 - SMB
  + TCP/UDP 636 - LDAPS (LDAP over TLS/SSL)
  + TCP 1024-65535 - Dynamic ports for RPC
  + TTCP 3268-3269 - Global Catalog

  If any security or firewall software is installed on a WorkSpace that blocks any of these ports, the WorkSpace may not function correctly or may be unreachable.

## IP address and port requirements by Region
<a name="ip-address-regions"></a>

### US East (N. Virginia)
<a name="us-east"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.us-east-1.amazonaws.com   | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain: https://ws-client-service.us-east-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints | https://smartcard.us-east-1.signin.aws | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domains: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domains: https://workspaces.us-east-1.amazonaws.com  | 
| Session Broker (PCM) | Domains: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-iad.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| DCV gateway domain name | \$1.prod.us-east-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### US West (Oregon)
<a name="us-west"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.us-west-2.amazonaws.com   | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain: https://ws-client-service.us-west-2.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints | https://smartcard.us-west-2.signin.aws | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domains: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domains: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domains: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-pdx.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 34.223.96.0/22 | 
| DCV gateway domain name | \$1.prod.us-west-2.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Asia Pacific (Mumbai)
<a name="ap-south"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.ap-south-1.amazonaws.com   | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain: https://ws-client-service.ap-south-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Web Access isn't currently available in the Asia Pacific (Mumbai) Region | 
| Health check hostname | drp-bom.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges | 13.126.243.0 - 13.126.243.255 | 
| DCV gateway servers IP address range | 65.1.156.0/22 | 
| DCV gateway domain name | \$1.prod.ap-south-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Asia Pacific (Seoul)
<a name="ap-northeast-2"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Device Metrics (for 1.0\$1 and 2.0\$1 WorkSpaces client applications) | https://device-metrics-us-2.amazon.com/ | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.ap-northeast-2.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain: https://ws-client-service.ap-northeast-2.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-icn.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 3.35.160.0/22 | 
| DCV gateway domain name | \$1.prod.ap-northeast-2.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Asia Pacific (Singapore)
<a name="ap-southeast-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.ap-southeast-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain: https://ws-client-service.ap-southeast-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-sin.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 13.212.132.0/22 | 
| DCV gateway domain name | \$1.prod.ap-southeast-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Asia Pacific (Sydney)
<a name="ap-southeast-2"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.ap-southeast-2.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.ap-southeast-2.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints | https://smartcard.ap-southeast-2.signin.aws | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-syd.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 3.25.248.0/22 | 
| DCV gateway domain name | \$1.prod.ap-southeast-2.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Asia Pacific (Tokyo)
<a name="ap-northeast-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.ap-northeast-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.ap-northeast-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints | https://smartcard.ap-northeast-1.signin.aws | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-nrt.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 3.114.164.0/22 | 
| DCV gateway domain name | \$1.prod.ap-northeast-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Canada (Central)
<a name="ca-central-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.ca-central-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.ca-central-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-yul.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 3.97.20.0/22 | 
| DCV gateway domain name | \$1.prod.ca-central-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Europe (Frankfurt)
<a name="eu-central-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.eu-central-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.eu-central-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-fra.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 18.192.216.0/22 | 
| DCV gateway domain name | \$1.prod.eu-central-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Europe (Ireland)
<a name="eu-west-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.eu-west-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.eu-west-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints | https://smartcard.eu-west-1.signin.aws | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-dub.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 3.248.176.0/22 | 
| DCV gateway domain name | \$1.prod.eu-west-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Europe (London)
<a name="eu-west-2"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.eu-west-2.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.eu-west-2.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-lhr.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 18.134.68.0/22 | 
| DCV gateway domain name | \$1.prod.eu-west-2.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Europe (Paris)
<a name="eu-west-3"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/Client  | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.eu-west-3.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.eu-west-3.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-cdg.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range |  51.17.72.0/22 | 
| DCV gateway domain name | \$1.prod.eu-west-3.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### South America (São Paulo)
<a name="sa-east-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.sa-east-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.sa-east-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-gru.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 15.228.64.0/22 | 
| DCV gateway domain name | \$1.prod.sa-east-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Africa (Cape Town)
<a name="sa-east-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.af-south-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.af-south-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-cpt.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 15.228.64.0/22 | 
| DCV gateway domain name | \$1.prod.af-south-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### Israel (Tel Aviv)
<a name="il-central-1"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://d2td7dqidlhjx7.cloudfront.net/  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: https://skylight-client-ds.il-central-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain:  https://ws-client-service.il-central-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://<directory id>.awsapps.com/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Web Access TURN Servers for PCoIP | Server: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-tlv.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 51.17.72.0/22 | 
| DCV gateway domain name | \$1.prod.il-central-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### AWS GovCloud (US-West) Region
<a name="govcloud-west-region"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://s3.amazonaws.com/workspaces-client-updates/prod/pdt/windows/WorkSpacesAppCast.xml  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: hhttps://skylight-client-ds.us-gov-west-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain: https://ws-client-service.us-gov-west-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints | https://smartcard.signin.amazonaws-us-gov.com | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://login.us-gov-home.awsapps.com/directory/<directory id>/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-pdt.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway domain name | \$1.prod.us-gov-west-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

### AWS GovCloud (US-East) Region
<a name="govcloud-east-region"></a>


**Domains and IP Addresses to add to your allowlist**  

| Category | Details | 
| --- | --- | 
| CAPTCHA | https://opfcaptcha-prod.s3.amazonaws.com/ | 
| Client Auto-update |  https://s3.amazonaws.com/workspaces-client-updates/prod/osu/windows/WorkSpacesAppCast.xml  | 
| Connectivity Check |  https://connectivity.amazonworkspaces.com/  | 
| Client Metrics (for 3.0\$1 WorkSpaces client applications) |  Domain: hhttps://skylight-client-ds.us-gov-east-1.amazonaws.com  | 
| Dynamic Messaging Service (for 3.0\$1 WorkSpaces client applications) |  Domain: https://ws-client-service.us-gov-east-1.amazonaws.com  | 
| Directory Settings |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Forrester Log Service  | https://fls-na.amazon.com/ | 
| Health Check (DRP) Servers | [Health check servers](#health_check) | 
| Pre-session Smart Card Authentication Endpoints | https://smartcard.signin.amazonaws-us-gov.com | 
| Registration Dependency (for Web Access and Teradici PCoIP Zero Clients) | https://s3.amazonaws.com | 
| User Login Pages | https://login.us-gov-home.awsapps.com/directory/<directory id>/ (where <directory id> is the customer's domain)  | 
| WS Broker |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| WorkSpaces API Endpoints |  Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html)  | 
| Session Broker (PCM) | Domain: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| Health check hostname | drp-osu.amazonworkspaces.com | 
| Health check IP addresses |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| PCoIP gateway servers public IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 
| DCV gateway servers IP address range | 18.254.148.0/22 | 
| DCV gateway domain name | \$1.prod.us-gov-east-1.highlander.aws.a2z.com | 
| Management interface IP address ranges |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html) | 

# Client network requirements for WorkSpaces Personal
<a name="workspaces-network-requirements"></a>

Your WorkSpaces users can connect to their WorkSpaces by using the client application for a supported device. Alternatively, they can use a web browser to connect to WorkSpaces that support this form of access. For a list of WorkSpaces that support web browser access, see "Which Amazon WorkSpaces bundles support web access?" in [ Client Access, Web Access, and User Experience](https://aws.amazon.com/workspaces/faqs/#Client_Access.2C_Web_Access.2C_and_User_Experience).

**Note**  
A web browser cannot be used to connect to Amazon Linux WorkSpaces.

**Important**  
Beginning October 1, 2020, customers will no longer be able to use the Amazon WorkSpaces Web Access client to connect to Windows 7 custom WorkSpaces or to Windows 7 Bring Your Own License (BYOL) WorkSpaces.

To provide your users with a good experience with their WorkSpaces, verify that their client devices meet the following network requirements:
+ The client device must have a broadband internet connection. We recommend planning for a minimum of 1 Mbps per simultaneous user watching a 480p video window. Depending on your user-quality requirements for video resolution, more bandwidth might be required.
+ The network that the client device is connected to, and any firewall on the client device, must have certain ports open to the IP address ranges for various AWS services. For more information, see [IP address and port requirements for WorkSpaces Personal](workspaces-port-requirements.md).
+ For the best performance for PCoIP, the round trip time (RTT) from the client's network to the Region that the WorkSpaces are in should be less than 100ms. If the RTT is between 100ms and 200ms, the user can access the WorkSpace, but performance is affected. If the RTT is between 200ms and 375ms, the performance is degraded. If the RTT exceeds 375ms, the WorkSpaces client connection is terminated.

  For the best performance for DCV, the RTT from the client's network to the Region that the WorkSpaces are in should be less than 250ms. If the RTT is between 250ms and 400ms, the user can access the WorkSpace, but the performance is degraded.

  To check the RTT to the various AWS Regions from your location, use the [Amazon WorkSpaces Connection Health Check](https://clients.amazonworkspaces.com/Health.html).
+ To use webcams with DCV, we recommend a minimum upload bandwidth of 1.7 megabits per second.
+ If users will access their WorkSpaces through a virtual private network (VPN), the connection must support a maximum transmission unit (MTU) of at least 1200 bytes.
**Note**  
You cannot access WorkSpaces through a VPN connected to your virtual private cloud (VPC). To access WorkSpaces using a VPN, internet connectivity (through the VPN's public IP addresses) is required, as described in [IP address and port requirements for WorkSpaces Personal](workspaces-port-requirements.md).
+ The clients require HTTPS access to WorkSpaces resources hosted by the service and Amazon Simple Storage Service (Amazon S3). The clients do not support proxy redirection at the application level. HTTPS access is required so that users can successfully complete registration and access their WorkSpaces.
+ To allow access from PCoIP zero client devices, you must be using a PCoIP protocol bundle for WorkSpaces. You must also enable Network Time Protocol (NTP) in Teradici. For more information, see [Set up PCoIP zero clients for WorkSpaces Personal](set-up-pcoip-zero-client.md).

You can verify that a client device meets the networking requirements as follows.

## To verify networking requirements for 3.0\$1 clients
<a name="verify-requirements-new-clients"></a>

1. Open your WorkSpaces client. If this is the first time you have opened the client, you are prompted to enter the registration code that you received in the invitation email.

1. Depending on which client you're using, do one of the following.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-network-requirements.html)

   The client application tests the network connection, ports, and round-trip time, and reports the results of these tests.

1. Close the **Network** dialog box to return to the sign-in page.

## To verify networking requirements for 1.0\$1 and 2.0\$1 clients
<a name="verify-requirements-legacy-clients"></a>

1. Open your WorkSpaces client. If this is the first time you have opened the client, you are prompted to enter the registration code that you received in the invitation email.

1. Choose **Network** in the lower-right corner of the client application. The client application tests the network connection, ports, and round-trip time, and reports the results of these tests.

1. Choose **Dismiss** to return to the sign-in page.

# Restrict access to trusted devices for WorkSpaces Personal
<a name="trusted-devices"></a>

By default, users can access their WorkSpaces from any supported device that is connected to the internet. If your company limits corporate data access to trusted devices (also known as managed devices), you can restrict WorkSpaces access to trusted devices with valid certificates.

**Note**  
This feature is currently available only when your WorkSpaces Personal directories are managed through Directory Service including Simple AD, AD Connector, and AWS Managed Microsoft AD directory.

When you enable this feature, WorkSpaces uses certificate-based authentication to determine whether a device is trusted. If the WorkSpaces client application can't verify that a device is trusted, it blocks attempts to log in or reconnect from the device.

For each directory, you can import up to two root certificates. If you import two root certificates, WorkSpaces presents them both to the client and the client finds the first valid matching certificate that chains up to either of the root certificates.

**Supported clients**
+ Android, running on Android or Android-compatible Chrome OS systems
+ macOS
+ Windows

**Important**  
This feature is not supported by the following clients:  
WorkSpaces client applications for Linux or iPad
Third-party clients, including but not limited to, Teradici PCoIP, RDP clients, and remote desktop applications.

**Note**  
When you enable access for specific clients, make sure that you block access for other device types that you don't need. For more information about how to do this, see Step 3.7 below.

## Step 1: Create the certificates
<a name="create-certificate"></a>

This feature requires two types of certificates: root certificates generated by an internal Certificate Authority (CA) and client certificates that chain up to a root certificate.

**Requirements**
+ Root certificates must be Base64-encoded certificate files in CRT, CERT, or PEM format.
+ Root certificates must satisfy the following regular expression pattern, which means that every encoded line, beside the last one, has to be exactly 64 characters long: `-{5}BEGIN CERTIFICATE-{5}\u000D?\u000A([A-Za-z0-9/+]{64} \u000D?\u000A)*[A-Za-z0-9/+]{1,64}={0,2}\u000D?\u000A-{5}END CERTIFICATE-{5}(\u000D?\u000A)`.
+ Device certificates must include a Common Name.
+ Device certificates must include the following extensions: `Key Usage: Digital Signature`, and `Enhanced Key Usage: Client Authentication`.
+ All the certificates in the chain from the device certificate to the trusted root Certificate Authority must be installed on the client device.
+ The maximum supported length of certificate chain is 4.
+ WorkSpaces does not currently support device revocation mechanisms, such as certificate revocation lists (CRL) or Online Certificate Status Protocol (OCSP), for client certificates.
+ Use a strong encryption algorithm. We recommend SHA256 with RSA, SHA256 with ECDSA, SHA384 with ECDSA, or SHA512 with ECDSA.
+ For macOS, if the device certificate is in the system keychain, we recommend that you authorize the WorkSpaces client application to access those certificates. Otherwise, users must enter keychain credentials when they log in or reconnect.

## Step 2: Deploy client certificates to the trusted devices
<a name="deploy-certificate"></a>

On the trusted devices for your users, you must install a certificate bundle that includes all the certificates in the chain from the device certificate to the trusted root Certificate Authority. You can use your preferred solution to install certificates to your fleet of client devices; for example, System Center Configuration Manager (SCCM) or mobile device management (MDM). Note that SCCM and MDM can optionally perform a security posture assessment to determine whether the devices meet your corporate policies to access WorkSpaces.

The WorkSpaces client applications search for certificates as follows:
+ Android - Go to **Settings**, choose **Security & location**, **Credentials**, then choose **Install from SD card**.
+ Android-compatible Chrome OS systems - Open Android settings and choose **Security & location**, **Credentials**, then choose **Install from SD card**.
+ macOS - Searches the keychain for client certificates.
+ Windows - Searches the user and root certificate stores for client certificates.

## Step 3: Configure the restriction
<a name="configure-restriction"></a>

After you have deployed the client certificates on the trusted devices, you can enable restricted access at the directory level. This requires the WorkSpaces client application to validate the certificate on a device before allowing a user to log in to a WorkSpace.

**To configure the restriction**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select the directory and then choose **Actions**, **Update Details**.

1. Expand **Access Control Options**.

1. Under **For each device type, specify which devices can access WorkSpaces**, choose **Trusted Devices**.

1. Import up to two root certificates. For each root certificate, do the following:

   1. Choose **Import**.

   1. Copy the body of the certificate to the form.

   1. Choose **Import**.

1. Specify whether other types of devices have access to WorkSpaces.

   1. Scroll down to the **Other Platforms** section. By default, WorkSpaces Linux clients are disabled, and users can access their WorkSpaces from their iOS devices, Android devices, Web Access, Chromebooks, and PCoIP zero client devices.

   1. Select the device types to enable and clear the device types to disable.

   1. To block access from all selected device types, choose **Block**.

1. Choose **Update and Exit**.

# Integrate SAML 2.0 with WorkSpaces Personal
<a name="amazon-workspaces-saml"></a>

**Note**  
SAML 2.0 is available only when your WorkSpaces Personal directories are managed through Directory Service including Simple AD, AD Connector, and AWS Managed Microsoft AD directory. The feature doesn't apply to directories that are managed by Amazon WorkSpaces, which normally use IAM Identity Center for user authentication instead of SAML 2.0 federation.

Integrating SAML 2.0 with your WorkSpaces for desktop session authentication allows your users to use their existing SAML 2.0 identity provider (IdP) credentials and authentication methods through their default web browser. By using your IdP to authenticate users for WorkSpaces, you can protect WorkSpaces by employing IdP features like multi-factor authentication and contextual access policies.

## Authentication workflow
<a name="authentication-workflow"></a>

The following sections describe the authentication workflow initiated by WorkSpaces client application, WorkSpaces Web Access, and a SAML 2.0 identity provider (IdP):
+ When the flow is initiated by the IdP. For example, when users choose an application in the IdP user portal in a web browser.
+ When the flow is initiated by the WorkSpaces client. For example, when users open the client application and sign in.
+ When the flow is initiated by WorkSpaces Web Access. For example, when users open Web Access in a browser and sign in.

In these examples, users enter `user@example.com`to sign in to the IdP. The IdP has a SAML 2.0 service provider application configured for a WorkSpaces directory and users are authorized for the WorkSpaces SAML 2.0 application. Users create a WorkSpace for their usernames, `user`, in a directory that's enabled for SAML 2.0 authentication. Additionally, users install the [WorkSpaces client application](https://clients.amazonworkspaces.com/) on their device or the user uses Web Access in a web browser.

**Identity provider (IdP)-initiated flow with client application**

The IdP-initiated flow allows users to automatically register the WorkSpaces client application on their devices without having to enter a WorkSpaces registration code. Users don't sign in to their WorkSpaces using the IdP-initiated flow. WorkSpaces authentication must originate from the client application.

1. Using their web browser, users sign in to the IdP.

1. After signing in to the IdP, users choose the WorkSpaces application from the IdP user portal.

1. Users are redirected to this page in the browser, and the WorkSpaces client application is opened automatically.   
![\[Opening WorkSpaces application redirection page\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/saml-redir.png)

1. The WorkSpaces client application is now registered and users can continue to sign by clicking **Continue to sign in to WorkSpaces**.

**Identity provider (IdP)-initiated flow with Web Access**

The IdP-initiated Web Access flow allows users to automatically register their WorkSpaces through a web browser without having to enter a WorkSpaces registration code. Users don't sign in to their WorkSpaces using the IdP-initiated flow. WorkSpaces authentication must originate from Web Access.

1. Using their web browser, users sign in to the IdP.

1. After signing in to the IdP, users click the WorkSpaces application from the IdP user portal.

1. Users are redirected to this page in the browser. To open WorkSpaces, choose **Amazon WorkSpaces in the browser**.  
![\[Opening WorkSpaces application redirection page\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/saml-redir.png)

1. The WorkSpaces client application is now registered and users can continue to sign in through WorkSpaces Web Access.

**WorkSpaces client-initiated flow**

The client-initiated flow allows users to sign in to their WorkSpaces after signing in to an IdP.

1. Users launch the WorkSpaces client application (if it isn't already running) and clicks **Continue to sign in to WorkSpaces**.

1. Users are redirected to their default web browser to sign in to the IdP. If the users are already signed in to the IdP in their browser, they don't need to sign in again and will skip this step.

1. Once signed in to the IdP, users are redirected to a pop up. Follow the prompts to allow your web browser to open the client application.  
![\[Open client application prompt.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/saml-open-client-app.png)

1. Users are redirected to the WorkSpaces client application to complete sign in to their WorkSpace. WorkSpaces usernames are populated automatically from the IdP SAML 2.0 assertion. When you use [ certificate-based authentication (CBA)](certificate-based-authentication.md) , users are automatically signed in.

1. Users are signed in to their WorkSpace.

**WorkSpaces Web Access-initiated flow**

The Web Access-initiated flow allows users to sign in to their WorkSpaces after signing in to an IdP.

1. Users launch the WorkSpaces Web Access and chooses **Sign in**.

1. In the same browser tab, users are redirected to IdP portal. If the users are already signed in to the IdP in their browser, they don't need to sign in again and can skip this step.

1. Once signed in to the IdP, users redirected to this page in the browser, and clicks **Log in to WorkSpaces**.

1. Users redirected to the WorkSpaces client application to complete sign in to their WorkSpace. WorkSpaces usernames are populated automatically from the IdP SAML 2.0 assertion. When you use [ certificate-based authentication (CBA)](certificate-based-authentication.md) , users are automatically signed in.

1. Users are signed in to their WorkSpace.

# Set up SAML 2.0 for WorkSpaces Personal
<a name="setting-up-saml"></a>

Enable WorkSpaces client application registration and signing in to WorkSpaces for your users by using their SAML 2.0 identity provider (IdP) credentials and authentication methods by setting up identity federation using SAML 2.0. To set up identity federation using SAML 2.0, use an IAM role and a relay state URL to configure your IdP and enable AWS. This grants your federated users access to a WorkSpaces directory. The relay state is the WorkSpaces directory endpoint to which users are forwarded after successfully signing in to AWS. 

**Topics**
+ [Requirements](#setting-up-saml-requirements)
+ [Prerequisites](#setting-up-saml-prerequisites)
+ [Step 1: Create a SAML identity provider in AWS IAM](#create-saml-identity-provider)
+ [Step 2: Create a SAML 2.0 federation IAM role](#create-saml-iam-role)
+ [Step 3: Embed an inline policy for the IAM role](#embed-inline-policy)
+ [Step 4: Configure your SAML 2.0 identity provider](#configure-saml-id-provider)
+ [Step 5: Create assertions for the SAML authentication response](#create-assertions-saml-auth)
+ [Step 6: Configure the relay state of your federation](#configure-relay-state)
+ [Step 7: Enable integration with SAML 2.0 on your WorkSpaces directory](#enable-integration-saml)

## Requirements
<a name="setting-up-saml-requirements"></a>
+ SAML 2.0 authentication is available in the following Regions:
  + US East (N. Virginia) Region
  + US West (Oregon) Region
  + Africa (Cape Town) Region
  + Asia Pacific (Mumbai) Region
  + Asia Pacific (Seoul) Region
  + Asia Pacific (Singapore) Region
  + Asia Pacific (Sydney) Region
  + Asia Pacific (Tokyo) Region
  + Canada (Central) Region
  + Europe (Frankfurt) Region
  + Europe (Ireland) Region
  + Europe (London) Region
  + South America (São Paulo) Region
  + Israel (Tel Aviv) Region
  + AWS GovCloud (US-West)
  + AWS GovCloud (US-East)
+ To use SAML 2.0 authentication with WorkSpaces,the IdP must support unsolicited IdP-initiated SSO with a deep link target resource or relay state endpoint URL. Examples of IdPs include ADFS, Azure AD, Duo Single Sign-On, Okta, PingFederate, and PingOne. Consult your IdP documentation for more information.
+ SAML 2.0 authentication will function with WorkSpaces launched using Simple AD, but this isn't recommended as Simple AD doesn't integrate with SAML 2.0 IdPs.
+ SAML 2.0 authentication is supported on the following WorkSpaces clients. Other client versions are unsupported for SAML 2.0 authentication. Open Amazon WorkSpaces [Client Downloads](https://clients.amazonworkspaces.com/) to find the latest versions:
  + Windows client application version 5.1.0.3029 or later
  + macOS client version 5.x or later
  + Linux client for Ubuntu 22.04 version 2024.1 or later, Ubuntu 20.04 version 24.1 or later
  + Web Access

  Other client versions won't be able to connect to WorkSpaces enabled for SAML 2.0 authentication unless fallback is enabled. For more information, see [ Enable SAML 2.0 authentication on the WorkSpaces directory.](https://d1.awsstatic.com/workspaces-saml-guide.pdf)

For step-by-step instructions to integrate SAML 2.0 with WorkSpaces using ADFS, Azure AD, Duo Single Sign-On, Okta, OneLogin, PingFederate and PingOne for Enterprise, review the [Amazon WorkSpaces SAML Authentication Implementation Guide](https://d1.awsstatic.com/workspaces-saml-guide.pdf).

## Prerequisites
<a name="setting-up-saml-prerequisites"></a>

Complete the following prerequisites before configuring your SAML 2.0 identity provider (IdP) connection to a WorkSpaces directory.

1. Configure your IdP to integrate user identities from the Microsoft Active Directory that is used with the WorkSpaces directory. For a user with a WorkSpace, the **sAMAccountName** and **email** attributes for the Active Directory user and the SAML claim values must match for the user to sign in to WorkSpaces using the IdP. For more information about integrating Active Directory with your IdP, consult your IdP documentation.

1. Configure your IdP to establish a trust relationship with AWS.
   + See [Integrating third-party SAML solution providers with AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml_3rd-party.html) for more information on configuring AWS federation. Relevant examples include IdP integration with AWS IAM to access the AWS management console.
   + Use your IdP to generate and download a federation metadata document that describes your organization as an IdP. This signed XML document is used to establish the relying party trust. Save this file to a location that you can access from the IAM console later.

1. Create or register a directory for WorkSpaces by using the WorkSpaces management console. For more information, see [Manage directories for WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/manage-workspaces-directory.html). SAML 2.0 authentication for WorkSpaces is supported for the following directory types:
   + AD Connector
   + AWS Managed Microsoft AD

1. Create a WorkSpace for a user who can sign in to the IdP using a supported directory type. You can create a WorkSpace using the WorkSpaces management console, AWS CLI, or WorkSpaces API. For more information, see [Launch a virtual desktop using WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html). 

## Step 1: Create a SAML identity provider in AWS IAM
<a name="create-saml-identity-provider"></a>

First, create a SAML IdP in AWS IAM. This IdP defines your organization's IdP-to-AWS trust relationship using the metadata document generated by the IdP software in your organization. For more information, see [ Creating and managing a SAML identity provider (Amazon Web Services Management Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html#idp-manage-identityprovider-console). For information about working with SAML IdPs in AWS GovCloud (US-West)and AWS GovCloud (US-East), see [AWS Identity and Access Management](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-iam.html). 

## Step 2: Create a SAML 2.0 federation IAM role
<a name="create-saml-iam-role"></a>

Next, create a SAML 2.0 federation IAM role. This step establishes a trust relationship between IAM and your organization's IdP, which identifies your IdP as a trusted entity for federation.

To create an IAM role for SAML IdP

1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **Roles** > **Create role**.

1.  For **Role type**, choose **SAML 2.0 federation**. 

1.  For **SAML Provider** select the SAML IdP that you created. 
**Important**  
Don't choose either of the two SAML 2.0 access methods, **Allow programmatic access only** or **Allow programmatic and Amazon Web Services Management Console access**.

1. For **Attribute**, choose **SAML:sub\$1type**.

1. For **Value** enter `persistent`. This value restricts role access to SAML user streaming requests that include a SAML subject type assertion with a value of persistent. If the SAML:sub\$1type is persistent, your IdP sends the same unique value for the NameID element in all SAML requests from a particular user. For more information about the SAML:sub\$1type assertion, see the **Uniquely identifying users in SAML-based federation** section in [ Using SAML-based federation for API access to AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html#CreatingSAML-configuring).

1. Review your SAML 2.0 trust information, confirming the correct trusted entity and condition, and then choose **Next: Permissions**. 

1. On the **Attach permissions policies** page, choose **Next: Tags**.

1. (Optional) Enter a key and value for each tag that you want to add. For more information, see [Tagging IAM users and roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html).

1. When you're done, choose **Next: Review**. You'll create and embed an inline policy for this role later.

1. For **Role name**, enter a name that identifies the purpose of this role. Because multiple entities might reference the role, you can't edit the role's name once it is created.

1. (Optional) For **Role description**, enter a description for the new role.

1. Review the role details and choose **Create role**.

1. Add the sts:TagSession permission to your new IAM role's trust policy. For more information, see [Passing session tags in AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html). In your new IAM role's details, choose the **Trust relationships** tab, and then choose **Edit trust relationship\$1**. When Edit Trust Relationship policy editor opens, add the **sts:TagSession\$1** permission, as follows:

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "Federated": "arn:aws:iam::111122223333:saml-provider/IDENTITY-PROVIDER"
               },
               "Action": [
                   "sts:AssumeRoleWithSAML",
                   "sts:TagSession"
               ],
               "Condition": {
                   "StringEquals": {
                       "SAML:aud": "https://signin.aws.amazon.com/saml"
                   }
               }
           }
       ]
   }
   ```

------

Replace `IDENTITY-PROVIDER` with the name of the SAML IdP you created in Step 1. Then choose **Update Trust Policy**.

## Step 3: Embed an inline policy for the IAM role
<a name="embed-inline-policy"></a>

Next, embed an inline IAM policy for the role that you created. When you embed an inline policy, the permissions in that policy can't be accidentally attached to the wrong principal entity. The inline policy provides federated users with access to the WorkSpaces directory.

**Important**  
IAM policies to manage access to AWS based on the source IP are not supported for the `workspaces:Stream` action. To manage IP access controls for WorkSpaces, use [IP access control groups](https://docs.aws.amazon.com/workspaces/latest/adminguide/amazon-workspaces-ip-access-control-groups.html). Additionally, when using SAML 2.0 authentication you can use IP access control policies if they are available from your SAML 2.0 IdP.

1. In the details for the IAM role that you created, choose the **Permissions** tab, and then add required permissions to the role's permissions policy. The **Create policy wizard** will start.

1. In **Create policy**, choose the **JSON** tab.

1. Copy and paste the following JSON policy into the JSON window. Then, modify the resource by entering your AWS Region Code, account ID, and directory ID. In the following policy, `"Action": "workspaces:Stream"` is the action that provides your WorkSpaces users with permissions to connect to their desktop sessions in the WorkSpaces directory.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "workspaces:Stream",
               "Resource": "arn:aws:workspaces:us-east-1:123456789012:directory/DIRECTORY-ID",
               "Condition": {
                   "StringEquals": {
                       "workspaces:userId": "${saml:sub}"
                   }
               }
           }
       ]
   }
   ```

------

   Replace `REGION-CODE` with the AWS Region where your WorkSpaces directory exists. Replace `DIRECTORY-ID` with the WorkSpaces directory ID, which can be found in the WorkSpaces management console. For resources in AWS GovCloud (US-West) or AWS GovCloud (US-East), use the following format for the ARN: `arn:aws-us-gov:workspaces:REGION-CODE:ACCOUNT-ID-WITHOUT-HYPHENS:directory/DIRECTORY-ID`.

1. When you're done, choose **Review policy**. The [Policy Validator](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_policy-validator.html) will report any syntax errors.

## Step 4: Configure your SAML 2.0 identity provider
<a name="configure-saml-id-provider"></a>

Next, depending on your SAML 2.0 IdP, you may need to manually update your IdP to trust AWS as a service provider by uploading the `saml-metadata.xml` file at [https://signin.aws.amazon.com/static/saml-metadata.xml](https://signin.aws.amazon.com/static/saml-metadata.xml) to your IdP. This step updates your IdP’s metadata. For some IdPs, the update may already be configured. If this is the case, proceed to the next step.

If this update isn't already configured in your IdP, review the documentation provided by your IdP for information about how to update the metadata. Some providers give you the option to type the URL, and the IdP obtains and installs the file for you. Others require you to download the file from the URL and then provide it as a local file.

**Important**  
At this time, you can also authorize users in your IdP to access the WorkSpaces application you have configured in your IdP. Users who are authorized to access the WorkSpaces application for your directory don't automatically have a WorkSpace created for them. Likewise, users that have a WorkSpace created for them are not automatically authorized to access the WorkSpaces application. To successfully connect to a WorkSpace using SAML 2.0 authentication, a user must be authorized by the IdP and must have a WorkSpace created.

**Note**  
If your end users will frequently switch between multiple different WorkSpaces user identities while using the same SAML 2.0 identity provider (IdP), ensure that your IdP is configured to force authentication (ForceAuthn) at each login attempt. This prevents your IdP from reusing an existing SSO session, which may otherwise cause authentication failures when your users are switching to another WorkSpace. Refer to your IdP's documentation for guidance on enabling the ForceAuthn (or equivalent) setting.

## Step 5: Create assertions for the SAML authentication response
<a name="create-assertions-saml-auth"></a>

Next, configure the information that your IdP sends to AWS as SAML attributes in its authentication response. Depending on your IdP, this is already configured, skip this step and continue to [ Step 6: Configure the relay state of your federation](https://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html#configure-relay-state).

If this information isn't already configured in your IdP, provide the following:
+ **SAML Subject NameID** – The unique identifier for the user who is signing in. The value must match the WorkSpaces user name, and is typically the **sAMAccountName** attribute for the Active Directory user.
+ **SAML Subject Type** (with a value set to `persistent`) – Setting the value to `persistent` ensures that your IdP sends the same unique value for the `NameID` element in all SAML requests from a particular user. Make sure that your IAM policy includes a condition to only allow SAML requests with a SAML sub\$1type set to `persistent`, as described in [ Step 2: Create a SAML 2.0 federation IAM role](https://docs.aws.amazon.com/appstream2/latest/developerguide/external-identity-providers-setting-up-saml.html#external-identity-providers-grantperms).
+ **`Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/Role`** – This element contains one or more `AttributeValue` elements that list the IAM role and SAML IdP to which the user is mapped by your IdP. The role and IdP are specified as a comma-delimited pair of ARNs. An example of the expected value is `arn:aws:iam::ACCOUNTNUMBER:role/ROLENAME,arn:aws:iam::ACCOUNTNUMBER:saml-provider/PROVIDERNAME`.
+ **`Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/RoleSessionName`** – This element contains one `AttributeValue` element that provides an identifier for the AWS temporary credentials that are issued for SSO. The value in the `AttributeValue` element must be between 2 and 64 characters long, can contain only alphanumeric characters, underscores, and the following characters: **\$1 . : / = \$1 - @**. It can't contain spaces. The value is typically an email address or a user principal name (UPN). It shouldn't be a value that includes a space, such as a user's display name.
+ **`Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email`** – This element contains one `AttributeValue` element that provides the email address of the user. The value must match the WorkSpaces user email address as defined in the WorkSpaces directory. Tag values may include combinations of letters, numbers, spaces, and **\$1 . : / = \$1 - @** characters. For more information, see [Rules for tagging in IAM and AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html#id_tags_rules) in the *IAM User Guide*.
+ **`Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/PrincipalTag:UserPrincipalName` (optional)** – This element contains one `AttributeValue` element that provides the Active Directory `userPrincipalName` for the user who is signing in. The value must be provided in the format of `username@domain.com`. This parameter is used with certificate-based authentication as the Subject Alternative Name in the end user certificate. For more information, see Certificate-Based Authentication.
+ **`Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/PrincipalTag:ObjectSid` (optional)** – This element contains one `AttributeValue` element that provides the Active Directory security identifier (SID) for the user who is signing in. This parameter is used with certificate-based authentication to enable strong mapping to the Active Directory user. For more information, see Certificate-Based Authentication.
+ **`Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/PrincipalTag:ClientUserName` (optional)** – This element contains one `AttributeValue` element that provides an alternative user name format. Use this attribute if you have use cases that require user name formats such as `corp\username`, `corp.example.com\username`, or `username@corp.example.com` to login using the WorkSpaces client. Tag keys and values can include any combination of letters, numbers, spaces, and **\$1 : / . \$1 = @ -** characters. For more information, see [Rules for tagging in IAM and AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html#id_tags_rules) in the *IAM User Guide*. To claim `corp\username` or `corp.example.com\username` formats, replace **\$1** with **/**in the SAML assertion.
+ **`Attribute`element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:Domain (optional)** – This element contains one `AttributeValue` element that provides the Active Directory DNS fully qualified domain name (FQDN) for users signing in. This parameter is used with certificate-based authentication when the Active Directory `userPrincipalName` for the user contains an alternative suffix. The value must be provided in the `domain.com`, including any subdomains.
+ **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/SessionDuration (optional)** – This element contains one `AttributeValue` element that specifies the maximum amount of time that a federated streaming session for a user can remain active before reauthentication is required. The default value is 3600 seconds (60 minutes). For more information, see the [ SAML `SessionDurationAttribute`](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-session-duration). 
**Note**  
Although `SessionDuration` is an optional attribute, we recommend that you include it in the SAML response. If you don't specify this attribute, the session duration is set to a default value of 3600 seconds (60 minutes). WorkSpaces desktop sessions are disconnected after their session duration expires.

For more information about how to configure these elements, see [ Configuring SAML assertions for the authentication response](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html) in the *IAM User Guide*. For information about specific configuration requirements for your IdP, see your IdP's documentation.

## Step 6: Configure the relay state of your federation
<a name="configure-relay-state"></a>

Next, use your IdP to configure the relay state of your federation to point to the WorkSpaces directory relay state URL. After successful authentication by AWS, the user is directed to the WorkSpaces directory endpoint, defined as the relay state in the SAML authentication response.

The following is the relay state URL format:

```
https://relay-state-region-endpoint/sso-idp?registrationCode=registration-code
```

Construct your relay state URL from your WorkSpaces directory registration code and the relay state endpoint associated with the Region in which your directory is located. The registration code can be found in the WorkSpaces management console.

Optionally, if you are using cross-region redirection for WorkSpaces, you can substitute the registration code with the fully qualified domain name (FQDN) associated with directories in your primary and failover Regions. For more information, see [Cross-region redirection for Amazon WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/cross-region-redirection.html). When using cross-region redirection and SAML 2.0 authentication, both primary and failover directories need to be enabled for SAML 2.0 authentication and independently configured with the IdP, using the relay state endpoint associated with each Region. This will allow the FQDN to be configured correctly when users register their WorkSpaces client applications before signing in, and will allow users to authenticate during a failover event.

The following table lists the relay state endpoints for the Regions where WorkSpaces SAML 2.0 authentication is available.


**Regions where WorkSpaces SAML 2.0 authentication is available**  

| Region | Relay state endpoint | 
| --- | --- | 
| US East (N. Virginia) Region | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html) | 
| US West (Oregon) Region | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html) | 
| Africa (Cape Town) Region | workspaces.euc-sso.af-south-1.aws.amazon.com | 
| Asia Pacific (Mumbai) Region | workspaces.euc-sso.ap-south-1.aws.amazon.com | 
| Asia Pacific (Seoul) Region | workspaces.euc-sso.ap-northeast-2.aws.amazon.com | 
| Asia Pacific (Singapore) Region | workspaces.euc-sso.ap-southeast-1.aws.amazon.com | 
| Asia Pacific (Sydney) Region | workspaces.euc-sso.ap-southeast-2.aws.amazon.com | 
| Asia Pacific (Tokyo) Region | workspaces.euc-sso.ap-northeast-1.aws.amazon.com | 
| Canada (Central) Region | workspaces.euc-sso.ca-central-1.aws.amazon.com | 
| Europe (Frankfurt) Region | workspaces.euc-sso.eu-central-1.aws.amazon.com | 
| Europe (Ireland) Region | workspaces.euc-sso.eu-west-1.aws.amazon.com | 
| Europe (London) Region | workspaces.euc-sso.eu-west-2.aws.amazon.com | 
| South America (São Paulo) Region | workspaces.euc-sso.sa-east-1.aws.amazon.com | 
| Israel (Tel Aviv) Region | workspaces.euc-sso.il-central-1.aws.amazon.com | 
| AWS GovCloud (US-West) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html)  For more information about, see [ Amazon WorkSpaces](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-workspaces.html) in the *AWS GovCloud (US) User Guide*.   | 
| AWS GovCloud (US-East) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html)  For more information about, see [ Amazon WorkSpaces](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-workspaces.html) in the *AWS GovCloud (US) User Guide*.   | 

With an identity provider (IdP)-initiated flow, you can opt to specify the client you want to use for SAML 2.0 federation. To do so, specify either `native` or `web` at end of the relay state URL, after `&client=`. When the parameter is specified in a relay state URL, the corresponding sessions will automatically start in the specified client.

## Step 7: Enable integration with SAML 2.0 on your WorkSpaces directory
<a name="enable-integration-saml"></a>

You can use the WorkSpaces console to enable SAML 2.0 authentication on the WorkSpaces directory.

**To enable integration with SAML 2.0**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose on the Directory ID for your WorkSpaces.

1. Under **Authentication**, choose **Edit**.

1. Choose **Edit SAML 2.0 Identity Provider**.

1. Check **Enable SAML 2.0 authentication**.

1. For the **User Access URL** and **IdP deep link parameter name**, enter values that are applicable to your IdP and the application you have configured in Step 1. The default value for the IdP deep link parameter name is “RelayState“ if you omit this parameter. The following table lists user access URL and parameter names that are unique to various identity providers for applications.   
**Domains and IP addresses to add to your allow list**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html)

   The user access URL is usually defined by the provider for unsolicited IdP-initiated SSO. A user can enter this URL in a web browser to federate directly to the SAML application. To test the user access URL and parameter values for your IdP, choose **Test**. Copy and paste the test URL to a private window in your current browser or another browser to test the SAML 2.0 logon without disrupting your current AWS management console session. When IdP-initiated flow opens, you can register your WorkSpaces client. For more information, see [ Identity provider (IdP)-initiated flow](https://docs.aws.amazon.com/workspaces/latest/adminguide/amazon-workspaces-saml.html).

1. Manage fallback settings by checking or unchecking **Allow clients that do not support SAML 2.0 to login**. Enable this setting to continue providing your users access to WorkSpaces using client types or versions that do not support SAML 2.0 or if users need time to upgrade to the latest client version.
**Note**  
This setting allows users to bypass SAML 2.0 and log in using directory authentication using older client versions.

1. To use SAML with the web client, enable Web Access. For more information, see [Enable and configure Amazon WorkSpaces Web Access](https://docs.aws.amazon.com/workspaces/latest/adminguide/web-access.html).
**Note**  
PCoIP with SAML is not supported on Web Access.

1. Choose **Save**. Your WorkSpaces directory is now enabled with SAML 2.0 integration. You can use the IdP-initiated and client application-initiated flows to register WorkSpaces client applications and sign in to WorkSpaces.

# Certificate-based authentication and WorkSpaces Personal
<a name="certificate-based-authentication"></a>

You can use certificate-based authentication with WorkSpaces to remove the user prompt for the Active Directory domain password. By using certificate-based authentication with your Active Directory domain, you can:
+ Rely on your SAML 2.0 identity provider to authenticate the user and provide SAML assertions to match the user in Active Directory.
+ Enable a single sign-on logon experience with fewer user prompts.
+ Enable passwordless authentication flows using your SAML 2.0 identity provider.

Certificate-based authentication uses AWS Private CA resources in your AWS account. AWS Private CA enables creation of private certificate authority (CA) hierarchies, including root and subordinate CAs. With AWS Private CA, you can create your own CA hierarchy and issue certificates with it for authenticating internal users. For more information, see the [AWS Private Certificate Authority User Guide](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html).

When using AWS Private CA for certificate-based authentication, WorkSpaces will request certificates for your users automatically during session authentication. Users are authenticated to Active Directory using a virtual smart card provisioned with the certificates.

Certificate-based authentication is supported with Windows WorkSpaces on DCV bundles using the latest WorkSpaces Web Access, Windows, and macOS client applications. Open Amazon WorkSpaces [Client downloads](https://clients.amazonworkspaces.com/) to find the latest versions: 
+ Windows client version 5.5.0 or later
+ macOS client version 5.6.0 or later

For more information on configuring certificate-based authentication with Amazon WorkSpaces, see [ How to configure certificate-based authentication for Amazon WorkSpaces](https://aws.amazon.com/blogs/desktop-and-application-streaming/how-to-configure-certificate-based-authentication-for-amazon-workspaces/) and [ Design considerations in highly regulated environments for Certificate Based Authentication with WorkSpaces Applications and WorkSpaces ](https://aws.amazon.com/blogs/desktop-and-application-streaming/design-considerations-in-highly-regulated-environments-for-certificate-based-authentication-with-appstream-2-0-workspaces/).

## Prerequisites
<a name="cert-based-auth-prerequesites"></a>

Complete the following steps before enabling certificate-based authentication.

1. Configure your WorkSpaces directory with SAML 2.0 integration to use certificate-based authentication. For more information, see [WorkSpaces Integration with SAML 2.0](https://docs.aws.amazon.com/workspaces/latest/adminguide/amazon-workspaces-saml.html).

1. Configure the `userPrincipalName` attribute in your SAML assertion. For more information, see [Create Assertions for the SAML Authentication Response](https://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html#create-assertions-saml-auth).

1. Configure the `ObjectSid` attribute in your SAML assertion. This is required to perform strong mapping to the Active Directory user. Certificate-based authentication will fail if the attribute does not match the Active Directory security identifier (SID) for user specified in the SAML\$1Subject `NameID`. For more information, see [Create Assertions for the SAML Authentication Response](https://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html#create-assertions-saml-auth).
**Note**  
According to [Microsoft KB5014754](https://support.microsoft.com/en-us/topic/kb5014754-certificate-based-authentication-changes-on-windows-domain-controllers-ad2c23b0-15d8-4340-a468-4d4f3b188f16), the `ObjectSid` attribute will become mandatory for certificate-based authentication after September 10, 2025. 

1. Add the [sts:TagSession](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) permission to your IAM role trust policy used with your SAML 2.0 configuration if it is not already present. This permission is required to use certificate-based authentication. For more information, see [Create a SAML 2.0 Federation IAM Role](https://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html#create-saml-iam-role).

1. Create a private certificate authority (CA) using AWS Private CA if you do not have one configured with your Active Directory. AWS Private CA is required to use certificate-based authentication. For more information, see [Planning your AWS Private CA deployment](https://docs.aws.amazon.com/privateca/latest/userguide/PcaPlanning.html) and follow the guidance to configure a CA for certificate-based authentication. The following AWS Private CA settings are the most common for certificate-based authentication use cases:

   1. CA type options:

      1. Short-lived certificate CA usage mode (recommended if you are only using the CA to issue end user certificates for certificate-based authentication)

      1. Single level hierarchy with a Root CA (alternatively, choose a subordinate CA if you want to integrate with an existing CA hierarchy)

   1. Key algorithm options: RSA 2048

   1. Subject distinguished name options: Use any combination of options to identify the CA in your Active Directory Trusted Root Certification Authorities store.

   1. Certificate revocation options: CRL distribution
**Note**  
Certificate-based authentication requires an online CRL distribution point accessible from desktops and the domain controller. This requires unauthenticated access to the Amazon S3 bucket configured for Private CA CRL entries, or a CloudFront distribution that will have access to the S3 bucket if it is blocking public access. For more information on these options, see [Planning a certificate revocation list (CRL)](https://docs.aws.amazon.com/privateca/latest/userguide/crl-planning.html#s3-bpa).

1. Tag your private CA with a key entitled `euc-private-ca` to designate the CA for use with EUC certificate-based authentication. The key does not require a value. For more information, see [Managing tags for your private CA](https://docs.aws.amazon.com/privateca/latest/userguide/PcaCaTagging.html).

1. Certificate-based authentication utilizes virtual smart cards for logon. Following the [Guidelines for enabling smart card logon with third-party certification authorities](https://learn.microsoft.com/en-us/troubleshoot/windows-server/windows-security/enabling-smart-card-logon-third-party-certification-authorities) in Active Directory, perform the following steps:
   + Configure domain controllers with a domain controller certificate to authenticate smart card users. If you have an Active Directory Certificate Services enterprise CA configured in your Active Directory, domain controllers are automatically enrolled with certificates to enable smart card logon. If you don't have Active Directory Certificate Services, see [Requirements for domain controller certificates from a third-party CA](https://learn.microsoft.com/en-US/troubleshoot/windows-server/windows-security/requirements-domain-controller). You can create a domain controller certificate with AWS Private CA. If you do this, don't use a private CA configured for short-lived certificates.
**Note**  
If you are using AWS Managed Microsoft AD, you can configure Certificate Services on an EC2 instance to satisfy the requirement for domain controller certificates. See [AWS Launch Wizard](https://docs.aws.amazon.com/launchwizard/latest/userguide/launch-wizard-ad-deploying-new-vpc.html) for example deployments of AWS Managed Microsoft AD configured with Active Directory Certificate Services. AWS Private CA can be configured as a subordinate to the Active Directory Certificate Services CA, or can be configured as its own root when using AWS Managed Microsoft AD.  
An additional configuration task with AWS Managed Microsoft AD and Active Directory Certificate Services is to create outbound rules from the controllers VPC security group to the EC2 instance running Certificate Services allowing TCP ports 135 and 49152-65535 to enable certificate autoenrollment. In addition, the EC2 instance running must allow inbound access on the same ports from domain instances, including domain controllers. For more information on locating the security group for AWS Managed Microsoft AD see [Configure your VPC subnets and security groups](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_tutorial_setup_trust_prepare_mad.html#tutorial_setup_trust_open_vpc).
   + On the AWS Private CA console or using the SDK or CLI, select your CA and under the CA certificate, export the CA private certificate. For more information, see [Exporting a private certificate](https://docs.aws.amazon.com/acm/latest/userguide/export-private.html).
   + Publish the CA to Active Directory. Logon to a domain controller or a domain-joined machine. Copy the CA private certificate to any `<path>\<file>` and run the following commands as a domain administrator. Alternatively, you can use Group Policy and the Microsoft PKI Health Tool (PKIView) tool to publish the CA. For more information, see [Configuration instructions](https://learn.microsoft.com/en-us/troubleshoot/windows-server/windows-security/enabling-smart-card-logon-third-party-certification-authorities#configuration-instructions).

     ```
     certutil -dspublish -f <path>\<file> RootCA
     certutil -dspublish -f  <path>\<file> NTAuthCA
     ```

     Ensure that the commands complete successfully, and then remove the private certificate file. Depending on Active Directory replication settings, it can take several minutes for the CA to be published to your domain controllers and desktop instances.
**Note**  
It is required that Active Directory distribute the CA to the Trusted Root Certification Authorities and Enterprise NTAuth stores automatically for WorkSpaces desktops when they are joined to the domain. 

## Enable certificate-based authentication
<a name="enable-cert-based-auth"></a>

Complete the following steps to enable certificate-based authentication.

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose the Directory ID for your WorkSpaces.

1. Under **Authentication**, click **Edit**.

1. Click **Edit Certificate-Based Authentication**.

1. Check **Enable Certificate-Based Authentication**.

1. Confirm that your private CA ARN is associated in the list. The private CA should be in the same AWS account and AWS Region, and must be tagged with a key entitled euc-private-ca to appear in the list.

1. Click **Save Changes**. Certificate-based authentication is now enabled.

1. Reboot your Windows WorkSpaces on DCV bundles for the changes to take effect. For more information, see [Reboot a WorkSpace](https://docs.aws.amazon.com/workspaces/latest/adminguide/reboot-workspaces.html).

1. After rebooting, when users authenticate via SAML 2.0 using a supported client, they will no longer receive a prompt for the domain password.

**Note**  
When certificate-based authentication is enabled to sign in to WorkSpaces, users are not prompted for multi-factor authentication (MFA) even if enabled on the Directory. When using certificate-based authentication, MFA can be enabled through your SAML 2.0 identity provider. For more information on AWS Directory Service MFA, see [Multi-factor authentication (AD Connector)](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_mfa.html) or [Enable multi-factor authentication for AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_mfa.html#supportedamazonapps). 

## Manage certificate-based authentication
<a name="manage-cert-based-auth"></a>

**CA Certificate**  
In a typical configuration, the private CA certificate has a validity period of 10 years. See [Managing the private CA lifecycle](https://docs.aws.amazon.com/privateca/latest/userguide/ca-lifecycle.html) for more information on replacing a CA with an expired certificate, or reissuing the CA with a new validity period.

**End User Certificates**  
End user certificates issued by AWS Private CA for WorkSpaces certificate-based authentication don't require renewal or revocation. These certificates are short-lived. WorkSpaces automatically issues a new certificate every 24 hours. These end user certificates have a shorter validity period than a typical AWS Private CA CRL distribution. As a result, end user certificates don't need to be revoked and won't appear in a CRL.

**Audit Reports**  
You can create an audit report to list all of the certificates that your private CA has issued or revoked. For more information, see [Using audit reports with your private CA](https://docs.aws.amazon.com/privateca/latest/userguide/PcaAuditReport.html).

**Logging and Monitoring**  
You can use [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/) to record API calls to AWS Private CA by WorkSpaces. For more information, see [Using CloudTrail](https://docs.aws.amazon.com/privateca/latest/userguide/PcaCtIntro.html). In [CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) you can view `GetCertificate` and `IssueCertificate` event names from `acm-pca.amazonaws.com` event source made by the WorkSpaces `EcmAssumeRoleSession` user name. These events will be recorded for every EUC certificate-based authentication request.

## Enable cross-account PCA sharing
<a name="enable-pca-sharing"></a>

 When you use Private CA cross-account sharing, you can grant other accounts permissions to use a centralized CA, which removes the needs for a Private CA in every account. The CA can generate and issue certificates by using [AWS Resource Access Manager](https://aws.amazon.com/ram/) to manage permissions. Private CA cross-account sharing can be used with WorkSpaces certificate-based Authentication (CBA) within the same AWS Region. 

**To use a shared Private CA resource with WorkSpaces CBA**

1. Configure the Private CA for CBA in a centralized AWS account. For more information, see [Certificate-based authentication and WorkSpaces Personal](#certificate-based-authentication).

1.  Share the Private CA with the resource AWS accounts where WorkSpaces resources utilize CBA by following the steps in [ How to use AWS RAM to share your ACM Private CA cross-account](https://aws.amazon.com/blogs/security/how-to-use-aws-ram-to-share-your-acm-private-ca-cross-account/). You don't need to complete step 3 to create a certificate. You can either share the Private CA with individual AWS accounts, or share through AWS Organizations. To share with individual accounts, you need to accept the shared Private CA in your resource account by using the Resource Access Manager (RAM) console or APIs. When configuring the share, confirm that the RAM resource share for the Private CA in the resource account is using the `AWSRAMBlankEndEntityCertificateAPICSRPassthroughIssuanceCertificateAuthority` managed permission template. This template aligns with the PCA template used by the WorkSpaces service role when issuing CBA certificates. 

1. After the share is successful, you should be able to view the shared Private CA by using the Private CA console in the resource account.

1. Use the API or CLI to associate the Private CA ARN with CBA in your WorkSpaces directory properties. At this time, the WorkSpaces console doesn't support selection of shared Private CA ARNs. Example CLI commands:

   ```
   aws workspaces modify-certificate-based-auth-properties —resource-id <value> —certificate-based-auth-properties Status=<value>,CertificateAuthorityArn=<value>
   ```

# Access Microsoft Entra ID-joined WorkSpaces Personal
<a name="access-entra-id"></a>

You can create Windows 10 or 11 BYOL personal WorkSpaces that are Microsoft Entra ID-joined and enrolled to Intune. For more details, see [Create a dedicated Microsoft Entra ID directory with WorkSpaces Personal](launch-entra-id.md). 

## Authentication workflow
<a name="authentication-workflow-entra"></a>

The following sections describe the authentication workflow initiated by WorkSpaces client application, WorkSpaces Web Access, and a SAML 2.0 identity provider (IdP), Microsoft Entra ID:
+ When the flow is initiated by the IdP. For example, when users choose an application in the Entra ID’s user portal in a web browser..
+ When the flow is initiated by the WorkSpaces client. For example, when users open the client application and sign in.
+ When the flow is initiated by WorkSpaces Web Access. For example, when users open Web Access in a browser and sign in.

In these examples, users enter `user@example.onmicrosoft.com`to sign in to the IdP. On Entra ID, an enterprise application is configured to integrate with IAM Identity Center. Users create a WorkSpace for their user names in a directory that uses IAM Identity Center as the identity source to connect to an Entra ID tenant. Additionally, users install the [WorkSpaces client application](https://clients.amazonworkspaces.com/) on their device or the user uses Web Access in a web browser.

**Identity provider (IdP)-initiated flow with client application**

The IdP-initiated flow allows users to automatically register the WorkSpaces client application on their devices without having to enter a WorkSpaces registration code. Users don't sign in to their WorkSpaces using the IdP-initiated flow. WorkSpaces authentication must originate from the client application.

1. Using their web browser, users sign in to the IdP (Microsoft Entra ID).

1. After signing in to the IdP, users choose the AWS IAM Identity Center application from the IdP user portal.

1. Users are redirected to the AWS access portal in the browser. Then, users choose the WorkSpaces icon.

1. Users are redirected to the page below and the WorkSpaces client application is opened automatically. Choose **Open Amazon WorkSpaces app** if the client application doesn't opened automatically.  
![\[Opening WorkSpaces application redirection page\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/saml-redir.png)

1. The WorkSpaces client application is now registered and users can continue to sign by clicking **Continue to sign in to WorkSpaces**.

**Identity provider (IdP)-initiated flow with Web Access**

The IdP-initiated Web Access flow allows users to automatically register their WorkSpaces through a web browser without having to enter a WorkSpaces registration code. Users don't sign in to their WorkSpaces using the IdP-initiated flow. WorkSpaces authentication must originate from Web Access.

1. Using their web browser, users sign in to the IdP.

1. After signing in to the IdP, users click the AWS IAM Identity Center application from the IdP user portal.

1. Users are redirected to AWS access portal in the browser. Then, users choose the WorkSpaces icon.

1. Users are redirected to this page in the browser. To open WorkSpaces, choose **Amazon WorkSpaces in the browser**.  
![\[Opening WorkSpaces application redirection page\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/saml-redir.png)

1. The WorkSpaces client application is now registered and users can continue to sign in through WorkSpaces Web Access.

**WorkSpaces client-initiated flow**

The client-initiated flow allows users to sign in to their WorkSpaces after signing in to an IdP.

1. Users launch the WorkSpaces client application (if it isn't already running) and clicks **Continue to sign in to WorkSpaces**.

1. Users are redirected to their default web browser to sign in to the IdP. If the users are already signed in to the IdP in their browser, they don't need to sign in again and will skip this step.

1. Once signed in to the IdP, users are redirected to a pop up. Follow the prompts to allow your web browser to open the client application.

1. Users are redirected to the WorkSpaces client application, on Windows login screen.

1. Users complete sign-in to Windows using their Entra ID username and credentials.

**WorkSpaces Web Access-initiated flow**

The Web Access-initiated flow allows users to sign in to their WorkSpaces after signing in to an IdP.

1. Users launch the WorkSpaces Web Access and chooses **Sign in**.

1. In the same browser tab, users are redirected to IdP portal. If the users are already signed in to the IdP in their browser, they don't need to sign in again and can skip this step.

1. Once signed in to the IdP, users redirected to this page in the browser, and clicks **Log in to WorkSpaces**.

1. Users are redirected to the WorkSpaces client application, on the Windows login screen.

1. Users complete sign-in to Windows using their Entra ID username and credentials.

## First-time user experience
<a name="first-time-entra"></a>

If you're logging in for the first time to a Microsoft Entra ID-joined Windows WorkSpaces, you must go through the out-of-box experience (OOBE). During OOBE, the WorkSpaces are joined to Entra ID. You can customize the OOBE experience by configuring the Autopilot profile assigned to the Microsoft Intune device group that you create for your WorkSpaces. For more information, see [Step 3: Configure Windows Autopilot user-driven mode](launch-entra-id.md#entra-step-3).

# Use smart cards for authentication in WorkSpaces Personal
<a name="smart-cards"></a>

Windows and Linux WorkSpaces on DCV bundles allow the use of [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card) and [Personal Identity Verification (PIV)](https://www.idmanagement.gov/university/piv/) smart cards for authentication.

Amazon WorkSpaces supports the use of smart cards for both *pre-session authentication* and *in-session authentication*. Pre-session authentication refers to smart card authentication that's performed while users are logging in to their WorkSpaces. In-session authentication refers to authentication that's performed after logging in.

For example, users can use smart cards for in-session authentication while working with web browsers and applications. They can also use smart cards for actions that require administrative permissions. For example, if the user has administrative permissions on their Linux WorkSpace, they can use smart cards to authenticate themselves when running `sudo` and `sudo -i` commands. 

**Topics**
+ [Requirements](#smart-cards-requirements)
+ [Limitations](#smart-cards-limitations)
+ [Directory configuration](#smart-cards-directory-config)
+ [Enable smart cards for Windows WorkSpaces](#smart-cards-windows-workspaces)
+ [Enable smart cards for Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces](#smart-cards-linux-workspaces)
+ [Enable smart cards for Amazon Linux 2 WorkSpaces](#smart-cards-amazon-linux-workspaces)

## Requirements
<a name="smart-cards-requirements"></a>
+ An Active Directory Connector (AD Connector) directory is required for pre-session authentication. AD Connector uses certificate-based mutual Transport Layer Security (mutual TLS) authentication to authenticate users to Active Directory using a hardware or software-based smart card certificate. For more information about how to configure your AD Connector and your on-premises directory, see [Directory configuration](#smart-cards-directory-config).
+ To use a smart card with a Windows or Linux WorkSpace, the user must use the Amazon WorkSpaces Windows client version 3.1.1 or later, WorkSpaces macOS client version 3.1.5 or later, or WorkSpaces Ubuntu 22.04 client version 2024.1 or later (smart card authentication is not supported with WorkSpaces Ubuntu 20.04 client). For more information about using smart cards with the Windows and macOS clients, see [ Smart Card Support](https://docs.aws.amazon.com/workspaces/latest/userguide/smart_card_support.html) in the *Amazon WorkSpaces User Guide*. 
+ The root CA and smart card certificates must meet certain requirements. For more information, see [ Enable mTLS authentication in AD Connector for use with smart cards](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ad_connector_clientauth.html) in the *AWS Directory Service Administration Guide* and [ Certificate Requirements](https://docs.microsoft.com/en-us/windows/security/identity-protection/smart-cards/smart-card-certificate-requirements-and-enumeration#certificate-requirements) in the Microsoft documentation. 

  In addition to those requirements, user certificates employed for smart card authentication to Amazon WorkSpaces must include the following attributes:
  + The AD user's userPrincipalName (UPN) in the subjectAltName (SAN) field of the certificate. We recommend issuing smart card certificates for the user's default UPN.
**Note**  
Amazon Linux 2 WorkSpaces rely on UPN for certificate-to-user mapping. Newer Linux WorkSpaces, like Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces, support more secure [mapping methods](https://www.idmanagement.gov/implement/scl-windows/#step-4---account-linking).
  + The Client Authentication (1.3.6.1.5.5.7.3.2) Extended Key Usage (EKU) attribute.
  + The Smart Card Logon (1.3.6.1.4.1.311.20.2.2) EKU attribute.
+ For pre-session authentication, Online Certificate Status Protocol (OCSP) is required for certificate revocation checking. For in-session authentication, OCSP is recommended, but not required.
**Note**  
Ubuntu WorkSpaces, Rocky Linux WorkSpaces, and Red Hat Enterprise Linux WorkSpaces require OCSP for in-session authentication by default, and OCSP verification in these systems requires the OCSP responder to have NONCE extension enabled to prevent replay attacks. To disable NONCE extension, in-session OCSP verification must be disabled altogether. To disable OCSP verification in Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces, create a new file `/etc/sssd/conf.d/disable-ocsp.conf`with the following content:   

  ```
  [sssd]
  certificate_verification = no_ocsp
  ```

## Limitations
<a name="smart-cards-limitations"></a>
+ Only the WorkSpaces Windows client application version 3.1.1 or later, the WorkSpaces macOS client application version 3.1.5 or later, and WorkSpaces Ubuntu 22.04 client application version 2024.1 or later are currently supported for smart card authentication. WorkSpaces Ubuntu 20.04 or earlier client application is not supported for smart card authentication.
+ The WorkSpaces Windows client application 3.1.1 or later supports smart cards only when the client is running on a 64-bit version of Windows.
+ Only AD Connector directories are currently supported for smart card authentication.
+ In-session authentication is available in all Regions where DCV is supported. Pre-session authentication is available in the following Regions:
  + Asia Pacific (Sydney) Region
  + Asia Pacific (Tokyo) Region
  + Europe (Ireland) Region
  + AWS GovCloud (US-East) Region
  + AWS GovCloud (US-West) Region
  + US East (N. Virginia) Region
  + US West (Oregon) Region
+ For in-session authentication and pre-session authentication on Linux or Windows WorkSpaces, only one smart card is currently allowed at a time. Simultaneous use of multiple cards may work, but is not supported.
+ For pre-session authentication, enabling both smart card authentication and sign-in authentication on the same directory is not currently supported.
+ Only CAC and PIV cards are supported at this time. Other types of hardware or software-based smart cards might also work, but they haven't been fully tested for use with DCV.

## Directory configuration
<a name="smart-cards-directory-config"></a>

To enable smart card authentication, you must configure your AD Connector directory and your on-premises directory in the following manner.

**AD Connector directory configuration**  
Before you begin, make sure your AD Connector directory has been set up as described in [ AD Connector Prerequisites](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/prereq_connector.html) in the *AWS Directory Service Administration Guide*. In particular, make sure that you have opened up the necessary ports in your firewall. 

To finish configuring your AD Connector directory, follow the instructions in [ Enable mTLS authentication in AD Connector for use with smart cards](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ad_connector_clientauth.html) in the *AWS Directory Service Administration Guide*.

**Note**  
Smart card authentication requires Kerberos Constrained Delegation (KCD) to function properly. KCD requires the username portion of the AD Connector service account to match the sAMAccountName of the same user. A sAMAccountName can't exceed 20 characters.

**On-premises directory configuration**  
In addition to configuring your AD Connector directory:
+ Make sure that the certificates that are issued to the domain controllers for your on-premises directory have the "KDC Authentication" extended key usage (EKU) set. To do this, use the Active Directory Domain Services (AD DS) default Kerberos Authentication certificate template. Do not use a Domain Controller certificate template or a Domain Controller Authentication certificate template because those templates don't contain the necessary settings for smart card authentication.
+ For Linux WorkSpaces, make sure that OCSP responder for the CA issuing smart card certificates has NONCE extension enabled. If it cannot be enabled, in-session OCSP verification will have to be disabled in Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces. To disable OCSP verification, create a new file `/etc/sssd/conf.d/disable-ocsp.conf`with the following content: 

  ```
  [sssd]
  certificate_verification = no_ocsp
  ```

## Enable smart cards for Windows WorkSpaces
<a name="smart-cards-windows-workspaces"></a>

For general guidance on how to enable smart card authentication on Windows, see [ Guidelines for enabling smart card logon with third-party certification authorities](https://docs.microsoft.com/troubleshoot/windows-server/windows-security/enabling-smart-card-logon-third-party-certification-authorities) in the Microsoft documentation.

**To detect the Windows lock screen and disconnect the session**  
To allow users to unlock Windows WorkSpaces that are enabled for smart card pre-session authentication when the screen is locked, you can enable Windows lock screen detection in users' sessions. When the Windows lock screen is detected, the WorkSpace session is disconnected, and the user can reconnect from the WorkSpaces client by using their smart card.

 You can enable disconnecting the session when the Windows lock screen is detected by using Group Policy settings. For more information, see [Configure disconnect session on screen lock for DCV](group_policy.md#gp_lock_screen_in_wsp).

**To enable in-session or pre-session authentication**  
By default, Windows WorkSpaces are not enabled to support the use of smart cards for pre-session or in-session authentication. If needed, you can enable in-session and pre-session authentication for Windows WorkSpaces by using Group Policy settings. For more information, see [Configure smart card redirection for DCV](group_policy.md#gp_smart_cards_in_wsp).

To use pre-session authentication, in addition to updating the Group Policy settings, you must also enable pre-session authentication through your AD Connector directory settings. For more information, follow the instructions in [ Enable mTLS authentication in AD Connector for use in smart cards](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ad_connector_clientauth.html) in the *AWS Directory Service Administration Guide*.

**To enable users to use smart cards in a browser**  
If your users are using Chrome as their browser, no special configuration is required to use smart cards.

If your users are using Firefox as their browser, you can enable your users to use smart cards in Firefox through Group Policy. You can use these [ Firefox Group Policy templates](https://github.com/mozilla/policy-templates/tree/master/windows) in GitHub.

For example, you can install the 64-bit version of [OpenSC](https://github.com/OpenSC/OpenSC/wiki) for Windows to support PKCS \$111, and then use the following Group Policy setting, where `NAME_OF_DEVICE` is whatever value you want to use to identify PKCS \$111, such as `OpenSC`, and where `PATH_TO_LIBRARY_FOR_DEVICE` is the path to the PKCS \$111 module. This path should point to a library with a .DLL extension, such as `C:\Program Files\OpenSC Project\OpenSC\pkcs11\onepin-opensc-pkcs11.dll`.

```
Software\Policies\Mozilla\Firefox\SecurityDevices\NAME_OF_DEVICE = PATH_TO_LIBRARY_FOR_DEVICE
```

**Tip**  
If you're using OpenSC, you can also load the OpenSC `pkcs11` module into Firefox by running the `pkcs11-register.exe` program. To run this program, either double-click the file at `C:\Program Files\OpenSC Project\OpenSC\tools\pkcs11-register.exe`, or open a Command Prompt window and run the following command:  

```
"C:\Program Files\OpenSC Project\OpenSC\tools\pkcs11-register.exe"
```
To verify that the OpenSC `pkcs11` module has been loaded into Firefox, do the following:  
If Firefox is already running, close it.
Open Firefox. Choose the menu button ![\[Firefox menu button\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/firefox-menu-button.png) in the upper-right corner, and then choose **Options**. 
On the **about:preferences** page, in the left navigation pane, choose **Privacy & Security**.
Under **Certificates**, choose **Security Devices**.
In the **Device Manager** dialog box, you should see **OpenSC smartcard framework (0.21)** in the left navigation, and it should have the following values when you select it:  
**Module**: `OpenSC smartcard framework (0.21)`  
**Path**: `C:\Program Files\OpenSC Project\OpenSC\pkcs11\onepin-opensc-pkcs11.dll`

**Troubleshooting**  
For information about troubleshooting smart cards, see [ Certificate and configuration problems](https://docs.microsoft.com/troubleshoot/windows-server/windows-security/enabling-smart-card-logon-third-party-certification-authorities#certificate-and-configuration-problems) in the Microsoft documentation. 

Some common issues that can cause problems:
+ Incorrect mapping of the slots to the certificates.
+ Having multiple certificates on the smart card that can match the user. Certificates are matched using the following criteria:
  + The root CA for the certificate.
  + The `<KU>` and `<EKU>` fields of the certificate.
  + The UPN in the certificate subject.
+ Having multiple certificates that have `<EKU>msScLogin` in their key usage.

In general, it's best to have only one certificate for smart card authentication that is mapped to the very first slot in the smart card.

The tools for managing the certificates and keys on the smart card (such as removing or remapping the certificates and keys) might be manufacturer-specific. For more information, see the documentation provided by the manufacturer of your smart cards.

## Enable smart cards for Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces
<a name="smart-cards-linux-workspaces"></a>

To enable the use of smart cards on Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces, you need to include the root and all intermediate CA certificates in the WorkSpace image for all CAs issuing smart cards, and for all CAs issuing domain controller certificates.

**To obtain your CA certificate:** You can obtain your CA certificate in several ways:
+ You can use a CA certificate bundle of a third-party certification authority. 
+ You can export your own CA certificate by using the Web Enrollment site, which is either `http://ip_address/certsrv` or `http://fqdn/certsrv`, where `ip_address` and `fqdn` are the IP address and the fully qualified domain name (FQDN) of the CA server. For more information about using the Web Enrollment site, see [ How to export a Root Certification Authority Certificate](https://docs.microsoft.com/troubleshoot/windows-server/identity/export-root-certification-authority-certificate) in the Microsoft documentation. 
+ You can use the following procedure to export the CA certificate from a CA server that is running Active Directory Certificate Services (AD CS). For information about installing AD CS, see [ Install the Certification Authority](https://docs.microsoft.com/windows-server/networking/core-network-guide/cncg/server-certs/install-the-certification-authority) in the Microsoft documentation. 

  1. Log into the CA server using an administrator account.

  1. From the Windows **Start** menu, open a command prompt window (**Start** > **Windows System** > **Command Prompt**). 

  1. Use the following command to export the CA certificate to a new file, where `rootca.cer` is the name of the new file:

     ```
     certutil -ca.cert rootca.cer
     ```

     For more information about running certutil, see [ certutil](https://docs.microsoft.com/windows-server/administration/windows-commands/certutil) in the Microsoft documentation.

  1. Use the following OpenSSL command to convert the exported CA certificate from DER format to PEM format, where *rootca* is the name of the certificate. For more information about OpenSSL, see [www.openssl.org](https://www.openssl.org/).

     ```
     openssl x509 -inform der -in rootca.cer -out /tmp/rootca.pem
     ```

**To add your CA certificates to your Linux WorkSpaces**

To assist you with enabling smart cards, we've added the `enable_smartcard` script to our Linux WorkSpaces DCV bundles. This script performs the following actions:
+ Imports your CA certificates into a private PEM bundle that defines the trust root for SSSD on Linux WorkSpaces).
+ Updates SSSD, PAM, and Kerberos configuration, which includes enabling `PKINIT` (Kerberos authentication using certificate instead of password) during WorkSpace provisioning.

The following procedure explains how to use the `enable_smartcard` script to import your CA certificates and to enable smart card authentication for your Linux WorkSpaces.

1. Create a new Linux WorkSpace with the DCV protocol enabled. When launching the WorkSpace in the Amazon WorkSpaces console, on the **Select Bundles** page, be sure to select **DCV** for the protocol, and then select one of the Linux WorkSpaces public bundles.

1. On the newly created WorkSpace, make sure `/etc/skylight.conf` file has `pam_smartcard = true` line in `[features]` section: 

   ```
   [features]
   pam_smartcard = true
   ```
**Note**  
If not all your users are yet configured to use strong `altSecurityIdentities` certificate mapping, you can also add `smartcard_weak_mapping = true` line to the same `[features]` section in `/etc/skylight.conf` to support legacy mapping methods, but we recommend migrating those users to use strong mapping methods as soon as possible instead. 

1. On the WorkSpace, run the following command as root, where `pem-path1`, `pem-path2`, etc., are the paths to files, each containing one of the CA certificates in the trust chain for the smart card and domain controller certificates. All of these files should be in PEM format and contain one certificate per file. Glob patterns can be used (e.g., `*.pem`)

   ```
   /usr/lib/skylight/enable_smartcard --ca-cert pem-path1 pem-path2 pem-path3 ...
   ```
**Note**  
Make sure additional dependency packages are installed on the WorkSpace before running the above command, using following commands as root.  
For Rocky Linux and Red Hat Enterprise Linux WorkSpaces:   

   ```
   dnf install sssd-dbus libsss_simpleifp sssd-tools krb5-pkinit opensc
   ```
 For Ubuntu WorkSpaces:   

   ```
   apt install krb5-pkinit opensc
   ```

1. Perform any additional customizations on the WorkSpace. For example, you might want to add a system-wide policy to [enable users to use smart cards in Firefox](#smart-cards-firefox-linux). (Chrome users must enable smart cards on their clients themselves. For more information, see [ Smart Card Support](https://docs.aws.amazon.com/workspaces/latest/userguide/smart_card_support.html) in the *Amazon WorkSpaces User Guide*.) 

1. [Create a custom WorkSpace image and bundle](create-custom-bundle.md) from the WorkSpace.

1. Use the new custom bundle to launch WorkSpaces for your users.

You can enable your users to use smart cards in Firefox by adding a SecurityDevices policy to your Linux WorkSpace image. For more information about adding system-wide policies to Firefox, see the [Mozilla policy templates](https://github.com/mozilla/policy-templates/releases) on GitHub.

**To enable users to use smart cards in Firefox**

1. On the WorkSpace that you're using to create your WorkSpace image, create a new file named `policies.json` in `PREFIX/firefox/distribution/`, where `PREFIX` is `/usr/lib64` on Fedora-based systems (Amazon Linux 2, Red Hat Enterprise Linux, and Rocky Linux WorkSpaces), and `/usr/lib` on Debian-based systems (Ubuntu WorkSpaces).

1. In the JSON file, add the following SecurityDevices policy, where `NAME_OF_DEVICE` is whatever value you want to use to identify the `pkcs` module. For example, you might want to use a value such as `"OpenSC"`:

   ```
   {
       "policies": {
           "SecurityDevices": {
               "NAME_OF_DEVICE": "PREFIX/opensc-pkcs11.so"
           }
       }
   }
   ```

**Troubleshooting**  
Troubleshooting of smart card authentication is easier when pre-session is set to use password authentication - during session provisioning Linux WorkSpaces automatically switch on-host authentication mode preference to password-based or smartcard-based depending on pre-session authentication method used. If there are any issues with smart card authentication, disconnecting and reconnecting using password pre-session authentication resets the workspace back to password on-host authentication. To manually switch Linux WorkSpaces instance to smart card authentication run `/usr/lib/skylight/resume_smartcard` command as root.

Linux WorkSpaces use OpenSC software for working with smart cards. That software comes with tools like `pkcs11-tool` and `pkcs15-tool` which can be useful in troubleshooting issues with smart cards. These tools can be used for inspecting smart card readers, individual tokens, and PIV slots or certificates on each smart card token.

An `openssl` command-line tool can be helpful in troubleshooting issues with trust chains, OCSP responders, or missing KUs/EKUs (key usage/extended key usage) flags, especially in combination with `pkcs15-tool`'s ability to extract public certificates from a smart card.

Common troubleshooting options:
+ Extract first (usually PIV slot 9A) certificate from the smart card and save it as `card-cert.pem`: `pkcs15-tool --read-certificate 1 > card-cert.pem`
+ Validate the extracted certificate against trust database on the WorkSpace: `openssl verify -verbose -CAfile /etc/sssd/pki/sssd_auth_ca_db.pem -cert card-cert.pem`
+ Get OCSP URL from the extracted smart card certificate: `openssl x509 -noout -ocsp_uri -in card-cert.pem`
+ Verify that OCSP response indicates certificate is valid and includes NONCE: `openssl ocsp -issuer /etc/sssd/pki/sssd_auth_ca_db.pem -CAfile /etc/sssd/pki/sssd_auth_ca_db.pem -cert card-cert.pem -text -url OCSP_URI`, where *OCSP\$1URI* is the OCSP URL from above.
+ Check if domain controller certificate is considered trusted: `openssl s_client -connect DC_HOSTNAME:636 -showcerts | openssl verify -verbose -CAfile /etc/sssd/pki/sssd_auth_ca_db.pem`, where *DC\$1HOSTNAME* is the host name of one of the domain controllers in your Active Directory domain.
+ Confirm domain controller certificate has KDC Authentication EKU (extended key usage) set: `openssl s_client -connect DC_HOSTNAME:636 -showcerts | openssl x509 -noout -text`.
+ Attempt manual PKINIT to see if there are any error codes that can be used to narrow down the problem: `KRB5_TRACE=/dev/stdout kinit -X X509_user_identity=PKCS11:opensc-pkcs11.so:certid=01 -V`, where *01* is the number of one of the four main PIV slots on the card - `01` for `9A`, `02` for `9C`, etc. Most cards will have certificate meant for user authentication in slot 9A.
+ Check if system is able to map smart card certificate to an AD user (execute as root): `dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe/Users org.freedesktop.sssd.infopipe.Users.FindByCertificate string:"$(<card-cert.pem)"`. This can be combined with enabling debug logging for SSSD.

The most common known issues:
+ Incomplete trust chain for the smart card certificate - when importing certificates using `enable_smartcard` script the full list of all root and intermediate CA certificates must to be provided. The `enable_smartcard` tool will show an error if not all imported certificates are trusted because of missing from the list root CA certificate, but it cannot detect when either an entire trust chain or the innermost intermediate CA certificate in one of the trust chains is missing. In that situation it will import certificates without an error, yet either a smart card certificate or domain controller certificates may still be considered untrusted.
+ Missing trust chain for the domain controller certificates - if domain controller certificates are issued by a different CA than smart cards (e.g., in case of [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card)), that CA trust chain needs to be imported together with the smart card issuing CA certificates.
+ Lack of NONCE extension support in OCSP responder - Linux WorkSpaces require that OCSP responder of the smart card issuer has NONCE extension enabled. If it cannot be enabled, OCSP validation will have to be completely disabled.
+ Domain controller certificates are missing `KDC Authentication` EKU (OID 1.3.6.1.5.2.3.1) - for smart card authentication to work domain controller certificates need to be re-issued to include KDC Authentication EKU.
+ Domain controller certificates are expired - for smart card authentication to work domain controller certificates must remain up-to-date.
+ Smart card certificates are mapped to users in AD using weak mapping methods - traditionally, UPN field in subjectAltName attribute was used to map a certificate to a user in AD, being expected to match userPrincipalName attribute. This is no longer considered a secure mapping method and is disallowed by default. It is possible to re-enable it by passing `--allow-weak-mapping` argument to `enable_smartcard` command and adding `smartcard_weak_mapping = true` line to the `[features]` section in `/etc/skylight.conf` file, but a better solution is to use one of the strong mapping methods. See [Account Linking](https://www.idmanagement.gov/implement/scl-windows/#step-4---account-linking) documentation for more details.

The tools for managing the certificates and keys on the smart card (such as removing or remapping the certificates and keys) might be manufacturer-specific. Additional tools that you can use to work with smart cards are:
+ `opensc-explorer`
+ `opensc-tool`
+ `pkcs11_inspect`
+ `pkcs11_listcerts`
+ `pkcs15-tool`

**To enable debug logging**
+ Add `debug_level = LEVEL` line in `/etc/sssd/sssd.conf` for each individual section, where *LEVEL* is the desired verbosity level, from 1 to 10. The logs for each corresponding section can then be found in `/var/log/sssd/` directory. See SSSD documentation [here](https://docs.pagure.org/sssd.sssd/users/troubleshooting.html#sssd-debug-logs) and [here](https://sssd.io/troubleshooting/basics.html#sssd-debug-logs) for more details.

## Enable smart cards for Amazon Linux 2 WorkSpaces
<a name="smart-cards-amazon-linux-workspaces"></a>

**Note**  
Amazon Linux 2 WorkSpaces on DCV currently have the following limitations:  
Clipboard, audio-in, video-in, and time zone redirection aren't supported.
Multiple monitors aren't supported.

To enable the use of smart cards on Amazon Linux 2 WorkSpaces, you need to include a root CA certificate file in the PEM format in the WorkSpace image.

**To obtain your root CA certificate:** You can obtain your root CA certificate in several ways:
+ You can use a root CA certificate operated by a third-party certification authority. 
+ You can export your own root CA certificate by using the Web Enrollment site, which is either `http://ip_address/certsrv` or `http://fqdn/certsrv`, where `ip_address` and `fqdn` are the IP address and the fully qualified domain name (FQDN) of the root certification CA server. For more information about using the Web Enrollment site, see [ How to export a Root Certification Authority Certificate](https://docs.microsoft.com/troubleshoot/windows-server/identity/export-root-certification-authority-certificate) in the Microsoft documentation. 
+ You can use the following procedure to export the root CA certificate from a root CA certification server that is running Active Directory Certificate Services (AD CS). For information about installing AD CS, see [ Install the Certification Authority](https://docs.microsoft.com/windows-server/networking/core-network-guide/cncg/server-certs/install-the-certification-authority) in the Microsoft documentation. 

  1. Log into the root CA server using an administrator account.

  1. From the Windows **Start** menu, open a command prompt window (**Start** > **Windows System** > **Command Prompt**). 

  1. Use the following command to export the root CA certificate to a new file, where `rootca.cer` is the name of the new file:

     ```
     certutil -ca.cert rootca.cer
     ```

     For more information about running certutil, see [ certutil](https://docs.microsoft.com/windows-server/administration/windows-commands/certutil) in the Microsoft documentation.

  1. Use the following OpenSSL command to convert the exported root CA certificate from DER format to PEM format, where *rootca* is the name of the certificate. For more information about OpenSSL, see [www.openssl.org](https://www.openssl.org/).

     ```
     openssl x509 -inform der -in rootca.cer -out /tmp/rootca.pem
     ```

**To add your root CA certificate to your Amazon Linux 2 WorkSpaces**

To assist you with enabling smart cards, we've added the `enable_smartcard` script to our Amazon Linux DCV bundles. This script performs the following actions:
+ Imports your root CA certificate into the [ Network Security Services (NSS)](https://developer.mozilla.org/docs/Mozilla/Projects/NSS) database. 
+ Installs the `pam_pkcs11` module for Pluggable Authentication Module (PAM) authentication.
+ Performs a default configuration, which includes enabling `pkinit` during WorkSpace provisioning.

The following procedure explains how to use the `enable_smartcard` script to add your root CA certificate to your Amazon Linux 2 WorkSpaces and to enable smart cards for your Amazon Linux 2 WorkSpaces.

1. Create a new Amazon Linux 2 WorkSpace with the DCV protocol enabled. When launching the WorkSpace in the Amazon WorkSpaces console, on the **Select Bundles** page, be sure to select **DCV** for the protocol, and then select one of the Amazon Linux 2 public bundles.

1. On the new WorkSpace, run the following command as root, where `pem-path` is the path to the root CA certificate file in PEM format.

   ```
   /usr/lib/skylight/enable_smartcard --ca-cert pem-path
   ```
**Note**  
Amazon Linux 2 WorkSpaces assume that the certificates on the smart cards are issued for the user's default user principal name (UPN), such as `sAMAccountName@domain`, where `domain` is a fully qualified domain name (FQDN).   
To use alternate UPN suffixes, `run /usr/lib/skylight/enable_smartcard --help` for more information. The mapping for alternate UPN suffixes is unique to each user. Therefore, that mapping must be performed individually on each user's WorkSpace.

1. (Optional) By default, all services are enabled to use smart card authentication on Amazon Linux 2 WorkSpaces. To limit smart card authentication to only specific services, you must edit `/etc/pam.d/system-auth`. Uncomment the `auth` line for `pam_succeed_if.so` and edit the list of services as needed.

   After the `auth` line is uncommented, to allow a service to use smart card authentication, you must add it to the list. To make a service use only password authentication, you must remove it from the list.

1. Perform any additional customizations to the WorkSpace. For example, you might want to add a system-wide policy to [enable users to use smart cards in Firefox](#smart-cards-firefox-amazon-linux). (Chrome users must enable smart cards on their clients themselves. For more information, see [ Smart Card Support](https://docs.aws.amazon.com/workspaces/latest/userguide/smart_card_support.html) in the *Amazon WorkSpaces User Guide*.) 

1. [Create a custom WorkSpace image and bundle](create-custom-bundle.md) from the WorkSpace.

1. Use the new custom bundle to launch WorkSpaces for your users.

You can enable your users to use smart cards in Firefox by adding a SecurityDevices policy to your Amazon Linux 2 WorkSpace image. For more information about adding system-wide policies to Firefox, see the [Mozilla policy templates](https://github.com/mozilla/policy-templates/releases) on GitHub.

**To enable users to use smart cards in Firefox**

1. On the WorkSpace that you're using to create your WorkSpace image, create a new file named `policies.json` in `/usr/lib64/firefox/distribution/`.

1. In the JSON file, add the following SecurityDevices policy, where `NAME_OF_DEVICE` is whatever value you want to use to identify the `pkcs` module. For example, you might want to use a value such as `"OpenSC"`:

   ```
   {
       "policies": {
           "SecurityDevices": {
               "NAME_OF_DEVICE": "/usr/lib64/opensc-pkcs11.so"
           }
       }
   }
   ```

**Troubleshooting:** For troubleshooting, we recommend adding the `pkcs11-tools` utility. This utility allows you to perform the following actions:
+ List each smart card.
+ List the slots on each smart card.
+ List the certificates on each smart card.

Some common issues that can cause problems:
+ Incorrect mapping of the slots to the certificates.
+ Having multiple certificates on the smart card that can match the user. Certificates are matched using the following criteria:
  + The root CA for the certificate.
  + The `<KU>` and `<EKU>` fields of the certificate.
  + The UPN in the certificate subject.
+ Having multiple certificates that have `<EKU>msScLogin` in their key usage.

In general, it's best to have only one certificate for smart card authentication that is mapped to the very first slot in the smart card.

The tools for managing the certificates and keys on the smart card (such as removing or remapping the certificates and keys) might be manufacturer-specific. Additional tools that you can use to work with smart cards are:
+ `opensc-explorer`
+ `opensc-tool`
+ `pkcs11_inspect`
+ `pkcs11_listcerts`
+ `pkcs15-tool`

**To enable debug logging**

To troubleshoot your `pam_pkcs11` and `pam-krb5` configuration, you can enable debug logging.

1. In the `/etc/pam.d/system-auth-ac` file, edit the `auth` action and change the `nodebug` parameter of `pam_pksc11.so` to `debug`. 

1. In the `/etc/pam_pkcs11/pam_pkcs11.conf` file, change `debug = false;` to `debug = true;`. The `debug` option applies separately to each mapper module, so you might need to change it both directly under the `pam_pkcs11` section and also under the appropriate mapper section (by default, this is `mapper generic`).

1. In the `/etc/pam.d/system-auth-ac` file, edit the `auth` action and add the `debug` or the `debug_sensitive` parameter to `pam_krb5.so`. 

After you've enabled debug logging, the system prints out `pam_pkcs11` debug messages directly in the active terminal. Messages from `pam_krb5` are logged in `/var/log/secure`. 

To check which username a smart card certificate maps to, use the following `pklogin_finder` command:

```
sudo pklogin_finder debug config_file=/etc/pam_pkcs11/pam_pkcs11.conf
```

When prompted, enter the smart card PIN. `pklogin_finder` outputs on `stdout` the username on the smart card certificate in the form `NETBIOS\username`. This username should match the WorkSpace username.

In Active Directory Domain Services (AD DS), the NetBIOS domain name is the pre-Windows 2000 domain name. Typically (but not always), the NetBIOS domain name is the subdomain of the Domain Name System (DNS) domain name. For example, if the DNS domain name is `example.com`, the NetBIOS domain name is usually `EXAMPLE`. If the DNS domain name is `corp.example.com`, the NetBIOS domain name is usually `CORP`. 

For example, for the user `mmajor` in the domain `corp.example.com`, the output from `pklogin_finder` is `CORP\mmajor`.

**Note**  
If you receive the message `"ERROR:pam_pkcs11.c:504: verify_certificate() failed"`, this message indicates that `pam_pkcs11` has found a certificate on the smart card that matches the username criteria but that doesn't chain up to a root CA certificate that is recognized by the machine. When that happens, `pam_pkcs11` outputs the above message and then tries the next certificate. It allows authentication only if it finds a certificate that both matches the username and chains up to a recognized root CA certificate.

To troubleshoot your `pam_krb5` configuration, you can manually invoke `kinit` in debug mode with the following command:

```
KRB5_TRACE=/dev/stdout kinit -V
```

This command should successfully obtain a Kerberos Ticket Granting Ticket (TGT). If it fails, try adding the correct Kerberos principal name explicitly to the command. For example, for the user `mmajor` in the domain `corp.example.com`, use this command: 

```
KRB5_TRACE=/dev/stdout kinit -V mmajor
```

If this command succeeds, the issue is most likely in the mapping from the WorkSpace username to the Kerberos principal name. Check the `[appdefaults]/pam/mappings` section in the `/etc/krb5.conf` file. 

If this command doesn't succeed, but a password-based `kinit` command does succeed, check the `pkinit_`-related configurations in the `/etc/krb5.conf` file. For example, if the smart card contains more than one certificate, you might need to make changes to `pkinit_cert_match`.

# Provide internet access for WorkSpaces Personal
<a name="amazon-workspaces-internet-access"></a>

Your WorkSpaces must have access to the internet so that you can install updates to the operating system and deploy applications. You can use one of the following options to allow your WorkSpaces in a virtual private cloud (VPC) to access the internet.

**Options**
+ Launch your WorkSpaces in private subnets and configure a NAT gateway in a public subnet in your VPC.
+ Launch your WorkSpaces in public subnets and automatically or manually assign public IP addresses to your WorkSpaces.

For more information about these options, see the corresponding sections in [Configure a VPC for WorkSpaces Personal](amazon-workspaces-vpc.md).

With any of these options, you must ensure that the security group for your WorkSpaces allows outbound traffic on ports 80 (HTTP) and 443 (HTTPS) to all destinations (`0.0.0.0/0`).

**Amazon Linux extras library**  
If you are using the Amazon Linux repository, your Amazon Linux WorkSpaces must either have internet access or you must configure VPC endpoints to this repository and to the main Amazon Linux repository. For more information, see the *Example: Enabling Access to the Amazon Linux AMI Repositories* section in [Endpoints for Amazon S3](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html). The Amazon Linux AMI repositories are Amazon S3 buckets in each Region. If you want instances in your VPC to access the repositories through an endpoint, create an endpoint policy that enables access to these buckets. The following policy allows access to the Amazon Linux repositories.

```
{
  "Statement": [
    {
        "Sid": "AmazonLinux2AMIRepositoryAccess",
        "Principal": "*",
        "Action": [
            "s3:GetObject"
        ],
        "Effect": "Allow",
        "Resource": [
            "arn:aws:s3:::amazonlinux.*.amazonaws.com/*"
        ]
    }
  ]
}
```

# Security groups for WorkSpaces Personal
<a name="amazon-workspaces-security-groups"></a>

When you register a directory with WorkSpaces, it creates two security groups, one for directory controllers and another for WorkSpaces in the directory. The security group for directory controllers has a name that consists of the directory identifier followed by **\$1controllers** (for example, d-12345678e1\$1controllers). The security group for WorkSpaces has a name that consists of the directory identifier followed by **\$1workspacesMembers** (for example, d-123456fc11\$1workspacesMembers).

**Warning**  
Avoid modifying, deleting, or detaching the **\$1controllers** and the **\$1workspacesMembers** security groups. Be cautious when modifying or deleting these security groups, because you will not be able to recreate these groups and add them back after they have been modified or deleted. For more information, see [ Amazon EC2 security groups for Linux instance](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/ec2-security-groups.html) or [ Amazon EC2 security groups for Windows instances](https://docs.aws.amazon.com//AWSEC2/latest/WindowsGuide/ec2-security-groups.html).

You can add a default WorkSpaces security group to a directory. After you associate a new security group with a WorkSpaces directory, new WorkSpaces that you launch or existing WorkSpaces that you rebuild will have the new security group. You can also [add this new default security group to existing WorkSpaces without rebuilding them](#security_group_existing_workspace), as explained later in this topic.

When you associate multiple security groups with a WorkSpaces directory, the rules from each security group are effectively aggregated to create one set of rules. We recommend condensing your security group rules as much as possible.

For more information about security groups, see [ Security Groups for Your VPC](https://docs.aws.amazon.com//vpc/latest/userguide/VPC_SecurityGroups.html) in the *Amazon VPC User Guide*.

**To add a security group to a WorkSpaces directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select the directory and choose **Actions**, **Update Details**.

1. Expand **Security Group** and select a security group.

1. Choose **Update and Exit**.

To add a security group to an existing WorkSpace without rebuilding it, you assign the new security group to the elastic network interface (ENI) of the WorkSpace.

**To add a security group to an existing WorkSpace**

1. Find the IP address for each WorkSpace that needs to be updated.

   1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

   1. Expand each WorkSpace and record its WorkSpace IP address.

1. Find the ENI for each WorkSpace and update its security group assignment.

   1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

   1. Under **Network & Security**, choose **Network Interfaces**.

   1. Search for the first IP address that you recorded in Step 1.

   1. Select the ENI associated with the IP address, choose **Actions**, and then choose **Change Security Groups**.

   1. Select the new security group, and choose **Save**.

   1. Repeat this process as needed for any other WorkSpaces. 

# IP access control groups for WorkSpaces Personal
<a name="amazon-workspaces-ip-access-control-groups"></a>

Amazon WorkSpaces allows you to control which IP addresses your WorkSpaces can be accessed from. By using IP address-based control groups, you can define and manage groups of trusted IP addresses, and only allow users to access their WorkSpaces when they're connected to a trusted network.

An *IP access control group* acts as a virtual firewall that controls the IP addresses from which users are allowed to access their WorkSpaces. To specify the CIDR address ranges, add rules to your IP access control group, and then associate the group with your directory. You can add up to 30 rules per IP access control group and can associate each IP access control group with one or more directories. You can create up to 140 IP access control groups per Region per AWS account. However, you can only associate up to 35 IP access control groups with a single directory.

A default IP access control group is associated with each directory. This default group includes a default rule that allows users to access their WorkSpaces from anywhere. You cannot modify the default IP access control group for your directory. If you don't associate an IP access control group with your directory, the default group is used. If you associate an IP access control group with a directory, the default IP access control group is disassociated.

To specify the public IP addresses and ranges of IP addresses for your trusted networks, add rules to your IP access control groups. If your users access their WorkSpaces through a NAT gateway or VPN, you must create rules that allow traffic from the public IP addresses for the NAT gateway or VPN.

**Note**  
IP access control groups do not allow the use of dynamic IP addresses for NATs. If you're using a NAT, configure it to use a static IP address instead of a dynamic IP address. Make sure the NAT routes all the UDP traffic through the same static IP address for the duration of the WorkSpaces session.
IP access control groups control the IP addresses from which users can connect their streaming sessions to WorkSpaces. Users can still execute functionalities, such as restart, rebuild, shutdown, from any IP address using Amazon WorkSpaces public APIs.
IP access control groups do not apply when VPC endpoint for streaming is configured for a directory.
When you change an IP access control, active sessions are not immediately interrupted; changes will be applied for new sessions only.

You can use this feature with Web Access, PCoIP zero clients, and the client applications for macOS, iPad, Windows, Chromebook, and Android.

## Create an IP access control group
<a name="create-ip-access-control-group"></a>

You can create an IP access control group as follows. Each IP access control group can contain up to 30 rules.

**To create an IP access control group**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **IP Access Controls**.

1. Choose **Create IP Group**.

1. In the **Create IP Group** dialog box, enter a name and description for the group and choose **Create**.

1. Select the group and choose **Edit**.

1. For each IP address, choose **Add Rule**. For **Source**, enter the IP address or IP address range. For **Description**, enter a description. When you are done adding rules, choose **Save**.

## Associate an IP access control group with a directory
<a name="associate-ip-access-control-group"></a>

You can associate an IP access control group with a directory to ensure that WorkSpaces are accessed only from trusted networks.

If you associate an IP access control group that has no rules with a directory, this blocks all access to all WorkSpaces.

**To associate an IP access control group with a directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select the directory and choose **Actions**, **Update Details**.

1. Expand **IP Access Control Groups** and select one or more IP access control groups.

1. Choose **Update and Exit**.

## Copy an IP access control group
<a name="copy-ip-access-control-group"></a>

You can use an existing IP access control group as a base for creating a new IP access control group.

**To create an IP access control group from an existing one**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **IP Access Controls**.

1. Select the group and choose **Actions**, **Copy to New**.

1. In the **Copy IP Group** dialog box, enter a name and description for the new group and choose **Copy Group**.

1. (Optional) To modify the rules copied from the original group, select the new group and choose **Edit**. Add, update, or remove rules as needed. Choose **Save**.

## Delete an IP access control group
<a name="delete-ip-access-control-group"></a>

You can delete a rule from an IP access control group at any time. If you remove a rule that was used to allow a connection to a WorkSpace, the user is disconnected from the WorkSpace.

Before you can delete an IP access control group, you must disassociate it from any directories.

**To delete an IP access control group**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. For each directory that is associated with the IP access control group, select the directory and choose **Actions**, **Update Details**. Expand **IP Access Control Groups**, clear the check box for the IP access control group, and choose **Update and Exit**.

1. In the navigation pane, choose **IP Access Controls**.

1. Select the group and choose **Actions**, **Delete IP Group**.

# Set up PCoIP zero clients for WorkSpaces Personal
<a name="set-up-pcoip-zero-client"></a>

PCoIP zero clients are compatible only with WorkSpaces bundles that are using the PCoIP protocol.

If your zero client device has firmware version 6.0.0 or later, your users can connect to their WorkSpaces directly. When your users are connecting directly to their WorkSpaces using a zero client device, we recommend using multi-factor authentication (MFA) with your WorkSpaces directory. For more information about using MFA with your directory, see the following documentation:
+ **AWS Managed Microsoft AD** — [ Enable multi-factor authentication for AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_mfa.html) in the *AWS Directory Service Administration Guide*
+ **AD Connector** — [ Enable multi-factor authentication for AD Connector](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ad_connector_mfa.html) in the *AWS Directory Service Administration Guide* and [Multi-factor authentication (AD Connector) for WorkSpaces Personal](connect-mfa.md)
+ **Trusted domains** — [ Enable multi-factor authentication for AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_mfa.html) in the *AWS Directory Service Administration Guide*
+ **Simple AD** — Multi-factor authentication is not available for Simple AD.

As of April 13, 2021, PCoIP Connection Manager is no longer supported for use with zero client device firmware versions between 4.6.0 and 6.0.0. If your zero client firmware is not version 6.0.0 or later, you can get the latest firmware through a Desktop Access subscription at [https://www.teradici.com/desktop-access](https://www.teradici.com/desktop-access).

**Important**  
In the Teradici PCoIP Administrative Web Interface (AWI) or the Teradici PCoIP Management Console (MC), make sure you enable Network Time Protocol (NTP). For the NTP host DNS name, use **pool.ntp.org**, and set the NTP host port to **123**. If NTP isn't enabled, your PCoIP zero client users might receive certificate failure errors, such as "The supplied certificate is invalid due to timestamp."
Starting with version 20.10.4 of the PCoIP agent, Amazon WorkSpaces disables USB redirection by default through the Windows registry. This registry setting affects the behavior of USB peripherals when your users are using PCoIP zero client devices to connect to their WorkSpaces. For more information, see [USB printers and other USB peripherals aren't working for PCoIP zero clients](amazon-workspaces-troubleshooting.md#pcoip_zero_client_usb).

For information about setting up and connecting with a PCoIP zero client device, see [PCoIP Zero Client](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-pcoip-zero-client.html) in the *Amazon WorkSpaces User Guide*. For a list of approved PCoIP zero client devices, see [PCoIP Zero Clients](https://www.teradici.com/resource-center/product-service-finder/pcoip-zero-clients) on the Teradici website.

# Set up Android for Chromebook for WorkSpaces Personal
<a name="set-up-android-chromebook"></a>

Version 2.4.13 is the final release of the Amazon WorkSpaces Chromebook client application. Because [ Google is phasing out support for Chrome Apps](https://blog.chromium.org/2020/01/moving-forward-from-chrome-apps.html), there will be no further updates to the WorkSpaces Chromebook client application, and its use is unsupported.

For [ Chromebooks that support installing Android applications](https://www.chromium.org/chromium-os/chrome-os-systems-supporting-android-apps/), we recommend using the [ WorkSpaces Android client application](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-android-client.html) instead.

Some Chromebooks launched before 2019 must be enabled to [ install Android apps](https://support.google.com/chromebook/answer/7021273) before users can install the Amazon WorkSpaces Android client application. For more information, see [ Chrome OS Systems Supporting Android Apps](https://sites.google.com/a/chromium.org/dev/chromium-os/chrome-os-systems-supporting-android-apps).

To remotely manage enabling your users' Chromebooks to install Android apps, see [Set up Android on Chrome devices](https://support.google.com/chrome/a/topic/9042368).

# Enable and configure WorkSpaces Web Access for WorkSpaces Personal
<a name="web-access"></a>

Most WorkSpaces bundles support Amazon WorkSpaces Web Access. For a list of WorkSpaces that support web browser access, see "Which Amazon WorkSpaces bundles support Web Access?" in [ Client Access, Web Access, and User Experience](https://aws.amazon.com/workspaces/faqs/#Client_Access.2C_Web_Access.2C_and_User_Experience).

**Note**  
As of November 7, 2025, Amazon WorkSpaces PCoIP Web Access is no longer open to new customers. The feature will only receive critical functional and security updates going forward. For more information, see the [Amazon WorkSpaces User Guide](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-web-access.html).
Web Access with DCV for Windows and Ubuntu WorkSpaces is supported in all Regions where DCV WorkSpaces are available. DCV for Amazon Linux WorkSpaces is only available in AWS GovCloud (US-West).
We strongly recommend using Web Access with DCV WorkSpaces for best streaming quality and user experience. The following are limitations when using Web Access with PCoIP WorkSpaces:  
Web Access with PCoIP is not supported in the AWS GovCloud (US) Regions, Asia Pacific (Mumbai), Africa (Cape Town), Europe (Frankfurt), and Israel (Tel Aviv)
Web Access with PCoIP is only supported for Windows WorkSpaces, not with Amazon Linux or Ubuntu WorkSpaces.
Web Access is not available for some Windows 10 WorkSpaces that are using the PCoIP protocol. If your PCoIP WorkSpaces are powered by Windows Server 2019 or 2022, Web Access is not available.
Web Access with PCoIP is limited in feature functionality. It supports video-out, audio-out, keyboard and mouse. It does not support many features, including video-in, audio-in, clipboard redirection, and web cams.
If you are using macOS on VPN and using the Firefox web browser, the web browser will not support streaming PCoIP WorkSpaces using WorkSpaces Web Access. This is due to a limitation in Firefox implementation of the WebRTC protocol.

**Important**  
Beginning October 1, 2020, customers will no longer be able to use the Amazon WorkSpaces Web Access client to connect to Windows 7 custom WorkSpaces or to Windows 7 Bring Your Own License (BYOL) WorkSpaces.

## Step 1: Enable Web Access to your WorkSpaces
<a name="enable-web-access"></a>

You control Web Access to your WorkSpaces at the directory level. For each directory containing WorkSpaces that you want to allow users to access through the Web Access client, do the following steps.

**To enable Web Access to your WorkSpaces**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Under the **Directory ID** column, choose the directory ID of the directory you want to enable Web Access for.

1. On the **Directory Details** page, scroll down to the **Other platforms** section and choose **Edit**.

1. Choose **Web Access**.

1. Choose **Save**.

**Note**  
After you enable Web Access, reboot your WorkSpace for the change to apply.

## Step 2: Configure inbound and outbound access to ports for Web Access
<a name="configure_inbound_outbound"></a>

Amazon WorkSpaces Web Access requires inbound and outbound access for certain ports. For more information, see [Ports for Web Access](workspaces-port-requirements.md#web-access-ports).

## Step 3: Configure Group Policy and security policy settings to enable users to log on
<a name="configure_group_policy"></a>

Amazon WorkSpaces relies on a specific logon screen configuration to enable users to successfully log on from their Web Access client.

To enable Web Access users to log on to their WorkSpaces, you must configure a Group Policy setting and three Security Policy settings. If these settings are not correctly configured, users might experience long logon times or black screens when they try to log on to their WorkSpaces. To configure these settings, use the following procedures. 

You can use Group Policy Objects (GPOs) to apply settings to manage Windows WorkSpaces or users that are part of your Windows WorkSpaces directory. We recommend that you create an organizational unit for your WorkSpaces Computer Objects and an organizational unit for your WorkSpaces User Objects.

For information about using the Active Directory administration tools to work with GPOs, see [ Installing the Active Directory Administration Tools](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_install_ad_tools.html) in the *AWS Directory Service Administration Guide*.

**To enable the WorkSpaces logon agent to switch users**

In most cases, when a user attempts to log on to a WorkSpace, the user name field is prepopulated with the name of that user. However, if an administrator has established an RDP connection to the WorkSpace to perform maintenance tasks, the user name field is populated with the name of the administrator instead.

To avoid this issue, disable the **Hide entry points for Fast User Switching** Group Policy setting. When you disable this setting, the WorkSpaces logon agent can use the **Switch User** button to populate the user name field with the correct name.

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **System**, and **Logon**. 

1. Open the **Hide entry points for Fast User Switching** setting.

1. In the **Hide entry points for Fast User Switching** dialog box, choose **Disabled**, and then choose **OK**.

By default, the list of last logged on users is displayed instead of the **Switch User** button. Depending on the configuration of the WorkSpace, the list might not display the **Other User** tile. When this situation occurs, if the prepopulated user name isn't correct, the WorkSpaces logon agent can't populate the field with the correct name.

To avoid this issue, enable the Security Policy setting **Interactive logon: Don't display last signed-in** or **Interactive logon: Do not display last user name** (depending on which version of Windows you're using).

**To hide the last logged on user name**

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Windows Settings**, **Security Settings**, **Local Policies**, and **Security Options**. 

1. Open one of the following settings:
   + For Windows 7 — **Interactive logon: Don't display last signed-in**
   + For Windows 10 — **Interactive logon: Do not display last user name**

1. In the **Properties** dialog box for the setting, choose **Enabled**, and then choose **OK**.

**To require pressing CTRL\$1ALT\$1DEL before users can log on**

For WorkSpaces Web Access, you need to require that users press CTRL\$1ALT\$1DEL before they can log on. Requiring users to press CTRL\$1ALT\$1DEL before they log on ensures that users are using a trusted path when they're entering their passwords.

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Windows Settings**, **Security Settings**, **Local Policies**, and **Security Options**. 

1. Open the **Interactive logon: Do not require CTRL\$1ALT\$1DEL** setting.

1. On the **Local Security Setting** tab, choose **Disabled**, and then choose **OK**.

**To display the domain and user information when the session is locked**

The WorkSpaces logon agent looks for the user's name and domain. After this setting is configured, the lock screen will display the user's full name (if it is specified in Active Directory), their domain name, and their user name.

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Windows Settings**, **Security Settings**, **Local Policies**, and **Security Options**. 

1. Open the **Interactive logon: Display user information when the session is locked** setting.

1. On the **Local Security Setting** tab, choose **User display name, domain and user names**, and then choose **OK**.

**To apply the Group Policy and Security Policy settings changes**  
Group Policy and Security Policy settings changes take effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy and Security Policy changes in the prior procedures, do one of the following:
+ Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
+ From an administrative command prompt, enter **gpupdate /force**.

# Configure WorkSpaces Thin Client
<a name="access-control-awstc"></a>

Most WorkSpaces bundles support Amazon WorkSpaces Thin Client Access. For a list of WorkSpaces that support web browser access, see "Which Amazon WorkSpaces bundles support Thin Client Access?" in [ Client Access, Web Access, and User Experience](https://aws.amazon.com/workspaces/faqs/#Client_Access.2C_Web_Access.2C_and_User_Experience).

## Step 1: Enable Access Control to your Amazon WorkSpaces Thin Client
<a name="enable-access-control-awstc"></a>

You control Thin Client Access to your WorkSpaces at the directory level with user-agent based access control. For each directory containing WorkSpaces that you want to allow users to access through the Thin Client Access client, do the following steps.

**To enable Thin Client Access to your WorkSpaces**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Under the **Directory ID** column, choose the directory ID of the directory you want to enable Thin Client Access for.

1. On the **Directory Details** page, scroll down to the **Other platforms** section and choose **Edit**.

1. Select **WorkSpaces Thin Client**.

1. Choose **Save**.

## Step 2: Configure inbound and outbound access to ports for Thin Client Access
<a name="configure_inbound_outbound_awstc"></a>

Amazon WorkSpaces Thin Client Access requires inbound and outbound access for certain ports. For more information, see [Ports for Web Access](workspaces-port-requirements.md#web-access-ports).

## Step 3: Configure Group Policy and security policy settings to enable users to log on
<a name="configure_group_policy-awstc"></a>

Amazon WorkSpaces relies on a specific logon screen configuration to enable users to successfully log on from their Thin Client Access client.

1. To enable Thin Client Access users to log on to their WorkSpaces, you must configure a Group Policy setting and three Security Policy settings. If these settings are not correctly configured, users might experience long logon times or black screens when they try to log on to their WorkSpaces. To configure these settings, use the following procedures. 

1. You can use Group Policy Objects (GPOs) to apply settings to manage Windows WorkSpaces or users that are part of your Windows WorkSpaces directory. We recommend that you create an organizational unit for your WorkSpaces Computer Objects and an organizational unit for your WorkSpaces User Objects.

1. For information about using the Active Directory administration tools to work with GPOs, see [ Installing the Active Directory Administration Tools](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_install_ad_tools.html) in the *AWS Directory Service Administration Guide*.

1. In most cases, when a user attempts to log on to a WorkSpace, the user name field is prepopulated with the name of that user. However, if an administrator has established an RDP connection to the WorkSpace to perform maintenance tasks, the user name field is populated with the name of the administrator instead.

1. To avoid this issue, disable the **Hide entry points for Fast User Switching** Group Policy setting. When you disable this setting, the WorkSpaces logon agent can use the **Switch User** button to populate the user name field with the correct name.

**To enable the WorkSpaces logon agent to switch users**

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **System**, and **Logon**. 

1. Open the **Hide entry points for Fast User Switching** setting.

1. In the **Hide entry points for Fast User Switching** dialog box, choose **Disabled**, and then choose **OK**.

By default, the list of last logged on users is displayed instead of the **Switch User** button. Depending on the configuration of the WorkSpace, the list might not display the **Other User** tile. When this situation occurs, if the prepopulated user name isn't correct, the WorkSpaces logon agent can't populate the field with the correct name.

To avoid this issue, enable the Security Policy setting **Interactive logon: Don't display last signed-in** or **Interactive logon: Do not display last user name** (depending on which version of Windows you're using).

**To hide the last logged on user name**

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Windows Settings**, **Security Settings**, **Local Policies**, and **Security Options**. 

1. Open one of the following settings:
   + For Windows 7 — **Interactive logon: Don't display last signed-in**
   + For Windows 10 — **Interactive logon: Do not display last user name**

1. In the **Properties** dialog box for the setting, choose **Enabled**, and then choose **OK**.

For WorkSpaces Thin Client Access, you need to require that users press CTRL\$1ALT\$1DEL before they can log on. Requiring users to press CTRL\$1ALT\$1DEL before they log on ensures that users are using a trusted path when they're entering their passwords.

**To require pressing CTRL\$1ALT\$1DEL before users can log on**

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Windows Settings**, **Security Settings**, **Local Policies**, and **Security Options**. 

1. Open the **Interactive logon: Do not require CTRL\$1ALT\$1DEL** setting.

1. On the **Local Security Setting** tab, choose **Disabled**, and then choose **OK**.

The WorkSpaces logon agent looks for the user's name and domain. After this setting is configured, the lock screen will display the user's full name (if it is specified in Active Directory), their domain name, and their user name.

**To display the domain and user information when the session is locked**

1. Open the Group Policy Management tool (**gpmc.msc**) and navigate to and select a GPO at the domain or domain controller level of the directory that you use for your WorkSpaces. (If you have the [ WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) installed in your domain, you can use the WorkSpaces GPO for your WorkSpaces machine accounts.)

1. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Windows Settings**, **Security Settings**, **Local Policies**, and **Security Options**. 

1. Open the **Interactive logon: Display user information when the session is locked** setting.

1. On the **Local Security Setting** tab, choose **User display name, domain and user names**, and then choose **OK**.

Group Policy and Security Policy settings changes take effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy and Security Policy changes in the prior procedures, do one of the following:

**To apply the Group Policy and Security Policy settings changes**

1. Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).

1. From an administrative command prompt, enter **gpupdate /force**.

# Configure FedRAMP authorization or DoD SRG compliance for WorkSpaces Personal
<a name="fips-encryption"></a>

To comply with the [Federal Risk and Authorization Management Program (FedRAMP)](https://aws.amazon.com/compliance/fedramp/) or the [Department of Defense (DoD) Cloud Computing Security Requirements Guide (SRG)](https://aws.amazon.com/compliance/dod/), you must configure Amazon WorkSpaces to use Federal Information Processing Standards (FIPS) endpoint encryption at the directory level. You must also use a US AWS Region that has FedRAMP authorization or is DoD SRG compliant.

The level of FedRAMP authorization (Moderate or High) or DoD SRG Impact Level (2, 4, or 5) depends on the US AWS Region in which Amazon WorkSpaces is being used.

For the levels of FedRAMP authorization and DoD SRG compliance that apply to each Region, see [AWS Services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/).

**Note**  
In addition to using FIPS endpoint encryption, you can also encrypt your WorkSpaces. For more information, see [Encrypted WorkSpaces in WorkSpaces Personal](encrypt-workspaces.md).

**Requirements**
+ You must create your WorkSpaces in a [US AWS Region that has FedRAMP authorization or is DoD SRG-compliant](https://aws.amazon.com/compliance/services-in-scope/).
+ The WorkSpaces directory must be configured to use **FIPS 140-2 Validated Mode** for endpoint encryption.
**Note**  
To use the **FIPS 140-2 Validated Mode** setting, the WorkSpaces directory must either be new, or all existing WorkSpaces in the directory must be using **FIPS 140-2 Validated Mode** for endpoint encryption. Otherwise, you cannot use this setting, and therefore the WorkSpaces that you create will not comply with FedRAMP or DoD security requirements.  
Refer to [step 3](#step3-fips) below for details on how to verify the directory.
+ Users must access their WorkSpaces from one of the following WorkSpaces client applications:
  + Windows: 2.4.3 or later
  + macOS: 2.4.3 or later for PCoIP WorkSpaces, and 5.21.0 or later for DCV WorkSpaces
  + Linux: 3.0.0 or later
  + iOS: 2.4.1 or later
  + Android: 2.4.1 or later
  + Fire Tablet: 2.4.1 or later
  + ChromeOS: 2.4.1 or later
  + Web Access

**To use FIPS endpoint encryption**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Verify that the directory where you want to create FedRAMP-authorized and DoD SRG-compliant WorkSpaces does not have any existing WorkSpaces associated with it. If there are WorkSpaces associated with the directory and the directory is not already enabled to use FIPS 140-2 Validated Mode, either terminate the WorkSpaces or create a new directory.

1. Choose the directory that meets the above criteria, and then choose **Actions**, **Update Details**.

1. <a name="step3-fips"></a>On the **Update Directory Details** page, choose the arrow to expand the **Access Control Options** section.

1. For **Endpoint Encryption**, choose **FIPS 140-2 Validated Mode** instead of **TLS Encryption Mode (Standard)**.

1. Choose **Update and Exit**.

1. You can now create WorkSpaces from this directory that are FedRAMP authorized and DoD SRG compliant. To access these WorkSpaces, users must use one of the WorkSpaces client applications listed earlier in the [Requirements](#fedramp-requirements) section.

# Enable SSH connections for your Linux WorkSpaces in WorkSpaces Personal
<a name="connect-to-linux-workspaces-with-ssh"></a>

If you or your users want to connect to your Linux WorkSpaces by using the command line, you can enable SSH connections. You can enable SSH connections to all WorkSpaces in a directory or to individual WorkSpaces in a directory. 

To enable SSH connections, you create a new security group or update an existing security group and add a rule to allow inbound traffic for this purpose. Security groups act as a firewall for associated instances, controlling both inbound and outbound traffic at the instance level. After you create or update your security group, your users and others can use PuTTY or other terminals to connect from their devices to your Linux WorkSpaces. For more information, see [Security groups for WorkSpaces Personal](amazon-workspaces-security-groups.md).

For a video tutorial, see [ How can I connect to my Linux Amazon WorkSpaces using SSH?](https://aws.amazon.com/premiumsupport/knowledge-center/linux-workspace-ssh/) on the AWS Knowledge Center. This tutorial is for Amazon Linux 2 WorkSpaces only.

**Topics**
+ [Prerequisites for SSH connections to Linux WorkSpaces](#before-you-begin-enable-ssh-linux-workspaces)
+ [Enable SSH connections to all Linux WorkSpaces in a directory](#enable-ssh-directory-level-access-linux-workspaces)
+ [Password-based authentication in WorkSpaces](#enable-ssh-access-old-version)
+ [Enable SSH connections to a specific Linux WorkSpace](#enable-ssh-access-specific-linux-workspace)
+ [Connect to a Linux WorkSpace using Linux or PuTTY](#ssh-connection-linux-workspace-using-linux-or-putty)

## Prerequisites for SSH connections to Linux WorkSpaces
<a name="before-you-begin-enable-ssh-linux-workspaces"></a>
+ Enabling inbound SSH traffic to a WorkSpace — To add a rule to allow inbound SSH traffic to one or more Linux WorkSpaces, make sure that you have the public or private IP addresses of the devices that require SSH connections to your WorkSpaces. For example, you can specify the public IP addresses of devices outside your virtual private cloud (VPC) or the private IP address of another EC2 instance in the same VPC as your WorkSpace. 

  If you plan to connect to a WorkSpace from your local device, you can use the search phrase "what is my IP address" in an internet browser or use the following service: [Check IP](https://checkip.amazonaws.com/). 
+ Connecting to a WorkSpace — The following information is required to initiate an SSH connection from a device to a Linux WorkSpace.
  + The NetBIOS name of the Active Directory domain that you are connected to.
  + Your WorkSpace user name.
  + The public or private IP address of the WorkSpace that you want to connect to.

    Private: If your VPC is attached to a corporate network and you have access to that network, you can specify the private IP address of the WorkSpace.

    Public: If your WorkSpace has a public IP address, you can use the WorkSpaces console to find the public IP address, as described in the following procedure.

**To find the IP addresses for the Linux WorkSpace you want to connect to and your user name**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. In the list of WorkSpaces, choose the WorkSpace that you want to enable SSH connections to.

1. In the **Running mode** column, confirm that the WorkSpace status is **Available**.

1. Click the arrow to the left of the WorkSpace name to display the inline summary, and note the following information:
   + The **WorkSpace IP**. This is the private IP address of the WorkSpace.

     The private IP address is required for obtaining the elastic network interface associated with the WorkSpace. The network interface is required to retrieve information such as the security group or public IP address associated with the WorkSpace.
   + The WorkSpace **Username**. This is the user name that you specify to connect to the WorkSpace.

1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

1. In the navigation pane, choose **Network Interfaces**.

1. In the search box, type the **WorkSpace IP** that you noted in Step 5. 

1. Select the network interface associated with the **WorkSpace IP**. 

1. If your WorkSpace has a public IP address, it is displayed in the **IPv4 Public IP** column. Make a note of this address, if applicable.

**To find the NetBIOS name of the Active Directory domain that you are connected to**

1. Open the Directory Service console at [https://console.aws.amazon.com/directoryservicev2/](https://console.aws.amazon.com/directoryservicev2/).

1. In the list of directories, click the **Directory ID** link of the directory for the WorkSpace.

1. In the **Directory details** section, note the **Directory NetBIOS name**.

## Enable SSH connections to all Linux WorkSpaces in a directory
<a name="enable-ssh-directory-level-access-linux-workspaces"></a>

To enable SSH connections to all Linux WorkSpaces in a directory, do the following.

**To create a security group with a rule to allow inbound SSH traffic to all Linux WorkSpaces in a directory**

1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

1. In the navigation pane, choose **Security Groups**.

1. Choose **Create Security Group**.

1. Type a name and optionally, a description for your security group.

1. For **VPC**, choose the VPC that contains the WorkSpaces that you want to enable SSH connections to.

1. On the **Inbound **tab, choose **Add Rule**, and do the following:
   + For **Type**, choose **SSH**.
   + For **Protocol**, TCP is automatically specified when you choose **SSH**.
   + For **Port Range**, 22 is automatically specified when you choose **SSH**.
   + For **Source**, specify the CIDR range of the public IP addresses for the computers that users will use to connect to their WorkSpaces. For example, a corporate network or a home network.
   + For **Description** (optional), type a description for the rule.

1. Choose **Create**.

1. Attach this security group to your WorkSpaces. For more information on adding this security group to your WorkSpaces, see [Security groups for WorkSpaces Personal](amazon-workspaces-security-groups.md). If you want to automatically attach additional security groups to your WorkSpaces, refer to this [ blog post](https://aws.amazon.com/blogs/desktop-and-application-streaming/automatically-attach-additional-security-groups-to-amazon-appstream-2-0-and-amazon-workspaces/).

## Password-based authentication in WorkSpaces
<a name="enable-ssh-access-old-version"></a>

**To enable password authentication in newly created Linux WorkSpaces**

1. Launch the WorkSpaces client and login to your WorkSpace.

1. Open the Terminal window.

1. In the Terminal window, run the following command to enable SSH Password Authentication in cloud-init.

   ```
   sudo bash -c 'touch /etc/cloud/cloud.cfg.d/15_sshpwauth.cfg && echo "ssh_pwauth: true" > /etc/cloud/cloud.cfg.d/15_sshpwauth.cfg && sudo rm /var/lib/cloud/instance/sem/config_set_passwords && sudo cloud-init single --name set-passwords'
   ```

   This script will do the following:
   + Create a configuration file in the cloud-init directory `/etc/cloud/cloud.cfg.d/`.
   + Modify the configuration file to tell cloud-init to enable SSH password authentication.
   + Reset the `set-passwords` cloud-init module so that it can be run again.
   + Run the `set-passwords` cloud-init module by itself. This will write a file that enables SSH password authentication to the SSH configuration directory, `/etc/ssh/sshd_config.d/`, and restart SSHD so that the setting will take place immediately.

 This enables SSH password authentication on your WorkSpace and will persist through custom images. If you enable SSH password authentication only in the SSHD configuration file, without configuring cloud-init, the setting will not persist through imaging on some Linux WorkSpaces. For more information, see [Set Passwords]() in the cloud-init module documentation.

**To disable password authentication in existing Linux WorkSpaces**

1. Launch the WorkSpaces client and login to your WorkSpace.

1. Open the Terminal window.

1. In the Terminal window, run the following command to disable SSH Password Authentication in cloud-init.

   ```
   sudo bash -c 'touch /etc/cloud/cloud.cfg.d/15_sshpwauth.cfg && echo "ssh_pwauth: false" > /etc/cloud/cloud.cfg.d/15_sshpwauth.cfg && sudo rm /var/lib/cloud/instance/sem/config_set_passwords && sudo cloud-init single —name set-passwords'
   ```

   This script will do the following:
   + Create a configuration file in the cloud-init directory `/etc/cloud/cloud.cfg.d/`.
   + Modify the configuration file to tell cloud-init to disable SSH password authentication.
   + Reset the `set-passwords` cloud-init module so that it can be run again.
   + Run the `set-passwords` cloud-init module by itself. This will write a file that enables SSH password authentication to the SSH configuration directory, `/etc/ssh/sshd_config.d/`, and restart SSHD so that the setting will take place immediately.

This immediately disables SSH in the WorkSpace and will persist through custom images.

## Enable SSH connections to a specific Linux WorkSpace
<a name="enable-ssh-access-specific-linux-workspace"></a>

To enable SSH connections to a specific Linux WorkSpace, do the following.

**To add a rule to an existing security group to allow inbound SSH traffic to a specific Linux WorkSpace**

1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

1. In the navigation pane, under **Network & Security**, choose **Network Interfaces**.

1. In the search bar, type the private IP address of the WorkSpace that you want to enable SSH connections to.

1. In the **Security groups** column, click the link for the security group.

1. On the **Inbound **tab, choose **Edit**.

1. Choose** Add Rule**, and then do the following:
   + For **Type**, choose **SSH**.
   + For **Protocol**, TCP is automatically specified when you choose **SSH**.
   + For **Port Range**, 22 is automatically specified when you choose **SSH**.
   + For **Source**, choose **My IP** or **Custom**, and specify a single IP address or an IP address range in CIDR notation. For example, if your IPv4 address is `203.0.113.25`, specify `203.0.113.25/32` to list this single IPv4 address in CIDR notation. If your company allocates addresses from a range, specify the entire range, such as `203.0.113.0/24`.
   + For **Description** (optional), type a description for the rule.

1. Choose **Save**.

## Connect to a Linux WorkSpace using Linux or PuTTY
<a name="ssh-connection-linux-workspace-using-linux-or-putty"></a>

After you create or update your security group and add the required rule, your users and others can use Linux or PuTTY to connect from their devices to your WorkSpaces. 

**Note**  
Before completing either of the following procedures, make sure that you have the following:  
The NetBIOS name of the Active Directory domain that you are connected to.
The username that you use to connect to the WorkSpace.
The public or private IP address of the WorkSpace that you want to connect to.
For instructions on how to obtain this information, see "Prerequisites for SSH Connections to Linux WorkSpaces" earlier in this topic.

**To connect to an Linux WorkSpace using Linux**

1. Open the command prompt as an administrator and enter the following command. For *NetBIOS name*, *Username*, and *WorkSpace IP*, enter the applicable values. 

   ```
   ssh "NetBIOS_NAME\Username"@WorkSpaceIP
   ```

   The following is an example of the SSH command where:
   + The *NetBIOS\$1NAME* is anycompany
   + The *Username *is janedoe
   + The *WorkSpace IP* is 203.0.113.25

   ```
   ssh "anycompany\janedoe"@203.0.113.25
   ```

1. When prompted, enter the same password that you use when authenticating with the WorkSpaces client (your Active Directory password).

**To connect to an Linux WorkSpace using PuTTY**

1. Open PuTTY.

1. In the **PuTTY Configuration** dialog box, do the following:
   + For **Host Name (or IP address)**, enter the following command. Replace the values with the NetBIOS name of the Active Directory domain that you are connected to, the user name that you use to connect to the WorkSpace, and the IP address of the WorkSpace that you want to connect to.

     ```
     NetBIOS_NAME\Username@WorkSpaceIP
     ```
   + For **Port**, enter **22**.
   + For **Connection type**, choose **SSH**.

   For an example of the SSH command, see step 1 in the previous procedure.

1.  Choose **Open**.

1. When prompted, enter the same password that you use when authenticating with the WorkSpaces client (your Active Directory password).

# Required configuration and service components for WorkSpaces Personal
<a name="required-service-components"></a>

As a WorkSpace administrator, you must understand the following about required configuration and service components.
+ [Required routing table configuration](#routing-table-configuration)
+ [Required service components for Windows](#required-service-components-windows)
+ [Required service components for Linux](#required-service-components-linux)
+ [Required service components for Ubuntu](#required-service-components-ubuntu)
+ [Required service components for Rocky Linux](#required-service-components-rocky)
+ [Required service components for Red Hat Enterprise Linux](#required-service-components-red-hat)

## Required routing table configuration
<a name="routing-table-configuration"></a>

We recommend that you not modify the operating system-level routing table for a WorkSpace. The WorkSpaces service requires the preconfigured routes in this table to monitor the system state and update system components. If routing table changes are required for your organization, contact AWS Support or your AWS account team before applying any changes. 

## Required service components for Windows
<a name="required-service-components-windows"></a>

On Windows WorkSpaces, the service components are installed in the following locations. Do not delete, change, block, or quarantine these objects. If you do so, the WorkSpace will not function correctly.

If antivirus software is installed on the WorkSpace, make sure it does not interfere with the service components installed in the following locations.
+ `C:\Program Files\Amazon`
+ `C:\Program Files\NICE`
+ `C:\Program Files\Teradici`
+ `C:\Program Files (x86)\Teradici`
+ `C:\ProgramData\Amazon`
+ `C:\ProgramData\NICE`
+ `C:\ProgramData\Teradici`

If antivirus software is installed on the WorkSpaces Core, make sure it does not interfere with the service components installed in the following locations.
+ C:\$1Program Files\$1Amazon
+ C:\$1ProgramData\$1Amazon

### 32-bit PCoIP agent
<a name="pcoip-agent-32-bit-to-64-bit"></a>

As of March 29, 2021, we updated the PCoIP agent from 32-bit to 64-bit. For Windows WorkSpaces that are using the PCoIP protocol, this means that the location of the Teradici files changed from `C:\Program Files (x86)\Teradici` to `C:\Program Files\Teradici`. Because we updated PCoIP agents during regular maintenance windows, some of your WorkSpaces might have used the 32-bit agent longer than others during the transition.

If you've configured firewall rules, antivirus software exclusions (on the client side and host side), Group Policy Object (GPO) settings, or settings for Microsoft System Center Configuration Manager (SCCM), Microsoft Endpoint Configuration Manager, or similar configuration management tools based on the full path to the 32-bit agent, you must also add the full path to the 64-bit agent to those settings.

**If you're filtering on the paths to any 32-bit PCoIP components, be sure to add the paths to the 64-bit versions of the components. Because your WorkSpaces might not all be updated at the same time, do not replace the 32-bit path with the 64-bit path, or some of your WorkSpaces might not work.** For example, if you're basing your exclusions or communication filters on `C:\Program Files (x86)\Teradici\PCoIP Agent\bin\pcoip_server_win32.exe`, you must also add `C:\Program Files\Teradici\PCoIP Agent\bin\pcoip_server.exe`. Likewise, if you're basing your exclusions or communications filters on `C:\Program Files (x86)\Teradici\PCoIP Agent\bin\pcoip_agent.exe`, you must also add `C:\Program Files\Teradici\PCoIP Agent\bin\pcoip_agent.exe`.

**PCoIP arbiter service change** — Be aware that the PCoIP arbiter service (`C:\Program Files (x86)\Teradici\PCoIP Agent\bin\pcoip_arbiter_win32.exe`) is removed when your WorkSpaces are updated to use the 64-bit agent.

**PCoIP zero clients and USB devices** — Starting with version 20.10.4 of the PCoIP agent, Amazon WorkSpaces disables USB redirection by default through the Windows registry. This registry setting affects the behavior of USB peripherals when your users are using PCoIP zero client devices to connect to their WorkSpaces. For more information, see [USB printers and other USB peripherals aren't working for PCoIP zero clients](amazon-workspaces-troubleshooting.md#pcoip_zero_client_usb).

## Required service components for Linux
<a name="required-service-components-linux"></a>

On Amazon Linux WorkSpaces, the service components are installed in the following locations. Do not delete, change, block, or quarantine these objects. If you do so, the WorkSpace will not function correctly.

**Note**  
Making changes to files other than `/etc/pcoip-agent/pcoip-agent.conf` might cause your WorkSpaces to stop working and might require you to rebuild them. For information about modifying `/etc/pcoip-agent/pcoip-agent.conf`, see [Manage your Amazon Linux 2 WorkSpaces in WorkSpaces Personal](manage_linux_workspace.md).
+ `/etc/dhcp/dhclient.conf`
+ `/etc/logrotate.d/pcoip-agent`
+ `/etc/logrotate.d/pcoip-server`
+ `/etc/os-release`
+ `/etc/pam.d/pcoip`
+ `/etc/pam.d/pcoip-session`
+ `/etc/pcoip-agent`
+ `/etc/profile.d/system-restart-check.sh`
+ `/etc/X11/default-display-manager`
+ `/etc/yum/pluginconf.d/halt_os_update_check.conf`
+ `/etc/systemd/system/euc-analytic-agent.service`
+ `/lib/systemd/system/pcoip.service`
+ `/lib/systemd/system/pcoip-agent.service`
+ `/lib64/security/pam_self.so`
+ `/usr/bin/pcoip-fne-view-license`
+ `/usr/bin/pcoip-list-licenses`
+ `/usr/bin/pcoip-validate-license`
+ `/usr/bin/euc-analytics-agent`
+ `/usr/lib/firewalld/services/pcoip-agent.xml`
+ `/usr/lib/modules-load.d/usb-vhci.conf`
+ `/usr/lib/pcoip-agent`
+ `/usr/lib/skylight`
+ `/usr/lib/systemd/system/pcoip.service`
+ `/usr/lib/systemd/system/pcoip.service.d/`
+ `/usr/lib/systemd/system/skylight-agent.service`
+ `/usr/lib/tmpfiles.d/pcoip-agent.conf`
+ `/usr/lib/yum-plugins/halt_os_update_check.py`
+ `/usr/sbin/pcoip-agent`
+ `/usr/sbin/pcoip-register-host`
+ `/usr/sbin/pcoip-support-bundler`
+ `/usr/share/doc/pcoip-agent`
+ `/usr/share/pcoip-agent`
+ `/usr/share/selinux/packages/pcoip-agent.pp`
+ `/usr/share/X11`
+ `/var/crash/pcoip-agent`
+ `/var/lib/pcoip-agent`
+ `/var/lib/skylight`
+ `/var/log/pcoip-agent` 
+ `/var/log/skylight`
+ `/var/logs/wsp`
+ `/var/log/eucanalytics` 

## Required service components for Ubuntu
<a name="required-service-components-ubuntu"></a>

On Ubuntu WorkSpaces, the service components are installed in the following locations. Do not delete, change, block, or quarantine these objects. If you do so, the WorkSpace will not function correctly.
+ `/etc/X11/default-display-manager`
+ `/etc/dcv`
+ `/etc/default/grub.d/zz-hibernation.cfg`
+ `/etc/netplan`
+ `/etc/os-release`
+ `/etc/pam.d/dcv`
+ `/etc/pam.d/dcv-graphical-sso`
+ `/etc/sssd/sssd.conf`
+ `/etc/wsp`
+ `/etc/systemd/system/euc-analytic-agent.service` 
+ `/lib64/security/pam_self.so`
+ `/usr/lib/skylight`
+ `/usr/lib/systemd/system/dcvserver.service`
+ `/usr/lib/systemd/system/dcvsessionlauncher.service`
+ `/usr/lib/systemd/system/skylight-agent.service`
+ `/usr/lib/systemd/system/wspdcvhostadapter.service`
+ `/usr/share/X11`
+ `/usr/bin/euc-analytics-agent`
+ `/var/lib/skylight`
+ `/var/log/skylight`
+ `/var/log/eucanalytics` 

## Required service components for Rocky Linux
<a name="required-service-components-rocky"></a>

On Red Hat Enterprise Linux WorkSpaces, the service components are installed in the following locations. Do not delete, change, block, or quarantine these objects. If you do so, the WorkSpace will not function correctly.
+ `/etc/dcv`
+ `/etc/os-release`
+ `/etc/pam.d/dcv-graphical-sso`
+ `/etc/pam.d/dcv`
+ `/etc/systemd/system/euc-analytic-agent.service`
+ `/etc/wsp`
+ `/usr/bin/euc-analytics-agent`
+ `/usr/lib/skylight`
+ `/usr/lib/systemd/system/dcvserver.service`
+ `/usr/lib/systemd/system/dcvsessionlauncher.service`
+ `/usr/lib/systemd/system/skylight-agent.service`
+ `/usr/lib/systemd/system/wspdcvhostadapter.service`
+ `/usr/lib/systemd/system/xdcv-console.path`
+ `/usr/lib/systemd/system/xdcv-console.service`
+ `/usr/lib/systemd/system/xdcv-console-update.service`
+ `/usr/share/X11`
+ `/var/lib/skylight`
+ `/var/log/eucanalytics`
+ `/var/log/skylight`

## Required service components for Red Hat Enterprise Linux
<a name="required-service-components-red-hat"></a>

On Red Hat Enterprise Linux WorkSpaces, the service components are installed in the following locations. Do not delete, change, block, or quarantine these objects. If you do so, the WorkSpace will not function correctly.
+ `/etc/dcv`
+ `/etc/os-release`
+ `/etc/pam.d/dcv-graphical-sso`
+ `/etc/pam.d/dcv`
+ `/etc/systemd/system/euc-analytic-agent.service`
+ `/etc/wsp`
+ `/usr/bin/euc-analytics-agent`
+ `/usr/lib/skylight`
+ `/usr/lib/systemd/system/dcvserver.service`
+ `/usr/lib/systemd/system/dcvsessionlauncher.service`
+ `/usr/lib/systemd/system/skylight-agent.service`
+ `/usr/lib/systemd/system/wspdcvhostadapter.service`
+ `/usr/lib/systemd/system/xdcv-console.path`
+ `/usr/lib/systemd/system/xdcv-console.service`
+ `/usr/lib/systemd/system/xdcv-console-update.service`
+ `/usr/share/X11`
+ `/var/log/eucanalytics`
+ `/var/log/skylight`

# Manage directories for WorkSpaces Personal
<a name="manage-workspaces-directory"></a>

WorkSpaces uses a directory to store and manage information for your WorkSpaces and users. You can use one of the following options:
+ AD Connector — Use your existing on-premises Microsoft Active Directory. Users can sign into their WorkSpaces using their on-premises credentials and access on-premises resources from their WorkSpaces.
+ AWS Managed Microsoft AD — Create a Microsoft Active Directory hosted on AWS.
+ Simple AD — Create a directory that is compatible with Microsoft Active Directory, powered by Samba 4, and hosted on AWS.
+ Cross trust — Create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain.
+ Microsoft Entra ID — Create a directory that uses Microsoft Entra ID as its identity source (through IAM Identity Center). Personal WorkSpaces in the directory are joined using Microsoft Entra's native authentication and are enrolled into Microsoft Intune through Microsoft Windows Autopilot user-driven mode. Directories using Microsoft Entra ID only support Windows 10 and 11 Bring Your Own Licenses WorkSpaces.
+ Custom — Create a directory that use an identity provider of your choice (through IAM Identity Center). WorkSpaces in the directory are managed using the device management solution of your choice such as JumpCloud. Directories using custom identity providers only support Windows 10 and 11 Bring Your Own Licenses WorkSpaces.

For tutorials that demonstrate how to set up these directories and launch WorkSpaces, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

**Tip**  
For a detailed exploration of directory and virtual private cloud (VPC) design considerations for various deployment scenarios, see [Best Practices for Deploying Amazon WorkSpaces](https://docs.aws.amazon.com/whitepapers/latest/best-practices-deploying-amazon-workspaces/best-practices-deploying-amazon-workspaces.html).

After you create a directory, you'll perform most directory administration tasks using tools such as the Active Directory Administration Tools. You can perform some directory administration tasks using the WorkSpaces console and other tasks using Group Policy. For more information about managing users and groups, see [Manage users in WorkSpaces Personal](manage-workspaces-users.md) and [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md).

**Note**  
Shared directories are not currently supported for use with Amazon WorkSpaces.
If you configure your AWS Managed Microsoft AD directory for multi-Region replication, only the directory in the primary Region can be registered for use with Amazon WorkSpaces. Attempts to register the directory in a replicated Region for use with Amazon WorkSpaces will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.
Simple AD and AD Connector are made available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your Simple AD or AD Connector directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).  
To delete empty directories, see [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md). If you delete your Simple AD or AD Connector directory, you can always create a new one when you want to start using WorkSpaces again.

**Topics**
+ [Register an existing Directory Service directory with WorkSpaces Personal](register-deregister-directory.md)
+ [Select an organizational unit for WorkSpaces Personal](select-ou.md)
+ [Configure automatic public IP addresses for WorkSpaces Personal](automatic-assignment.md)
+ [Control device access for WorkSpaces Personal](control-device-access.md)
+ [Manage local administrator permissions for WorkSpaces Personal](local-admin-setting.md)
+ [Update the AD Connector account (AD Connector) for WorkSpaces Personal](connect-account.md)
+ [Multi-factor authentication (AD Connector) for WorkSpaces Personal](connect-mfa.md)
+ [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md)
+ [Update DNS servers for WorkSpaces Personal](update-dns-server.md)
+ [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md)
+ [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md)

# Register an existing Directory Service directory with WorkSpaces Personal
<a name="register-deregister-directory"></a>

To allow WorkSpaces to use an existing Directory Service directory, you must register it with WorkSpaces. After you register a directory, you can launch WorkSpaces in the directory.

**Requirements:** To register a directory for use with WorkSpaces, it must meet the following requirement:
+ If you're using AWS Managed Microsoft AD or Simple AD, your directory can be in a dedicated private subnet, as long as the directory has access to the VPC where the WorkSpaces are located.
+ For more information about directory and VPC design, see the [https://d1.awsstatic.com/whitepapers/Best-Practices-for-Deploying-Amazon-WorkSpaces.pdf](https://d1.awsstatic.com/whitepapers/Best-Practices-for-Deploying-Amazon-WorkSpaces.pdf) whitepaper.

**Note**  
Simple AD and AD Connector are made available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your Simple AD or AD Connector directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).  
To delete empty directories, see [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md). If you delete your Simple AD or AD Connector directory, you can always create a new one when you want to start using WorkSpaces again.

**To register an existing AWS Directory Service directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose **Create directory**.

1. On the **Create directory** page, for **WorkSpaces type** choose **Personal**. For **WorkSpace device management**, choose **AWS Directory Service**.

1. Select the directory you want to register in the **Directories in Directory Service** table

1. Select two subnets of your VPC that are not from the same Availability Zone. These subnets will be used to launch your WorkSpaces. For more information, see [Availability Zones for WorkSpaces Personal](azs-workspaces.md).
**Note**  
If you do not know which subnets to choose, select **No Preference**.

1. For **Enable Self Service Permissions**, choose **Yes** to enable your users to rebuild their WorkSpaces, change volume size, compute type and running mode. Enabling may impact how much you pay for Amazon WorkSpaces. Choose **No** otherwise.

1. Choose **Register**. Initially the value of **Registered** is `REGISTERING`. After registration is complete, the value is `Yes`.

After you've registered the Directory Service directory, you can create a personal WorkSpace. For more information, see [Create a WorkSpace in WorkSpaces Personal](create-workspaces-personal.md).

When you are finished using the directory with WorkSpaces, you can deregister it. Note that you must deregister a directory before you can delete it. If you want to deregister and delete a directory, you must first find and remove all the applications and services that are registered to the directory. For more information, see [Delete Your Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_delete.html) in the *AWS Directory Service Administration Guide*. 

**To deregister a directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select the directory.

1. Choose **Actions**, **Deregister**.

1. When prompted for confirmation, choose **Confirm**. After deregistration is complete, the directory becomes unregistered and is removed from the list.

# Select an organizational unit for WorkSpaces Personal
<a name="select-ou"></a>

**Note**  
This feature is only available for directories managed through AWS Directory Service, including AD Connector, AWS Managed Microsoft AD, and Simple AD.

WorkSpace machine accounts are placed in the default organizational unit (OU) for the WorkSpaces directory. Initially, the machine accounts are placed in the Computers OU of your directory or the directory that your AD Connector is connected to. You can select a different OU from your directory or connected directory, or specify an OU in a separate target domain. Note that you can select only one OU per directory.

After you select a new OU, the machine accounts for all WorkSpaces that are created or rebuilt are placed in the newly selected OU.

**To select an organizational unit**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose your directory.

1. Under Target domain and organizational unit, choose **Edit**.

1. To find an OU, under Target and organizational unit, you can start typing all or part of the OU name and choose the OU you want to use.

1. (Optional) Choose an OU distiguished name to overwrite your selected OU with a custom OU.

1. Choose **Save**.

1. (Optional) Rebuild the existing WorkSpaces to update the OU. For more information, see [Rebuild a WorkSpace in WorkSpaces Personal](rebuild-workspace.md).

# Configure automatic public IP addresses for WorkSpaces Personal
<a name="automatic-assignment"></a>

After you enable automatic assignment of public IP addresses, each WorkSpace that you launch is assigned a public IP address from the Amazon-provided pool of public addresses. A WorkSpace in a public subnet can access the internet through the internet gateway if it has a public IP address. WorkSpaces that already exist before you enable automatic assignment do not receive public addresses until you rebuild them.

Note that you do not need to enable automatic assignment of public addresses if your WorkSpaces are in private subnets and you configured a NAT gateway for the virtual private cloud (VPC), or if your WorkSpaces are in public subnets and you assigned them Elastic IP addresses. For more information, see [Configure a VPC for WorkSpaces Personal](amazon-workspaces-vpc.md).

**Warning**  
If you associate an Elastic IP address that you own to a WorkSpace, and then you later disassociate that Elastic IP address from the WorkSpace, the WorkSpace loses its public IP address, and it doesn't automatically get a new one from the Amazon-provided pool. To associate a new public IP address from the Amazon-provided pool with the WorkSpace, you must [rebuild the WorkSpace](rebuild-workspace.md). If you don't want to rebuild the WorkSpace, you must associate another Elastic IP address that you own to the WorkSpace.

**To configure Elastic IP addresses**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select the directory for your WorkSpaces.

1. Choose **Actions**, **Update Details**.

1. Expand **Access to Internet** and select **Enable** or **Disable**.

1. Choose **Update**.

# Control device access for WorkSpaces Personal
<a name="control-device-access"></a>

You can specify the types of devices that have access to WorkSpaces based on the device platform. You can use certificates to restrict access to WorkSpaces to trusted devices (also known as managed devices).

**To control device access to WorkSpaces**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose your directory.

1. Under Access control options, choose **Edit**.

1. Under Trusted devices, specify which device types can access WorkSpaces by selecting either **Allow all**, **Trusted devices**, or **Deny all**. For more information, see [Restrict access to trusted devices for WorkSpaces Personal](trusted-devices.md).

1. Choose **Save**.

# Manage local administrator permissions for WorkSpaces Personal
<a name="local-admin-setting"></a>

**Note**  
This feature is only available for directories managed through AWS Directory Service, including AD Connector, AWS Managed Microsoft AD, and Simple AD.

You can specify whether users are local administrators on their WorkSpaces, which enables them to install application and modify settings on their WorkSpaces. Users are local administrators by default. If you modify this setting, the change applies to all new WorkSpaces that you create and any WorkSpaces that you rebuild.

**To modify local administrator permissions**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose your directory.

1. Under Local administrator settings, choose **Edit**.

1. To ensure that users are local administrators, choose **Enable local administrator setting**.

1. Choose **Save**.

# Update the AD Connector account (AD Connector) for WorkSpaces Personal
<a name="connect-account"></a>

You can update the AD Connector account that is used to read users and groups and join WorkSpaces machine accounts to your AD Connector directory.

**To update the AD Connector account**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select your directory and then choose **View details**.

1. Under AD connector account, choose **Edit**.

1. Enter the sign-in credentials for the new account.

1. Choose **Save**.

# Multi-factor authentication (AD Connector) for WorkSpaces Personal
<a name="connect-mfa"></a>

You can enable multi-factor authentication (MFA) for your AD Connector directory. For more information about using multi-factor authentication with AWS Directory Service, see [ Enable multi-factor authentication for AD Connector](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ad_connector_mfa.html) and [ AD Connector prerequisites](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/prereq_connector.html). 

**Note**  
Your RADIUS server can either be hosted by AWS or it can be on-premises.
The usernames must match between Active Directory and your RADIUS server. 

**To enable multi-factor authentication**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select your directory and then choose **Actions**, **Update Details**.

1. Expand **Multi-Factor Authentication** and then select **Enable Multi-Factor Authentication**.

1. For **RADIUS server IP address(es)**, type the IP addresses of your RADIUS server endpoints separated by commas, or type the IP address of your RADIUS server load balancer.

1. For **Port**, type the port that your RADIUS server is using for communications. Your on-premises network must allow inbound traffic over the default RADIUS server port (UDP:1812) from AD Connector.

1. For **Shared secret code** and **Confirm shared secret code**, type the shared secret code for your RADIUS server.

1. For **Protocol**, choose the protocol for your RADIUS server.

1. For **Server timeout**, type the time, in seconds, to wait for the RADIUS server to respond. This value must be between 1 and 50.

1. For **Max retries**, type the number of times to attempt communication with the RADIUS server. This value must be between 0 and 10.

1. Choose **Update and Exit**.

Multi-factor authentication is available when **RADIUS status** is **Enabled**. While multi-factor authentication is being set up, users cannot log in to their WorkSpaces.

# Create a directory for WorkSpaces Personal
<a name="launch-workspaces-tutorials"></a>

WorkSpaces Personal allows you to use directories managed through Directory Service to store and manage information for your WorkSpaces and users. Use the following options to create a WorkSpaces Personal directory:
+ Create a Simple AD directory.
+ Create an AWS Directory Service for Microsoft Active Directory, also known as AWS Managed Microsoft AD.
+ Connect to an existing Microsoft Active Directory by using Active Directory Connector.
+ Create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain.
+ Create a dedicated Microsoft Entra ID WorkSpaces directory.
+ Create a dedicated Custom WorkSpaces directory.

**Note**  
Shared directories are not currently supported for use with Amazon WorkSpaces.
If you configure your AWS Managed Microsoft AD directory for multi-Region replication, only the directory in the primary Region can be registered for use with Amazon WorkSpaces. Attempts to register the directory in a replicated Region for use with Amazon WorkSpaces will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.
Simple AD and AD Connector are made available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your Simple AD or AD Connector directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).

## Before you create a directory
<a name="prereqs-tutorials"></a>
+ WorkSpaces is not available in every Region. Verify the supported Regions and select a Region for your WorkSpaces. For more information about the supported Regions, see [WorkSpaces Pricing by AWS Region](https://aws.amazon.com/workspaces/pricing/).
+ Create a virtual private cloud with at least two private subnets. For more information, see [Configure a VPC for WorkSpaces Personal](amazon-workspaces-vpc.md). The VPC must be connected to your on-premises network through a virtual private network (VPN) connection or Direct Connect. For more information, see [AD Connector Prerequisites](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/prereq_connector.html) in the *AWS Directory Service Administration Guide*.
+ Provide access to the internet from the WorkSpace. For more information, see [Provide internet access for WorkSpaces Personal](amazon-workspaces-internet-access.md).

For information about how to delete an empty directory, see [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md). If you delete your Simple AD or AD Connector directory, you can always create a new one when you want to start using WorkSpaces again.

**Topics**
+ [Before you create a directory](#prereqs-tutorials)
+ [Identify the computer name for your WorkSpaces Personal directory](wsp-directory-identify-computer.md)
+ [Create an AWS Managed Microsoft AD directory for WorkSpaces Personal](launch-workspace-microsoft-ad.md)
+ [Create a Simple AD directory for WorkSpaces Personal](launch-workspace-simple-ad.md)
+ [Create an AD Connector for WorkSpaces Personal](launch-workspace-ad-connector.md)
+ [Create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain for WorkSpaces Personal](launch-workspace-trusted-domain.md)
+ [Create a dedicated Microsoft Entra ID directory with WorkSpaces Personal](launch-entra-id.md)
+ [Create a dedicated Custom directory with WorkSpaces Personal](launch-custom.md)

# Identify the computer name for your WorkSpaces Personal directory
<a name="wsp-directory-identify-computer"></a>

The **Computer Name** value shown for a WorkSpace in the Amazon WorkSpaces console varies, depending on which type of WorkSpace you've launched (Amazon Linux, Ubuntu, or Windows). The computer name for a WorkSpace can be in one of these formats: 
+ **Amazon Linux**: A-*xxxxxxxxxxxxx*
+ **Red Hat Enterprise Linux**: R-*xxxxxxxxxxxxx*
+ **Rocky Linux**: R-*xxxxxxxxxxxxx*
+ **Ubuntu**: U-*xxxxxxxxxxxxx*
+ **Windows**: IP-C*xxxxxx* or WSAMZN-*xxxxxxx* or EC2AMAZ-*xxxxxxx*

For Windows WorkSpaces, the computer name format is determined by the bundle type, and in the case of WorkSpaces created from public bundles or from custom bundles based on public images, by when the public images were created.

Starting June 22, 2020, Windows WorkSpaces launched from public bundles have the WSAMZN-*xxxxxxx* format for their computer names instead of the IP-C*xxxxxx* format.

For custom bundles based on a public image, if the public image was created before June 22, 2020, the computer names are in the EC2AMAZ-*xxxxxxx* format. If the public image was created on or after June 22, 2020, the computer names are in the WSAMZN-*xxxxxxx* format. 

For Bring Your Own License (BYOL) bundles, either the DESKTOP-*xxxxxxx* or the EC2AMAZ-*xxxxxxx* format is used for the computer names by default.

If you've specified a custom format for the computer names in your custom or BYOL bundles, your custom format overrides these defaults. To specify a custom format, see [Create a custom WorkSpaces image and bundle for WorkSpaces Personal](create-custom-bundle.md).

**Important**  
After a WorkSpace is created, you can safely change its computer name. For example, you can execute a PowerShell script with the command `Rename-Computer` on your WorkSpace or remotely. The updated computer name value will then be shown for a WorkSpace in the Amazon WorkSpaces console.

# Create an AWS Managed Microsoft AD directory for WorkSpaces Personal
<a name="launch-workspace-microsoft-ad"></a>

In this tutorial, we create an AWS Managed Microsoft AD directory. For tutorials that use the other options, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

First, create an AWS Managed Microsoft AD directory. Directory Service creates two directory servers, one in each of the private subnets of your VPC. Note that there are no users in the directory initially. You will add a user in the next step when you launch the WorkSpace.

**Note**  
Shared directories are not currently supported for use with Amazon WorkSpaces.
If your AWS Managed Microsoft AD directory has been configured for multi-Region replication, only the directory in the primary Region can be registered for use with Amazon WorkSpaces. Attempts to register the directory in a replicated Region for use with Amazon WorkSpaces will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.

**To create an AWS Managed Microsoft AD directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose **Create directory**.

1. On the **Create directory** page, for **WorkSpaces type** choose **Personal**. Then, for **WorkSpace device management** choose **AWS Directory Service**.

1. Choose **Create directory**, which opens the **Set up a directory** page on the AWS Directory Service

1. Choose **AWS Managed Microsoft AD**, and then **Next**.

1. Configure the directory as follows:

   1. For **Organization name**, enter a unique organization name for your directory (for example, my-demo-directory). This name must be at least four characters in length, consist of only alphanumeric characters and hyphens (-), and begin or end with a character other than a hyphen.

   1. For **Directory DNS**, enter the fully-qualified name for the directory (for example, workspaces.demo.com).
**Important**  
If you need to update your DNS server after launching your WorkSpaces, follow the procedure in [Update DNS servers for WorkSpaces Personal](update-dns-server.md) to ensure that your WorkSpaces get properly updated.

   1. For **NetBIOS name**, enter a short name for the directory (for example, workspaces).

   1. For **Admin password** and **Confirm password**, enter a password for the directory administrator account. For more information about the password requirements, see [Create Your AWS Managed Microsoft AD Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/create_managed_ad.html) in the *AWS Directory Service Administration Guide*.

   1. (Optional) For **Description**, enter a description for the directory.

   1. For **VPC**, select the VPC that you created.

   1. For **Subnets**, select the two private subnets (with the CIDR blocks `10.0.1.0/24` and `10.0.2.0/24`).

   1. Choose **Next Step**.

1. Choose **Create directory**.

1. You will be brought back to the Create directory page on WorkSpaces console. The initial status of the directory is `Requested` and then `Creating`. When directory creation is complete (this might take a few minutes), the status is `Active`.

After you’ve created an AWS Managed Microsoft AD directory, you can register it with Amazon WorkSpaces. For more information, see [Register an existing Directory Service directory with WorkSpaces Personal](register-deregister-directory.md)

# Create a Simple AD directory for WorkSpaces Personal
<a name="launch-workspace-simple-ad"></a>

In this tutorial, we launch a WorkSpace that uses Simple AD. For tutorials that use the other options, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

**Note**  
Simple AD is not available in every AWS Region. Verify the supported Regions and [ select a Region](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/getting-started.html#select-region) for your Simple AD directory. For more information about the supported Regions for Simple AD, see [ Region Availability for AWS Directory Service](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/regions.html).
Simple AD is made available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your Simple AD directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).
[ Simple AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/simple_ad_getting_started.html) currently supports only IPv4 addressing, meaning that when creating a directory, the associated VPC will be configured with an IPv4 CIDR block and does not support IPv6 networks.

When you create a Simple AD directory. Directory Service creates two directory servers, one in each of the private subnets of your VPC. There are no users in the directory initially. Add a user after you create the WorkSpace. For more information, see [Create a WorkSpace in WorkSpaces Personal](create-workspaces-personal.md)

**To create a Simple AD directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose **Create directory**.

1. On the **Create directory** page, for **WorkSpaces type** choose **Personal**. Then, for **WorkSpace device management** choose **AWS Directory Service**.

1. Choose **Create directory**, which opens the **Set up a directory** page on the AWS Directory Service

1. Choose **Simple AD**, and then **Next**.

1. Configure the directory as follows:

   1. For **Organization name**, enter a unique organization name for your directory (for example, my-example-directory). This name must be at least four characters in length, consist of only alphanumeric characters and hyphens (-), and begin or end with a character other than a hyphen.

   1. For **Directory DNS name**, enter the fully-qualified name for the directory (for example, example.com).
**Important**  
If you need to update your DNS server after launching your WorkSpaces, follow the procedure in [Update DNS servers for WorkSpaces Personal](update-dns-server.md) to ensure that your WorkSpaces get properly updated.

   1. For **NetBIOS name**, enter a short name for the directory (for example, example).

   1. For **Admin password** and **Confirm password**, enter a password for the directory administrator account. For more information about the password requirements, see [How to Create a Microsoft AD Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/create_managed_ad.html) in the *AWS Directory Service Administration Guide*.

   1. (Optional) For **Description**, enter a description for the directory.

   1. For **Directory size**, choose **Small**.

   1. For **VPC**, select the VPC that you created.

   1. For **Subnets**, select the two private subnets (with the CIDR blocks `10.0.1.0/24` and `10.0.2.0/24`).

   1. Choose **Next**.

1. Choose **Create directory**.

1. You will be brought back to the Create directory page on WorkSpaces console. The initial status of the directory is `Requested` and then `Creating`. When directory creation is complete (this might take a few minutes), the status is `Active`.

**What happens during directory creation**

WorkSpaces completes the following tasks on your behalf:
+ Creates an IAM role to allow the WorkSpaces service to create elastic network interfaces and list your WorkSpaces directories. This role has the name `workspaces_DefaultRole`.
+ Sets up a Simple AD directory in the VPC that is used to store user and WorkSpace information. The directory has an administrator account with the user name Administrator and the specified password.
+ Creates two security groups, one for directory controllers and another for WorkSpaces in the directory.

After you’ve created an Simple AD directory, you can register it with Amazon WorkSpaces. For more information, see [Register an existing Directory Service directory with WorkSpaces Personal](register-deregister-directory.md)

# Create an AD Connector for WorkSpaces Personal
<a name="launch-workspace-ad-connector"></a>

In this tutorial, we create an AD Connector. For tutorials that use the other options, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

## Create an AD Connector
<a name="create-ad-connector"></a>

**Note**  
AD Connector is made available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your AD Connector directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).  
To delete empty directories, see [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md). If you delete your AD Connector directory, you can always create a new one when you want to start using WorkSpaces again.

**To create an AD Connector**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose **Create directory**.

1. On the **Create directory** page, for **WorkSpaces type** choose **Personal**. Then, for **WorkSpace device management** choose **AWS Directory Service**.

1. Choose **Create directory**, which opens the **Set up a directory** page on the AWS Directory Service

1. Choose **AWS Managed Microsoft AD**, and then **Next**.

1. For **Organization name**, enter a unique organization name for your directory (for example, my-example-directory). This name must be at least four characters in length, consist of only alphanumeric characters and hyphens (-), and begin or end with a character other than a hyphen.

1. For **Connected directory DNS**, enter the fully-qualified name of your on-premises directory (for example, example.com).

1. For **Connected directory NetBIOS name**, enter the short name of your on-premises directory (for example, example).

1. For **Connector account username**, enter the user name of a user in your on-premises directory. The user must have permissions to read users and groups, create computer objects, and join computers to the domain.

1. For **Connector account password** and **Confirm password**, enter the password for the on-premises user.

1. For **DNS address**, enter the IP address of at least one DNS server in your on-premises directory.
**Important**  
If you need to update your DNS server IP address after launching your WorkSpaces, follow the procedure in [Update DNS servers for WorkSpaces Personal](update-dns-server.md) to ensure that your WorkSpaces get properly updated.

1. (Optional) For **Description**, enter a description for the directory.

1. Keep **Size** as **Small**.

1. For **VPC**, select your VPC.

1. For **Subnets**, select your subnets. The DNS servers that you specified must be accessible from each subnet.

1. Choose **Create directory**.

1. You will be brought back to the Create directory page on WorkSpaces console. The initial status of the directory is `Requested` and then `Creating`. When directory creation is complete (this might take a few minutes), the status is `Active`.

# Create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain for WorkSpaces Personal
<a name="launch-workspace-trusted-domain"></a>

In this tutorial, we create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain. For tutorials that use the other options, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

**Note**  
Launching WorkSpaces with AWS accounts in a separate trusted domain works with AWS Managed Microsoft AD when it is configured with a trust relationship to your on-premises directory. However, WorkSpaces using Simple AD or AD Connector cannot launch WorkSpaces for users from a trusted domain.

**To set up the trust relationship**

1. Set up AWS Managed Microsoft AD in your virtual private cloud (VPC). For more information, see [Create Your AWS Managed Microsoft AD directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/create_managed_ad.html) in the *AWS Directory Service Administration Guide*.
**Note**  
Shared directories are not currently supported for use with Amazon WorkSpaces.
If your AWS Managed Microsoft AD directory has been configured for multi-Region replication, only the directory in the primary Region can be registered for use with Amazon WorkSpaces. Attempts to register the directory in a replicated Region for use with Amazon WorkSpaces will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.

1. Create a trust relationship between your AWS Managed Microsoft AD and your on-premises domain. Ensure that the trust is configured as a two-way trust. For more information, see [Tutorial: Create a Trust Relationship Between Your AWS Managed Microsoft AD and Your On-Premises Domain](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/tutorial_setup_trust.html) in the *AWS Directory Service Administration Guide*.

A one-way or two-way trust can be used to manage and authenticate with WorkSpaces, and so that WorkSpaces can be provisioned to on-premises users and groups. For more information, see [Deploy Amazon WorkSpaces using a One-Way Trust Resource Domain with AWS Directory Service](https://aws.amazon.com/getting-started/hands-on/deploy-workspaces-one-way-trust/).

**Note**  
Red Hat Enterprise Linux, Rocky Linux, and Ubuntu WorkSpaces use System Security Services Daemon (SSSD) for Active Directory integration, and SSSD does not support forest trust. Configure external trust instead. Two-way trust is recommended for Amazon Linux, Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces.
You cannot use a web browser (Web Access) to connect to Linux WorkSpaces.

# Create a dedicated Microsoft Entra ID directory with WorkSpaces Personal
<a name="launch-entra-id"></a>

In this tutorial, we create Bring Your Own License (BYOL) Windows 10 and 11 personal WorkSpaces that are Microsoft Entra ID joined and enrolled to Microsoft Intune. Before creating such WorkSpaces, you need to first create a dedicated WorkSpaces Personal directory for Entra ID-joined WorkSpaces.

**Note**  
Microsoft Entra joined personal WorkSpaces are available in all AWS regions where Amazon WorkSpaces is offered except for Africa (Cape Town), Israel (Tel Aviv), and China (Ningxia).

**Contents**
+ [Overview](#entra-overview)
+ [Requirements and limitations](#entra-requirements-limitation)
+ [Step 1: Enable IAM Identity Center and synchronize with Microsoft Entra ID](#entra-step-1)
+ [Step 2: Register a Microsoft Entra ID application to grant permissions for Windows Autopilot](#entra-step-2)
+ [Step 3: Configure Windows Autopilot user-driven mode](#entra-step-3)
+ [Step 4: Create an AWS Secrets Manager secret](#entra-step-4)
+ [Step 5: Create a dedicated Microsoft Entra ID WorkSpaces directory](#entra-step-5)
+ [Configure the IAM Identity Center application for a WorkSpaces directory (optional)](#configure-iam-directory)
+ [Create a cross-Region IAM Identity Center integration (optional)](#create-cross-region-iam-identity-integration)

## Overview
<a name="entra-overview"></a>

A Microsoft Entra ID personal WorkSpaces directory contains all the information needed to launch Microsoft Entra ID-joined WorkSpaces that are assigned to your users managed with Microsoft Entra ID. User information is made available to WorkSpaces through AWS IAM Identity Center, which acts as an identity broker to bring your workforce identity from Entra ID to AWS. Microsoft Windows Autopilot user-driven mode is used to accomplish WorkSpaces Intune enrollment and Entra join. The following diagram illustrates the Autopilot process.

![\[Diagram showing WorkSpaces client, service, and agent interacting with AWS and Azure components for authentication and device management.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/autopilot.jpg)


## Requirements and limitations
<a name="entra-requirements-limitation"></a>
+ Microsoft Entra ID P1 plan or higher.
+ Microsoft Entra ID and Intune is enabled and have role assignments.
+ Intune administrator - Required for managing Autopilot deployment profiles.
+ Global administrator - Required for granting admin consent for the API permissions assigned to the application created in [ step 3](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html#entra-step-3). The application can be created without this permission. However, a Global Administrator would need to provide admin consent on the application permissions.
+ Assign Windows 10/11 VDA E3 or E5 user subscription licenses to your WorkSpaces users.
+ Entra ID directories only support Windows 10 or 11 Bring Your Own License personal WorkSpaces. The following are supported versions.
  + Windows 10 Version 21H2 (December 2021 Update)
  + Windows 10 Version 22H2 (November 2022 Update)
  + Windows 11 Enterprise 23H2 (October 2023 release)
  + Windows 11 Enterprise 22H2 (October 2022 release)
  + Windows 11 Enterprise 24H2 (October 2024 release)
  + Windows 11 Enterprise 25H2 (September 2025 release)
+ Bring Your Own License (BYOL) is enabled for your AWS account and you have a valid Windows 10 or 11 BYOL image imported in your account. For more information, see [Bring Your Own Windows desktop licenses in WorkSpaces](byol-windows-images.md).
+ Microsoft Entra ID directories only support Windows 10 or 11 BYOL personal WorkSpaces.
+ Microsoft Entra ID directories support only DCV protocol.
+ If you are using a firewall for your WorkSpaces, make sure it does not block the outbound traffic to the endpoints for Microsoft Intune and Windows Autopilot. Please review [Network endpoints for Microsoft Intune - Microsoft Intune](https://learn.microsoft.com/en-us/intune/intune-service/fundamentals/intune-endpoints?tabs=north-america) and [Windows Autopilot requirements](https://learn.microsoft.com/en-us/autopilot/requirements?tabs=networking) for details.
+ Microsoft Entra ID directories do not support Microsoft Entra ID tenants in Government Community Cloud High (GCCH) and Department of Defense (DoD) environments.

## Step 1: Enable IAM Identity Center and synchronize with Microsoft Entra ID
<a name="entra-step-1"></a>

To create Microsoft Entra ID-joined personal WorkSpaces and assign them to your Entra ID users, you have to make the user information available to AWS through IAM Identity Center. IAM Identity Center is the recommended AWS service for managing user access to AWS resources. For more information, see [ What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). This is a one-time setup.

If you don’t have an existing IAM Identity Center instance to integrate with your WorkSpaces, we recommend that you create one in the same Region as your WorkSpaces. If you have an existing AWS Identity Center instance in a different Region, you can set up cross-Region integration. For more information about cross-Region setup, see [Create a cross-Region IAM Identity Center integration (optional)](#create-cross-region-iam-identity-integration). 

**Note**  
Cross-region integration between WorkSpaces and IAM Identity Center is not supported in AWS GovCloud (US) Region.

1. Enable IAM Identity Center with your AWS Organizations, especially if you are using a multi-account environment. You can also create an account instance of IAM Identity Center. To learn more, see [ Enabling AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-set-up-for-idc.html). Each WorkSpaces directory can be associated with one IAM Identity Center instance, organization or account. 

   If you are using an organization instance and trying to create a WorkSpaces directory in one of the member accounts, make sure you have the following IAM Identity Center permissions.
   + `"sso:DescribeInstance"`
   + `"sso:CreateApplication"`
   + `"sso:PutApplicationGrant"`
   + `"sso:PutApplicationAuthenticationMethod"`
   + `"sso:DeleteApplication"`
   + `"sso:DescribeApplication"`
   + `"sso:getApplicationGrant"`

   For more information, see [ Overview of managing access permissions to your IAM Identity Center resources](https://docs.aws.amazon.com/singlesignon/latest/userguide/iam-auth-access-overview.html). Also, ensure that no Service Control Policies (SCPs) are blocking these permissions. To learn more about SCPs, see [ Service control policies (SCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html).

1. Configure IAM Identity Center and Microsoft Entra ID to automatically synchronize selected or all users from your Entra ID tenant to your IAM Identity Center instance. For more information, see [ Configure SAML and SCIM with Microsoft Entra ID and IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/idp-microsoft-entra.html) and [ Tutorial: Configure AWS IAM Identity Center for automatic user provisioning](https://learn.microsoft.com/en-us/entra/identity/saas-apps/aws-single-sign-on-provisioning-tutorial).

1. Verify that the users you configured on Microsoft Entra ID are synchronized correctly to AWS IAM Identity Center instance. If you see an error message in Microsoft Entra ID, it indicates that the user in Entra ID is configured in a way that IAM Identity Center doesn’t support. The error message will identify this issue. For example, if the user object in Entra ID lacks a first name, a last name, and/or a display name, you’ll receive an error message similar to `"2 validation errors detected: Value at 'name.givenName' failed to satisfy constraint: Member must satisfy regular expression pattern: [\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}\\t\\n\\r ]+; Value at 'name.givenName' failed to satisfy constraint: Member must have length greater than or equal to 1"`. For more information, see [ Specific users fail to synchronize into IAM Identity Center from an external SCIM provider](https://docs.aws.amazon.com/singlesignon/latest/userguide/troubleshooting.html#issue2).

**Note**  
WorkSpaces uses Entra ID UserPrincipalName (UPN) attribute to identify individual users and the following are its limitations:  
UPNs cannot exceed 63 characters in length.
If you change the UPN after assigning a WorkSpace to a user, the user won't be able to connect to their WorkSpace unless you change the UPN back to what it was before.

## Step 2: Register a Microsoft Entra ID application to grant permissions for Windows Autopilot
<a name="entra-step-2"></a>

WorkSpaces Personal uses Microsoft Windows Autopilot user-driven mode to enroll WorkSpaces to Microsoft Intune and join them to Microsoft Entra ID.

To allow Amazon WorkSpaces to register WorkSpaces Personal into Autopilot, you must register a Microsoft Entra ID application that grants necessary Microsoft Graph API permissions. For more information about registering an Entra ID application, see [ Quickstart: Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate).

We recommend providing the following API permissions in your Entra ID application.
+ To create a new personal WorkSpace that needs to be joined to Entra ID, following API permission is required.
  + `DeviceManagementServiceConfig.ReadWrite.All`
+ When you terminate a personal WorkSpace or rebuild it, the following permissions are used. 
**Note**  
If you don’t provide these permissions, WorkSpace will be terminated but it will not be removed from your Intune and Entra ID tenants and you will have to remove them separately.
  + `DeviceManagementServiceConfig.ReadWrite.All`
  + `Device.ReadWrite.All`
  + `DeviceManagementManagedDevices.ReadWrite.All`
+ These permissions require admin consent. For more information, see [ Grant tenant-wide admin consent to an application ](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal).

Next, you must add a client secret for the Entra ID application. For more information, see [ Add credentials](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate#add-credentials). Make sure you remember the client secret string as you will need it when creating the AWS Secrets Manager secret in Step 4.

## Step 3: Configure Windows Autopilot user-driven mode
<a name="entra-step-3"></a>

Ensure you are familiar with the [ Step by step tutorial for Windows Autopilot user-driven Microsoft Entra join in Intune](https://learn.microsoft.com/en-us/autopilot/tutorial/user-driven/azure-ad-join-workflow).

**To configure your Microsoft Intune for Autopilot**

1. Sign into the Microsoft Intune admin center

1. Create a new Autopilot device group for personal WorkSpaces. For more information, see [Create device groups for Windows Autopilot](https://learn.microsoft.com/en-us/autopilot/enrollment-autopilot).

   1. Choose **Groups**, **New group**

   1. For **Group type**, choose **Security**.

   1. For **Membership type**, choose **Dynamic Device**.

   1. Choose **Edit dynamic query** to create a dynamic membership rule. The rule should be in the following format:

      ```
      (device.devicePhysicalIds -any (_ -eq "[OrderID]:WorkSpacesDirectoryName"))
      ```
**Important**  
`WorkSpacesDirectoryName` should match the directory name of the Entra ID WorkSpaces Personal directory you create in step 5. This is because the directory name string is used as group tag when WorkSpaces registers virtual desktops into Autopilot. Additionally, group tag maps to the `OrderID` attribute on Microsoft Entra devices. 

1. Choose **Devices**, **Windows**, **Enrollment**. For **Enrollment Options**, choose **Automatic Enrollment**. For **MDM user scope** select **All**.

1. Create an Autopilot deployment profile. For more information, see [ Create an Autopilot deployment profile](https://learn.microsoft.com/en-us/autopilot/profiles#create-an-autopilot-deployment-profile).

   1. For **Windows Autopilot**, choose **Deployment profiles**, **Create profile**.

   1. In the **Windows Autopilot deployment profiles** screen, select the **Create Profile** drop down menu and then select **Windows PC**.

   1. In the **Create profile** screen, on **On the Out-of-box experience (OOBE)** page. For **Deployment mode**, select **User-driven**. For **Join to Microsoft Entra ID**, select **Microsoft Entra joined**. You can customize the computer names for your Entra ID-joined personal WorkSpaces by selecting **Yes** for **Apply device name template**, to create a template to use when naming a device during enrollment.

   1. On the **Assignments** page, for **Assign to**, choose **Selected groups**. Choose **Select groups to include**, and select the Autopilot device group you’ve just created in 2.

## Step 4: Create an AWS Secrets Manager secret
<a name="entra-step-4"></a>

You must create a secret in AWS Secrets Manager to securely store the information, including the application ID and client secret, for the Entra ID application you created in [Step 2: Register a Microsoft Entra ID application to grant permissions for Windows Autopilot](#entra-step-2). This is a one-time setup. 

**To create an AWS Secrets Manager secret**

1. Create a customer managed key on [AWS Key Management Service](https://aws.amazon.com/kms/). The key will later be used to encrypt the AWS Secrets Manager secret. Don't use the default key to encrypt your secret as the default key cannot be accessed by the WorkSpaces service. Follow the steps below to create the key.

   1. Open the AWS KMS console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).

   1. To change the AWS Region, use the Region selector in the upper-right corner of the page.

   1. Choose **Create key**.

   1. On the **Configure key** page, for **Key type** choose **Symmetric**. For **Key usage**, choose **Encrypt and decrypt**.

   1. On the **Review** page, in the Key policy editor, ensure you allow the WorkSpaces service's principal `workspaces.amazonaws.com` access to the key by including following permissions in the key policy.

      ```
      {
          "Effect": "Allow",
          "Principal": {
              "Service": [
                  "workspaces.amazonaws.com"
              ]
          },
          "Action": [
              "kms:Decrypt",
              "kms:DescribeKey"
          ],
          "Resource": "*"
       }
      ```

1. Create the secret on AWS Secrets Manager, using the AWS KMS key created in previous step.

   1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).

   1. Choose **Store a new secret**.

   1. On the **Choose secret type** page, for **Secret type**, select **Other type of secret**.

   1. For **Key/value pairs**, in the key box, enter “application\$1id” into the key box, then copy the Entra ID application ID from [Step 2](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html#entra-step-2) and paste it into the value box.

   1. Choose **Add row**, in the key box, enter “application\$1password”, then copy the Entra ID application client secret from [Step 2](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html#entra-step-2) and paste it into the value box.

   1. Choose the AWS KMS key that you created in the previous step from the **Encryption key** drop-down list.

   1. Choose **Next**.

   1. On the **Configure secret** page, enter a **Secret name** and **Description**.

   1. In the **Resource permissions** section, choose **Edit permissions**.

   1. Make sure you allow the WorkSpaces service's principal `workspaces.amazonaws.com` access to the secret by including following resource policy in the resource permissions.

------
#### [ JSON ]

****  

      ```
      {
        "Version":"2012-10-17",		 	 	 
        "Statement" : [ {
          "Effect" : "Allow",
          "Principal" : {
            "Service" : [ "workspaces.amazonaws.com"]
          },
          "Action" : "secretsmanager:GetSecretValue",
          "Resource" : "*"
        } ]
      }
      ```

------

## Step 5: Create a dedicated Microsoft Entra ID WorkSpaces directory
<a name="entra-step-5"></a>

Create a dedicated WorkSpaces directory that stores information for your Microsoft Entra ID-joined WorkSpaces and Entra ID users.

**To create an Entra ID WorkSpaces directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. On the **Create directory** page, for **WorkSpaces type** choose **Personal**. For **WorkSpace device management**, choose **Microsoft Entra ID**.

1. For **Microsoft Entra tenant ID**, enter your Microsoft Entra ID tenant ID that you want your directory's WorkSpaces to join to. You won't be able to change the tenant ID after the directory is created. 

1. For **Entra ID Application ID and password**, select the AWS Secrets Manager secret that you created in [Step 4](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html#entra-step-4) from the drop down list. You won't be able to change the secret associated with the directory after the directory is created. However, you can always update the content of the secret, including the Entra ID Application ID and its password through the AWS Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).

1. If your IAM Identity Center instance is in the same AWS Region as your WorkSpaces directory, for **User identity source**, select the IAM Identity Center instance that you configured in [Step 1](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html#entra-step-1) from the dropdown list. You won't be able to change the IAM Identity Center instance associated with the directory after the directory is created.

   If your IAM Identity Center instance is in a different AWS Region than your WorkSpaces directory, choose **Enable Cross-Region** and then select the Region from the dropdown list.
**Note**  
If you have an existing IAM Identity Center instance in a different Region, you must opt-in to set up a cross-Region integration. For more information about cross-Region setup, see [Create a cross-Region IAM Identity Center integration (optional)](#create-cross-region-iam-identity-integration). 

1. For **Directory name**, enter a unique name for the directory (For example, `WorkSpacesDirectoryName`).
**Important**  
The directory name should match the `OrderID` used to construct the dynamic query for the Autopilot device group that you created with Microsoft Intune in [Step 3](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html#entra-step-3). The directory name string is used as the group tag when registering personal WorkSpaces into Windows Autopilot. The group tag maps to the `OrderID` attribute on Microsoft Entra devices.

1. (Optional) For **Description**, enter a description for the directory.

1. For **VPC**, select the VPC that you used to launch your WorkSpaces. For more information, see [Configure a VPC for WorkSpaces Personal](amazon-workspaces-vpc.md).

1. For **Subnets**, select two subnets of your VPC that are not from the same Availability Zone. These subnets will be used to launch your personal WorkSpaces. For more information, see [Availability Zones for WorkSpaces Personal](azs-workspaces.md).
**Important**  
Make sure the WorkSpaces launched in the subnets have internet access, which is needed when users login to the Windows desktops. For more information, see [Provide internet access for WorkSpaces Personal](amazon-workspaces-internet-access.md).

1. For **Configuration**, select **Enable dedicated WorkSpace**. You must enable it to create a dedicated WorkSpaces Personal directory to launch Bring Your Own License (BYOL) Windows 10 or 11 personal WorkSpaces. 
**Note**  
If you don't see the **Enable dedicated WorkSpace** option under **Configuration**, your account hasn't been enabled for BYOL. To enable BYOL for your account, see [Bring Your Own Windows desktop licenses in WorkSpaces](byol-windows-images.md).

1. (Optional) For **Tags**, specify the key pair value that you want to use for personal WorkSpaces in the directory.

1. Review the directory summary and choose **Create directory**. It takes several minutes for your directory to be connected. The initial status of the directory is `Creating`. When directory creation is complete, the status is `Active`. 

An IAM Identity Center application is also automatically created on your behalf once the directory is created. To find the application’s ARN go to the directory's summary page.

You can now use the directory to launch Windows 10 or 11 personal WorkSpaces that are enrolled to Microsoft Intune and joined to Microsoft Entra ID. For more information, see [Create a WorkSpace in WorkSpaces Personal](create-workspaces-personal.md). 

After you've created a WorkSpaces Personal directory, you can create a personal WorkSpace. For more information, see [Create a WorkSpace in WorkSpaces Personal](create-workspaces-personal.md)

## Configure the IAM Identity Center application for a WorkSpaces directory (optional)
<a name="configure-iam-directory"></a>

A corresponding IAM Identity Center application is automatically created once a directory is created. You can find the application’s ARN in the Summary section on the directory detail page. By default, all users in the Identity Center instance can access their assigned WorkSpaces without configuring the corresponding Identity Center application. However, you can manage user access to WorkSpaces in a directory by configuring the user assignment for the IAM Identity Center application.

**To configure the user assignment for the IAM Identity Center application**

1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. On the **AWS managed applications** tab, choose the application for the WorkSpaces directory. The application names are in the following format: `WorkSpaces.wsd-xxxxx`, where `wsd-xxxxx` is the WorkSpaces directory ID.

1. Choose **Actions**, **Edit details**.

1. Change the **User and group assignment method** from **Do not require assignments** to **Require assignments**.

1. Choose **Save changes**.

After you make this change, users in the Identity Center instance will lose access their assign WorkSpaces unless they are assigned to the application. To assign your users to the application, use the AWS CLI command `create-application-assignment` to assign users or groups to an application. For more information, see the [AWS CLI Command Reference](https://docs.aws.amazon.com//cli/latest/reference/sso-admin/create-application-assignment.html).

## Create a cross-Region IAM Identity Center integration (optional)
<a name="create-cross-region-iam-identity-integration"></a>

We recommend that your WorkSpaces and the associated IAM Identity Center instance are in the same AWS Region. However, if you already have an IAM Identity Center instance configured in a different Region from your WorkSpaces Region, you can create a cross-Region integration. When you create a cross-Region WorkSpaces and IAM Identity Center integration, you enable WorkSpaces to make cross-Region calls to access and store information from your IAM Identity Center instance, such as user and group attributes.

**Important**  
Amazon WorkSpaces supports cross-Region IAM Identity Center and WorkSpaces integrations only for organization-level instances. WorkSpaces doesn't support cross-Region IAM Identity Center integrations for account-level instances. For more information about IAM Identity Center instance types and their use cases, see, [Understanding types of IAM Identity Center instances](https://docs.aws.amazon.com//amazonq/latest/qbusiness-ug/setting-up.html#idc-instance-types).

If you create a cross-Region integration between a WorkSpaces directory and an IAM Identity Center instance, you may experience higher latency when deploying WorkSpaces and during login because of cross-Region calls. The increase in latency is proportional to the distance between your WorkSpaces Region and the IAM Identity Center Region. We recommend that you perform latency tests for your specific use case.

 You can enable cross-Region IAM Identity Center connections during [Step 5: Create a dedicated Microsoft Entra ID WorkSpaces directory](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-entra-id.html#entra-step-5). For **User identity source**, choose the IAM Identity Center instance that you configured in [Step 1: Enable IAM Identity Center and synchronize with Microsoft Entra ID](#entra-step-1) from the dropdown menu. 

**Important**  
You can't change the IAM Identity Center instance associated with the directory after you create it.

# Create a dedicated Custom directory with WorkSpaces Personal
<a name="launch-custom"></a>

Before you create Windows 10 and 11 BYOL personal WorkSpaces and assign them to your users, managed with AWS IAM Identity Center Identity Providers (IdPs), you must create a dedicated Custom WorkSpaces directory. Personal WorkSpaces are not joined to any Microsoft Active Directory but can be managed with a Mobile Device Management (MDM) solution of your choice, such as JumpCloud. For more information about JumpCloud, see [this article](https://jumpcloud.com/support/integrate-with-aws-workspaces). For tutorials that use the other options, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).

**Note**  
Amazon WorkSpaces can't create or manage user accounts on personal WorkSpaces launched in a Custom directory. As an administrator, you will have to manage them.
Custom WorkSpaces directory is available in all AWS regions where Amazon WorkSpaces is offered except for Africa (Cape Town), Israel (Tel Aviv), and China (Ningxia).
Amazon WorkSpaces can't create or manage user accounts on WorkSpaces using Custom directories. To ensure the MDM agent software you use can create the user profile on the Windows WorkSpaces, contact the MDM solution providers. Creating the user profile allows your users to sign into the Windows desktop from Windows login screen.

**Contents**
+ [Requirements and limitations](#custom-requirements-limitations)
+ [Step 1: Enable IAM Identity Center and connect with your Identity Provider](#custom-step-1)
+ [Step 2: Create a dedicated Custom WorkSpaces directory](#custom-step-2)

## Requirements and limitations
<a name="custom-requirements-limitations"></a>
+ Custom WorkSpaces directories only support Windows 10 or 11 Bring Your Own License personal WorkSpaces.
+ Custom WorkSpaces directories only support DCV protocol.
+ Ensure you enable BYOL for your AWS account and you have your own AWS KMS server that your personal WorkSpaces can access for Windows 10 and 11 activation. For details, see [Bring Your Own Windows desktop licenses in WorkSpaces](byol-windows-images.md).
+ Ensure you pre-install the MDM agent software on the BYOL image that you imported to your AWS account.

## Step 1: Enable IAM Identity Center and connect with your Identity Provider
<a name="custom-step-1"></a>

To assign WorkSpaces to your users managed with your Identity Providers, the user information must be made available to AWS through AWS IAM Identity Center. We recommend using IAM Identity Center to manage your user's access to AWS resources. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). This is a one-time setup.

**To make user information available to AWS**

1. Enable IAM Identity Center on AWS. You can enable IAM Identity Center with your AWS organizations, especially if you are using a multi-account environment. You can also create an account instance of IAM Identity Center. For more information, see [ Enabling AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-set-up-for-idc.html). Each WorkSpaces directory can associate with one IAM Identity Center organization or account instance. Each IAM Identity Center instance can be associated with one or more WorkSpaces Personal directory.

   If you are using an organization instance and trying to create a WorkSpaces directory in one of the member accounts, ensure you have the following IAM Identity Center permissions. 
   + `"sso:DescribeInstance"`
   + `"sso:CreateApplication"`
   + `"sso:PutApplicationGrant"`
   + `"sso:PutApplicationAuthenticationMethod"`
   + `"sso:DeleteApplication"`
   + `"sso:DescribeApplication"`
   + `"sso:getApplicationGrant"`

   For more information, see [ Overview of managing access permissions to your IAM Identity Center resources](https://docs.aws.amazon.com/singlesignon/latest/userguide/iam-auth-access-overview.html). Ensure that no Service Control Policies (SCPs) are blocking these permissions. To learn more about SCPs, see [ Service control policies (SCPs)](https://docs.aws.amazon.com/userguide/orgs_manage_policies_scps.html).

1. Configure IAM Identity Center and your Identity Provider (IdP) to automatically synchronize users from your IdP to your IAM Identity Center instance. For more information, see [ Getting started tutorials](https://docs.aws.amazon.com/singlesignon/latest/userguide/tutorials.html) and choose the specific tutorial for the IdP that you want to use. For example, [ Using IAM Identity Center to connect with your JumpCloud Directory Platform](https://docs.aws.amazon.com/singlesignon/latest/userguide/jumpcloud-idp.html).

1. Verify that the users you configured on your IdP are synchronized correctly to AWS IAM Identity Center instance. The first synchronization can take up to an hour depending the configuration of your IdP. 

## Step 2: Create a dedicated Custom WorkSpaces directory
<a name="custom-step-2"></a>

Create a dedicated WorkSpaces Personal directory that stores information about your personal WorkSpaces and your users.

**To create a dedicated Custom WorkSpaces directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose **Create directory**.

1. On the **Create directory** page, for **WorkSpaces** type, choose **Personal**. For **WorkSpace device management**, choose **Custom**.

1. For **User identity source**, select the IAM Identity Center instance that you configured in [Step 1](https://docs.aws.amazon.com/) from the dropdown list. You won't be able to change the IAM Identity Center instance associated with the directory once the directory is created.
**Note**  
You have to specify an IAM Identity Center instance for the directory or you won't be able to launch personal WorkSpaces with the directory using the WorkSpaces console. WorkSpaces directories with no associated Identity Center are only compatible with WorkSpaces Core partner solutions.

1. For **Directory name**, enter a unique name for the directory.

1. For **VPC**, select the VPC that you used to launch your WorkSpaces. For more information, see [Configure a VPC for WorkSpaces Personal](amazon-workspaces-vpc.md).

1. For **Subnets**, select two subnets of your VPC that are not from the same Availability Zone. These subnets will be used to launch your personal WorkSpaces. For more information, see [Availability Zones for WorkSpaces Personal](azs-workspaces.md).
**Important**  
Make sure the WorkSpaces launched in the subnets have internet access, which is needed when users login to the Windows desktops. For more information, see [Provide internet access for WorkSpaces Personal](amazon-workspaces-internet-access.md).

1. For **Configuration**, select **Enable dedicated WorkSpace**. You must enable it to create a dedicated WorkSpaces Personal directory to launch Bring Your Own License (BYOL) Windows 10 or 11 personal WorkSpaces. 

1. (Optional) For **Tags**, specify the key pair value that you want to use for personal WorkSpaces in the directory.

1. Review the directory summary and choose **Create directory**. It takes several minutes for your directory to be connected. The initial status of the directory is `Creating`. When directory creation is complete, the status is `Active`. 

An IAM Identity Center application is also automatically created on your behalf once the directory is created. To find the application’s ARN go to the directory's summary page.

You can now use the directory to launch Windows 10 or 11 personal WorkSpaces that are enrolled to Microsoft Intune and joined to Microsoft Entra ID. For more information, see [Create a WorkSpace in WorkSpaces Personal](create-workspaces-personal.md). 

After you've created a WorkSpaces Personal directory, you can create a personal WorkSpace. For more information, see [Create a WorkSpace in WorkSpaces Personal](create-workspaces-personal.md)

# Update DNS servers for WorkSpaces Personal
<a name="update-dns-server"></a>

If you need to update the DNS server IP addresses for your Active Directory after launching your WorkSpaces, you must also update your WorkSpaces with the new DNS server settings.

You can update your WorkSpaces with the new DNS settings in one of the following ways:
+ Update the DNS settings on the WorkSpaces **before** you update the DNS settings for Active Directory.
+ Rebuild the WorkSpaces **after** you update the DNS settings for Active Directory.

We recommend updating the DNS settings on the WorkSpaces before updating the DNS settings in Active Directory (as explained in [Step 1](#update-registry-dns) of the following procedure).

If you want to rebuild the WorkSpaces instead, update one of the DNS server IP addresses in your Active Directory ([Step 2](#update-dns-active-directory)), and then follow the procedure in [Rebuild a WorkSpace in WorkSpaces Personal](rebuild-workspace.md) to rebuild your WorkSpaces. After you've rebuilt your WorkSpaces, follow the procedure in [Step 3](#test-updated-dns-settings) to test your DNS server updates. After completing that step, update the IP address of your second DNS server in Active Directory, and then rebuild your WorkSpaces again. Be sure to follow the procedure in [Step 3](#test-updated-dns-settings) to test your second DNS server update. As noted in the [ Best Practices](#update-dns-best-practices) section, we recommend updating your DNS server IP addresses one at a time. 

## Best practices
<a name="update-dns-best-practices"></a>

When you're updating your DNS server settings, we recommend the following best practices:
+ To avoid disconnections and inaccessibility of domain resources, we strongly recommend performing DNS server updates during off-peak hours or during a planned maintenance period.
+ Don't launch any new WorkSpaces during the 15 minutes before and the 15 minutes after changing your DNS server settings.
+ When updating your DNS server settings, change one DNS server IP address at a time. Verify that the first update is correct before updating the second IP address. We recommend performing the following procedure ([Step 1](#update-registry-dns), [Step 2](#update-dns-active-directory), and [Step 3](#test-updated-dns-settings)) twice to update the IP addresses one at a time.

## Step 1: Update the DNS server settings on your WorkSpaces
<a name="update-registry-dns"></a>

In the following procedure, the current and new DNS server IP address values are referred to as follows:
+ Current DNS IP addresses: `OldIP1`, `OldIP2`
+ New DNS IP addresses: `NewIP1`, `NewIP2`

**Note**  
 If this is the second time you're performing this procedure, replace `OldIP1` with `OldIP2` and `NewIP1` with `NewIP2`.

### Update the DNS server settings for Windows WorkSpaces
<a name="update-registry-dns-windows"></a>

If you have multiple WorkSpaces, you can deploy the following registry update to the WorkSpaces by applying a Group Policy Object (GPO) on the Active Directory OU for your WorkSpaces. For more information about working with GPOs, see [Manage your Windows WorkSpaces in WorkSpaces Personal](group_policy.md).

You can make these updates either by using the Registry Editor or by using Windows PowerShell. Both procedures are described in this section.

**To update the DNS registry settings using the Registry Editor**

1. On your Windows WorkSpace, open the Windows search box, and enter **registry editor** to open the Registry Editor (**regedit.exe**). 

1. When asked "Do you want to allow this app to make changes to your device?", choose **Yes**.

1. In the Registry Editor, navigate to the following registry entry:

   **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1SkyLight**

1. Open the **DomainJoinDns** registry key. Update `OldIP1` with `NewIP1`, and then choose **OK**.

1. Close the Registry Editor.

1. Reboot the WorkSpace, or restart the service SkyLightWorkspaceConfigService.
**Note**  
After you restart the service SkyLightWorkspaceConfigService, it can take up to 1 minute for the network adapter to reflect the change.

1. Proceed to [Step 2](#update-dns-active-directory), and update your DNS server settings in Active Directory to replace `OldIP1` with `NewIP1`.

**To update the DNS registry settings using PowerShell**

The following procedure uses PowerShell commands to update your registry and restart the service SkyLightWorkspaceConfigService.

1. On your Windows WorkSpace, open the Windows search box, and enter **powershell**. Choose **Run as Administrator**.

1. When asked "Do you want to allow this app to make changes to your device?", choose **Yes**.

1. In the PowerShell window, run the following command to retrieve the current DNS server IP addresses.

   ```
   Get-ItemProperty -Path HKLM:\SOFTWARE\Amazon\SkyLight -Name DomainJoinDNS
   ```

   You should receive the following output.

   ```
   DomainJoinDns : OldIP1,OldIP2
   PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\SkyLight
   PSParentPath  : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Amazon
   PSChildName   : SkyLight
   PSDrive       : HKLM
   PSProvider    : Microsoft.PowerShell.Core\Registry
   ```

1. In the PowerShell window, run the following command to change `OldIP1` to `NewIP1`. Be sure to leave `OldIP2` as is for now.

   ```
   Set-ItemProperty -Path HKLM:\SOFTWARE\Amazon\SkyLight -Name DomainJoinDNS -Value "NewIP1,OldIP2"
   ```

1. Run the following command to restart the service SkyLightWorkspaceConfigService.

   ```
   restart-service -Name SkyLightWorkspaceConfigService
   ```
**Note**  
After you restart the service SkyLightWorkspaceConfigService, it can take up to 1 minute for the network adapter to reflect the change.

1. Proceed to [Step 2](#update-dns-active-directory), and update your DNS server settings in Active Directory to replace `OldIP1` with `NewIP1`.

### Update the DNS server settings for Amazon Linux 2 WorkSpaces
<a name="update-registry-dns-linux"></a>

If you have more than one Amazon Linux 2 WorkSpace, we recommend that you use a configuration management solution to distribute and enforce policy. For example, you can use [Ansible](https://www.ansible.com/).

**To update the DNS server settings on a Amazon Linux 2 WorkSpace**

1. On your Linux WorkSpace, open a Terminal window.

1. Use the following Linux command to edit the `/etc/dhcp/dhclient.conf` file. You must have root user privileges to edit this file. Either become root by using the `sudo -i` command, or run all commands with `sudo` as shown.

   ```
   sudo vi /etc/dhcp/dhclient.conf
   ```

   In the `/etc/dhcp/dhclient.conf` file, you will see the following `prepend` command, where `OldIP1` and `OldIP2` are the IP addresses of your DNS servers.

   ```
   prepend domain-name-servers OldIP1, OldIP2; # skylight
   ```

1. Replace `OldIP1` with `NewIP1`, and leave `OldIP2` as is for now.

1. Save your changes to `/etc/dhcp/dhclient.conf`.

1. Reboot the WorkSpace.

1. Proceed to [Step 2](#update-dns-active-directory), and update your DNS server settings in Active Directory to replace `OldIP1` with `NewIP1`.

### Update the DNS server settings for Ubuntu WorkSpaces
<a name="update-registry-dns-ubuntu"></a>

If you have more than one Ubuntu WorkSpace, we recommend that you use a configuration management solution to distribute and enforce policy. For example, you can use [Landscape](https://ubuntu.com/landscape).

**To update the DNS server settings on a Ubuntu WorkSpace**

1. On your Ubuntu WorkSpace, open a Terminal window and run the following command. You must have root user privileges to edit this file. Either become root by using the `sudo -i` command, or run all commands with `sudo` as shown.

   ```
   sudo vi /etc/netplan/zz-workspaces-domain.yaml
   ```

1. In the yaml file, you will see the following `nameserver` command.

   ```
   nameservers:
       search:[Your domain FQDN]
       addresses:[OldIP1, OldIP2]
   ```

   Replace the `OldIP1` and `OldIP2` with the `NewIP1` and `NewIP2`.

   If you have multiple DNS servers IP addesses, add them as comma separated values. For example, `[NewDNSIP1, NewDNSIP2, NewDNSIP3]`.

1. Save the yaml file.

1. Run the command `sudo netplan apply` to apply the changes.

1. Run the command `resolvectl status` to verify that the new DNS IP address is being used.

1. Proceed to [Step 2](#update-dns-active-directory), and update your DNS server settings in Active Directory.

### Update the DNS server settings for Red Hat Enterprise Linux WorkSpaces
<a name="update-registry-dns-rhel"></a>

If you have more than one Red Hat Enterprise Linux WorkSpace, we recommend that you use a configuration management solution to distribute and enforce policy. For example, you can use [Ansible](https://www.ansible.com/).

**To update the DNS server settings on a Red Hat Enterprise Linux WorkSpace**

1. On your Red Hat Enterprise Linux WorkSpace, open a Terminal window and run the command below. You must have root user privileges to edit this file. Either become root by using the `sudo -i` command, or run all commands with `sudo` as shown.

   ```
   sudo nmcli conn modify CustomerNIC ipv4.dns 'NewIP1 NewIP2'
   ```

1. Run the following command.

   ```
   sudo systemctl restart NetworkManager
   ```

1. To check the updated DNS and network configuration run the following command.

   ```
   nmcli device show eth1
   ```

1. Proceed to [Step 2](#update-dns-active-directory), and update your DNS server settings in Active Directory.

## Step 2: Update the DNS server settings for Active Directory
<a name="update-dns-active-directory"></a>

In this step, you update your DNS server settings for Active Directory. As noted in the [Best Practices](#update-dns-best-practices) section, we recommend updating your DNS server IP addresses one at a time.

To update your DNS server settings for Active Directory, see the following documentation in the *AWS Directory Service Administration Guide*:
+ **AD Connector**: [ Update the DNS Address for Your AD Connector](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ad_connector_update_dns.html)
+ **AWS Managed Microsoft AD**: [ Configure DNS Conditional Forwarders for Your On-premises Domain](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_tutorial_setup_trust_prepare_onprem.html#tutorial_setup_trust_onprem_forwarder)
+ **Simple AD**: [ Configure DNS](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/simple_ad_dns.html)

After updating your DNS server settings, proceed to [Step 3](#test-updated-dns-settings).

## Step 3: Test the updated DNS server settings
<a name="test-updated-dns-settings"></a>

After completing [Step 1](#update-registry-dns) and [Step 2](#update-dns-active-directory), use the following procedure to verify that your updated DNS server settings are working as expected.

In the following procedure, the current and new DNS server IP address values are referred to as follows:
+ Current DNS IP addresses: `OldIP1`, `OldIP2`
+ New DNS IP addresses: `NewIP1`, `NewIP2`

**Note**  
If this is the second time you're performing this procedure, replace `OldIP1` with `OldIP2` and `NewIP1` with `NewIP2`.

### Test the updated DNS server settings for Windows WorkSpaces
<a name="test-updated-dns-settings-windows"></a>

1. Shut down the `OldIP1` DNS server.

1. Log in to a Windows WorkSpace.

1. On the Windows **Start** menu, choose **Windows System**, then choose **Command Prompt**.

1. Run the following command, where `AD_Name` is the name of your Active Directory (for example, `corp.example.com`).

   ```
   nslookup AD_Name
   ```

   The `nslookup` command should return the following output. (If this is the second time you're performing this procedure, you should see `NewIP2` in place of `OldIP2`.)

   ```
   Server:  Full_AD_Name
   Address:  NewIP1
   
   Name:    AD_Name
   Addresses:  OldIP2
             NewIP1
   ```

1. If the output is not what you were expecting or if you receive any errors, repeat [Step 1](#update-registry-dns).

1. Wait for an hour and confirm that no user issues have been reported. Verify that `NewIP1` is getting DNS queries and responding with answers.

1. After you've verified that the first DNS server is working properly, repeat [Step 1](#update-registry-dns) to update the second DNS server, this time replacing `OldIP2` with `NewIP2`. Then repeat Step 2 and Step 3. 

### Test the updated DNS server settings for Linux WorkSpaces
<a name="test-updated-dns-settings-linux"></a>

1. Shut down the `OldIP1` DNS server.

1. Log in to a Linux WorkSpace.

1. On your Linux WorkSpace, open a Terminal window.

1. The DNS server IP addresses returned in the DHCP response are written to the local `/etc/resolv.conf` file on the WorkSpace. Run the following command to view the contents of the `/etc/resolv.conf `file.

   ```
   cat /etc/resolv.conf
   ```

   You should see the following output. (If this is the second time you're performing this procedure, you should see `NewIP2` in place of `OldIP2`.)

   ```
   ; This file is generated by Amazon WorkSpaces
   ; Modifying it can make your WorkSpace inaccessible until reboot
   options timeout:2 attempts:5
   ; generated by /usr/sbin/dhclient-script
   search region.compute.internal
   nameserver NewIP1
   nameserver OldIP2
   nameserver WorkSpaceIP
   ```
**Note**  
If you make manual modifications to the `/etc/resolv.conf` file, those changes are lost when the WorkSpace is restarted.

1. If the output is not what you were expecting or if you receive any errors, repeat [Step 1](#update-registry-dns).

1. The actual DNS server IP addresses are stored in the `/etc/dhcp/dhclient.conf` file. To see the contents of this file, run the following command.

   ```
   sudo cat /etc/dhcp/dhclient.conf
   ```

   You should see the following output. (If this is the second time you're performing this procedure, you should see `NewIP2` in place of `OldIP2`.)

   ```
   # This file is generated by Amazon WorkSpaces
   # Modifying it can make your WorkSpace inaccessible until rebuild
   prepend domain-name-servers NewIP1, OldIP2; # skylight
   ```

1. Wait for an hour and confirm that no user issues have been reported. Verify that `NewIP1` is getting DNS queries and responding with answers.

1. After you've verified that the first DNS server is working properly, repeat [Step 1](#update-registry-dns) to update the second DNS server, this time replacing `OldIP2` with `NewIP2`. Then repeat Step 2 and Step 3. 

# Delete a directory for WorkSpaces Personal
<a name="delete-workspaces-directory"></a>

**Note**  
Simple AD and AD Connector are made available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your Simple AD or AD Connector directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).  
If you delete your Simple AD or AD Connector directory, you can always create a new one when you want to start using WorkSpaces again.

**What happens when you delete a directory:** When you delete a directory, the following occurs:
+ When a Simple AD or AWS Directory Service for Microsoft Active Directory directory is deleted, all of the directory data and snapshots are deleted and cannot be recovered. After the directory is deleted, any Amazon EC2 instances that are joined to the directory remain intact. You cannot, however, use your directory credentials to log in to these instances. You need to log in to these instances with an AWS account that is local to the instance.
+ When an AD Connector directory is deleted, your on-premises directory remains intact. Any Amazon EC2 instances that are joined to the directory also remain intact and remain joined to your on-premises directory. You can still use your directory credentials to log in to these instances.

## Delete an Entra ID or Custom WorkSpaces directory
<a name="delete-entra-custom"></a>

Entra ID WorkSpaces directory allows you to create Entra ID-joined Windows 10 or 11 BYOL WorkSpaces. For more information, see [Create a dedicated Microsoft Entra ID directory with WorkSpaces Personal](launch-entra-id.md).

Custom WorkSpaces directory allows you to create WorkSpaces that are not Active Directory domain-joined, but use your own device management software and IAM Identity Center. For more information, see [Create a dedicated Custom directory with WorkSpaces Personal](launch-custom.md).

**To delete an Entra ID or Custom WorkSpaces directory**

1. Delete all the WorkSpaces in the directory. For more information, see [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md).

1. In the navigation pane, choose **Directories**.

1. Select the directory.

1. Choose **Actions**, **Delete**.

1. When prompted for confirmation, enter **delete**.

## Delete an AWS Directory Service directory
<a name="delete-aws-directory"></a>

You can delete the AWS Directory Service directory for your WorkSpaces if it is no longer in use by other WorkSpaces or other applications, such as WorkDocs, Amazon WorkMail, or Amazon Chime. Note that you must deregister a directory before you can delete it. 

**To deregister a directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select the directory.

1. Choose **Actions**, **Deregister**.

1. When prompted for confirmation, choose **Deregister**. After deregistration is complete, the value of **Registered** is `No`.

**To delete a directory**

1. Delete all WorkSpaces in the directory. For more information, see [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md).

1. Find and remove all of the applications and services that are registered to the directory. For more information, see [Delete Your Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_delete.html) in the *AWS Directory Service Administration Guide*.

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select the directory and choose **Actions**, **Deregister**.

1. When prompted for confirmation, choose **Deregister**.

1. Select the directory again and choose **Actions**, **Delete**.

1. When prompted for confirmation, choose **Delete**.
**Note**  
Removing application assignments can sometimes take more time than expected. If you receive the following error message, verify that you've removed all application assignments, and then wait 30 to 60 minutes before trying again to delete the directory:  

   ```
   An Error Has Occurred
   Cannot delete the directory because it still has authorized applications. 
   Additional directory details can be viewed at the Directory Service console.
   ```

1. (Optional) After you delete all resources in the virtual private cloud (VPC) for your directory, you can delete the VPC and release the Elastic IP address used for the NAT gateway. For more information, see [ Deleting your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#VPC_Deleting) and [ Working with Elastic IP addresses](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-eips.html#WorkWithEIPs) in the *Amazon VPC User Guide*.

1. (Optional) To delete any custom bundles and images that you are finished with, see [Delete a custom bundle or image in WorkSpaces Personal](delete_bundle.md).

# Set up Active Directory Administration Tools for WorkSpaces Personal
<a name="directory_administration"></a>

You'll perform most administrative tasks for your WorkSpaces directory using directory management tools, such as the Active Directory Administration Tools. However, you'll use the WorkSpaces console to perform some directory-related tasks. For more information, see [Manage directories for WorkSpaces Personal](manage-workspaces-directory.md).

If you create a directory with AWS Managed Microsoft AD or Simple AD that includes five or more WorkSpaces, we recommend that you centralize administration on an Amazon EC2 instance. Although you can install the directory management tools on a WorkSpace, using an Amazon EC2 instance is a more robust solution.

**To set up the Active Directory Administration Tools**

1. Launch an Amazon EC2 Windows instance and join it to your WorkSpaces directory by using one of the following options:
   + If you don't already have an existing Amazon EC2 Windows instance, you can join the instance to your directory domain when you launch the instance. For more information, see [Seamlessly join a Windows EC2 instance](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/launching_instance.html) in the *AWS Directory Service Administration Guide*.
   + If you already have an existing Amazon EC2 Windows instance, you can join it to your directory manually. For more information, see [Manually Add a Windows Instance](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/join_windows_instance.html) in the *AWS Directory Service Administration Guide*.

1. Install the Active Directory Administration Tools on the Amazon EC2 Windows instance. For more information, see [Installing the Active Directory Administration Tools](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/install_ad_tools.html) in the *AWS Directory Service Administration Guide*.
**Note**  
When you're installing the Active Directory Administration Tools, make sure to also select **Group Policy Management** to install the Group Policy Management Editor (**gpmc.msc**) tool.

   When the feature installation is finished, the Active Directory tools are available on the Windows **Start** menu under **Windows Administrative Tools**.

1. Run the tools as a directory administrator as follows:

   1. On the Windows **Start** menu, open **Windows Administrative Tools**.

   1. Hold down the Shift key, right-click the shortcut for the tool you want to use, and choose **Run as different user**.

   1. Enter the sign-in credentials for the administrator. With Simple AD, the username is **Administrator** and with AWS Managed Microsoft AD, the administrator is **Admin**.

You can now perform directory administration tasks using the Active Directory tools that you are familiar with. For example, you can use the Active Directory Users and Computers Tool to add users, remove users, promote a user to directory administrator, or reset a user password. Note that you must be logged into your Windows instance as a user that has permissions to manage users in the directory.

**To promote a user to a directory administrator**
**Note**  
This procedure applies only to directories created with Simple AD, not AWS Managed AD. For directories created with AWS Managed AD, see [ Manage Users and Groups in AWS Managed Microsoft AD](https://docs.aws.amazon.com//directoryservice/latest/admin-guide/ms_ad_manage_users_groups.html) in the *AWS Directory Service Administration Guide*.

1. Open the Active Directory Users and Computers tool.

1. Navigate to the **Users** folder under your domain and select the user to promote.

1. Choose **Action**, **Properties**.

1. In the ***username* Properties** dialog box, choose **Member Of**.

1. Add the user to the following groups and choose **OK**.
   + **Administrators**
   + **Domain Admins**
   + **Enterprise Admins**
   + **Group Policy Creator Owners**
   + **Schema Admins**

**To add or remove users**  
You can create new users from the Amazon WorkSpaces console only during the process of launching a WorkSpace, and you cannot delete users through the Amazon WorkSpaces console. Most user management tasks, including managing user groups, must be performed through your directory. 

**Important**  
Before you can remove a user, you must delete the WorkSpace assigned to that user. For more information, see [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md).

The process you use for managing users and groups depends on which type of directory you're using.
+ If you're using AWS Managed Microsoft AD, see [ Manage Users and Groups in AWS Managed Microsoft AD](https://docs.aws.amazon.com//directoryservice/latest/admin-guide/ms_ad_manage_users_groups.html) in the *AWS Directory Service Administration Guide*.
+ If you're using Simple AD, see [ Manage Users and Groups in Simple AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/simple_ad_manage_users_groups.html) in the *AWS Directory Service Administration Guide*. 
+ If you use Microsoft Active Directory through AD Connector or a trust relationship, you can manage users and groups using the [ Active Directory module](https://docs.microsoft.com/powershell/module/activedirectory/).

**To reset a user password**  
When you reset the password for an existing user, do not set **User must change password at next logon**. Otherwise, the users cannot connect to their WorkSpaces. Instead, assign a secure temporary password to each user and then ask the users to manually change their passwords from within the WorkSpace the next time they log on.

**Note**  
If you're using AD Connector or if your users are in the AWS GovCloud (US-West) Region, your users won't be able to reset their own passwords. (The **Forgot password?** option on the WorkSpaces client application login screen won't be available .)

# Administer users in WorkSpaces Personal
<a name="administer-workspace-users"></a>

Each WorkSpace is assigned to a single user and cannot be shared by multiple users. By default, only one WorkSpace per user per directory is allowed.

**Topics**
+ [Manage users in WorkSpaces Personal](manage-workspaces-users.md)
+ [Create multiple WorkSpaces for a user in WorkSpaces Personal](create-multiple-workspaces-for-user.md)
+ [Customize how users log in to their WorkSpaces in WorkSpaces Personal](customize-workspaces-user-login.md)
+ [Enable self-service WorkSpaces management capabilities for your users in WorkSpaces Personal](enable-user-self-service-workspace-management.md)
+ [Enable Amazon Connect audio optimization for your users in WorkSpaces Personal](enable-amazon-connect-audio-optimization.md)
+ [Enable diagnostic log uploads in WorkSpaces Personal](enable-diagnostic-log-uploads.md)

# Manage users in WorkSpaces Personal
<a name="manage-workspaces-users"></a>

As an administrator for WorkSpaces, you can perform the following tasks to manage WorkSpaces users.

## Edit user information
<a name="edit-user"></a>

You can use the WorkSpaces console to edit the user information for a WorkSpace.

**Note**  
This feature is available only if you use AWS Managed Microsoft AD or Simple AD. If you use Microsoft Active Directory through AD Connector or a trust relationship, you can manage users and groups using the [ Active Directory module](https://docs.microsoft.com/powershell/module/activedirectory/). If you use Microsoft Entra ID or Custom WorkSpaces directory, you can manage users and groups with Microsoft Entra ID or your Identity Providers.

**To edit user information**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select a user and choose **Actions**, **Edit users**.

1. Update **First name**, **Last name**, and **Email** as needed.

1. Choose **Update**.

## Add or delete users
<a name="add-delete-user"></a>

You can create users from the Amazon WorkSpaces console only during the process of launching a WorkSpace, and you cannot delete users through the Amazon WorkSpaces console. Most user management tasks, including managing user groups, must be performed through your directory.

**To add or delete users and groups**  
To add, delete, or otherwise manage users and groups, you must do this through your directory. You'll perform most administrative tasks for your WorkSpaces directory using directory management tools, such as the Active Directory Administration Tools. For more information, see [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md).

**Important**  
Before you can remove a user, you must delete the WorkSpace assigned to that user. For more information, see [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md).

The process you use for managing users and groups depends on which type of directory you're using.
+ If you're using AWS Managed Microsoft AD, see [ Manage Users and Groups in AWS Managed Microsoft AD](https://docs.aws.amazon.com//directoryservice/latest/admin-guide/ms_ad_manage_users_groups.html) in the *AWS Directory Service Administration Guide*.
+ If you're using Simple AD, see [ Manage Users and Groups in Simple AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/simple_ad_manage_users_groups.html) in the *AWS Directory Service Administration Guide*. 
+ If you use Microsoft Active Directory through AD Connector or a trust relationship, you can manage users and groups by using the [ Active Directory module](https://docs.microsoft.com/powershell/module/activedirectory/).

## Send an invitation email
<a name="send-invitation"></a>

You can send an invitation email to a user manually if needed.

**Note**  
If you're using AD Connector or a trusted domain, invitation emails aren't automatically sent to your users, so you must send them manually. Invitation emails also aren't sent automatically if the user already exists in Active Directory.

**To resend an invitation email**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. On the **WorkSpaces** page, use the search box to search for the user you want to send an invitation to, and then select the corresponding WorkSpace from the search results. You can select only one WorkSpace at a time.

1. Choose **Actions**, **Invite users**.

1. On the **Invite users to the WorkSpace** page, choose **Send invite**.

# Create multiple WorkSpaces for a user in WorkSpaces Personal
<a name="create-multiple-workspaces-for-user"></a>

By default, you can create only one WorkSpace per user per directory. However, if needed, you can create more than one WorkSpace for a user, depending on your directory setup. 
+ If you have only one directory for your WorkSpaces, create multiple usernames for the user. For example, a user named Mary Major can have mmajor1, mmajor2, and so on as usernames. Each username is associated with a different WorkSpace in the same directory, but the WorkSpaces have the same registration code, as long as the WorkSpaces are all created in the same directory in the same AWS Region.
+ If you have multiple directories for your WorkSpaces, create the WorkSpaces for the user in separate directories. You can use the same username in the directories, or you can use different usernames in the directories. The WorkSpaces will have different registration codes.

**Tip**  
So that you can easily locate all the WorkSpaces that you've created for a user, use the same base username for each WorkSpace.  
For example, if you have a user named Mary Major with the Active Directory username mmajor, create WorkSpaces for her with usernames such as mmajor, mmajor1, mmajor2, mmajor3, or other variants, such as mmajor\$1windows or mmajor\$1linux. As long as all the WorkSpaces have the same starting base username (mmajor), you can sort on the username in your WorkSpaces console to group all of the WorkSpaces for that user together.

**Important**  
A user can have both a PCoIP and a DCV WorkSpace as long as the two WorkSpaces are located in separate directories. The same user cannot have a PCoIP and a DCV WorkSpace in the same directory. 
If you are setting up multiple WorkSpaces for use with cross-Region redirection, you must set up the WorkSpaces in different directories in different AWS Regions, and you must use the same usernames in each directory. For more information about cross-Region redirection, see [Cross-Region redirection for WorkSpaces Personal](cross-region-redirection.md). 

To switch between the WorkSpaces, the user logs in with the username and registration code associated with a particular Workspace. If the user is using a 3.0\$1 version of the WorkSpaces client applications for Windows, macOS, or Linux, the user can assign different names to the WorkSpaces by going to **Settings**, **Manage Login Information** in the client application.

# Customize how users log in to their WorkSpaces in WorkSpaces Personal
<a name="customize-workspaces-user-login"></a>

Customize your users' access to WorkSpaces by using uniform resource identifiers (URIs) to provide a simplified login experience that integrates with existing workflows in your organization. For example, you can automatically generate login URIs that register your users by using their WorkSpaces registration code. As a result: 
+ Users can bypass the manual registration process.
+ Their usernames are automatically entered on their WorkSpaces client login page.
+ If multi-factor authentication (MFA) is used in your organization, their usernames and MFA codes are automatically entered on their client login page.

URI access works with both Region-based registration codes (for example, `WSpdx+ABC12D`) and fully qualified domain name (FQDN) based registration codes (for example, `desktop.example.com`). For more information about creating and using FQDN-based registration codes, see [Cross-Region redirection for WorkSpaces Personal](cross-region-redirection.md).

You can configure URI access to WorkSpaces for client applications on the following supported devices: 
+ Windows computers
+ macOS computers
+ Ubuntu Linux 18.04, 20.04, and 22.04 computers
+ iPads
+ Android devices

To use URIs to access their WorkSpaces, users must first install the client application for their device by opening [https://clients.amazonworkspaces.com/](https://clients.amazonworkspaces.com/) and following the directions.

URI access is supported on the Firefox and Chrome browsers on Windows and macOS computers, on the Firefox browser on Ubuntu Linux 18.04, 20.04, and 22.04 computers, and on the Internet Explorer and Microsoft Edge browsers on Windows computers. For more information about WorkSpaces clients, see [WorkSpaces Clients](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-clients.html) in the *Amazon WorkSpaces User Guide*.

**Note**  
On Android devices, URI access works only with the Firefox browser, not with the Google Chrome browser.

To configure URI access to WorkSpaces, use any of the URI formats described in the following table.

**Note**  
If the data component of your URI includes any of the following reserved characters, we recommend that you use percent-encoding in the data component to avoid ambiguity:   
`@ : / ? & =`  
For example, if you have usernames that include any of these characters, you should percent-encode those usernames in your URI. For more information, see [Uniform Resource Identifier (URI): Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986.txt).


| Supported syntax | Description | 
| --- | --- | 
| workspaces:// | Opens the WorkSpaces client application. (Note: Using workspaces:// by itself is not currently supported in the Linux client application.) | 
| workspaces://@registrationcode | Registers a user by using their WorkSpaces registration code. Also displays the client login page. | 
| workspaces://username@registrationcode | Registers a user by using their WorkSpaces registration code. Also automatically enters the username in the username field on the client login page. | 
| workspaces://username@registrationcode?MFACode=mfa | Registers a user by using their WorkSpaces registration code. Also automatically enters the username in the username field and the multi-factor authentication (MFA) code in the MFA code field on the client login page. | 
| workspaces://@registrationcode?MFACode=mfa | Registers a user by using their WorkSpaces registration code. Also automatically enters the multi-factor authentication (MFA) code in the MFA code field on the client login page. | 

**Note**  
If users open a URI link when they are already connected to a WorkSpace from a Windows client, a new WorkSpaces session opens and their original WorkSpaces session remains open. If users open a URI link when they are connected to a WorkSpace from a macOS, iPad, or Android client, no new session opens; only their original WorkSpaces session remains open.

# Enable self-service WorkSpaces management capabilities for your users in WorkSpaces Personal
<a name="enable-user-self-service-workspace-management"></a>

In WorkSpaces, you can enable self-service WorkSpace management capabilities for your users to provide them with more control over their experience. It can also reduce your IT support staff workload for WorkSpaces. When you enable self-service capabilities, users can perform one or more of the following tasks directly from their WorkSpaces client:
+ Cache their credentials on their client. This lets them reconnect to their WorkSpace without re-entering their credentials.
+ Restart (reboot) their WorkSpace.
+ Increase the size of the root and user volumes on their WorkSpace. 
+ Change the compute type (bundle) for their WorkSpace.
+ Switch the running mode of their WorkSpace.
+ Rebuild their WorkSpace.

**Supported clients**
+ Android, running on Android or Android-compatible Chrome OS systems
+ Linux
+ macOS
+ Windows

**To enable self-service management capabilities for your users**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose the directory you want to enable self-service management capabilities.

1. Scroll down to Self-service permissions and choose **Edit**. Enable or disable the following options as required to determine the WorkSpace management tasks that users can perform from their client:
   + **Remember me** — Users can choose whether to cache their credentials on their client by selecting the **Remember Me** or **Keep me logged in** check box on the login screen. The credentials are cached in RAM only. When users choose to cache their credentials, they can reconnect to their WorkSpaces without re-entering their credentials. To control how long users can cache their credentials, see [Set the maximum lifetime for a Kerberos ticket](group_policy.md#gp_kerberos_ticket).
   + **Restart WorkSpace from client** — Users can restart (reboot) their WorkSpace. Restarting disconnects the user from their WorkSpace, shuts it down, and reboots it. The user data, operating system, and system settings are not affected.
   + **Increase volume size** — Users can expand the root and user volumes on their WorkSpace to a specified size without contacting IT support. Users can increase the size of the root volume (for Windows, the C: drive; for Linux, /) up to 175 GB, and the size of the user volume (for Windows, the D: drive; for Linux, /home) up to 100 GB. WorkSpace root and user volumes come in set groups that can't be changed. The available groups are [Root(GB), User(GB)]: [80, 10], [80, 50], [80, 100], [175 to 2000, 100 to 2000]. For more information, see [Modify a WorkSpace in WorkSpaces Personal](modify-workspaces.md).

     For a newly created WorkSpace, users must wait 6 hours before they can increase the size of these drives. After that, they can do so only once in a 6-hour period. While a volume size increase is in progress, users can perform most tasks on their WorkSpace. The tasks that they can't perform are: changing their WorkSpace compute type, switching their WorkSpace running mode, restarting their WorkSpace, or rebuilding their WorkSpace. When the process is finished, the WorkSpace must be rebooted for the changes to take effect. This process might take up to an hour.
**Note**  
If users increase the volume size on their WorkSpace, this increases the billing rate for their WorkSpace.
   + **Change compute type** — Users can switch their WorkSpace between compute types (bundles). For a newly created WorkSpace, users must wait 6 hours before they can switch to a different bundle. After that, they can switch to a larger bundle only once in a 6-hour period, or to a smaller bundle once in a 30-day period. When a WorkSpace compute type change is in progress, users are disconnected from their WorkSpace, and they can't use or change the WorkSpace. The WorkSpace is automatically rebooted during the compute type change process. This process might take up to an hour.
**Note**  
If users change their WorkSpace compute type, this changes the billing rate for their WorkSpace.
   + **Switch running mode** — Users can switch their WorkSpace between the **AlwaysOn** and **AutoStop** running modes. For more information, see [Manage the running mode in WorkSpaces Personal](running-mode.md).
**Note**  
If users switch the running mode of their WorkSpace, this changes the billing rate for their WorkSpace.
   + **Rebuild WorkSpace from client** — Users can rebuild the operating system of a WorkSpace to its original state. When a WorkSpace is rebuilt, the user volume (D: drive) is recreated from the latest backup. Because backups are completed every 12 hours, users' data might be up to 12 hours old. For a newly created WorkSpace, users must wait 12 hours before they can rebuild their WorkSpace. When a WorkSpace rebuild is in progress, users are disconnected from their WorkSpace, and they can't use or make changes to their WorkSpace. This process might take up to an hour. 
   + **Diagnostic log uploads** — Users can upload WorkSpaces client log files directly to WorkSpaces to troubleshoot issues without interrupting use of the WorkSpaces client. If you enable diagnostic log uploads for your users, or let your users do so themselves, the log files are sent to WorkSpaces automatically. You can enable diagnostic log uploads before or during a WorkSpaces streaming session.

1. Choose **Save**.

# Enable Amazon Connect audio optimization for your users in WorkSpaces Personal
<a name="enable-amazon-connect-audio-optimization"></a>

In the WorkSpaces management console, you can enable Amazon Connect Contact Control Panel (CCP) audio optimization for your WorkSpaces fleets to enhance security and to enable native-quality audio. After enabling CCP audio optimization, the CCP audio will be processed by the client endpoints, while WorkSpaces users can interact with the CCP from within their WorkSpaces.

Amazon Connect Contact Control Panel (CCP) audio optimization works with:
+ The WorkSpaces Windows client.
+ Amazon Linux and Windows WorkSpaces.
+ WorkSpaces using PCoIP or DCV.

## Requirements
<a name="amazon-connect-audio-optimization-requirements"></a>
+ You must be set up with Amazon Connect.
+ You must build a custom CCP with the Amazon Connect Stream API by creating a CCP with no media for call signaling. This way, the media is handled on the local desktop using standard CCP, and the signaling and call controls are handled on the remote connection with the CCP with no media. For more information about the Amazon Connect streams API, see the GitHub repository at [https://github.com/aws/amazon-connect-streams](https://github.com/aws/amazon-connect-streams). The custom CCP that you build is the CCP your Amazon Connect agents will use within their WorkSpaces.
+ You must have a web browser installed onto WorkSpaces client endpoints that's supported by Amazon Connect. For the list of supported browsers, see [ Browsers supported by Amazon Connect](https://docs.aws.amazon.com/connect/latest/adminguide/browsers.html).
**Note**  
If your users use browsers that are not supported, they will be asked to download a supported browser when they attempt to log in to the CCP.

## Enable Amazon Connect audio optimization
<a name="enable-audio-optimization"></a>

To enable Amazon Connect audio optimization for your users:

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select your directory, and choose **Actions**, **Update Details**.

1. Expand **Amazon Connect Audio Optimization**.
**Note**  
Before configuring with Amazon Connect, choose **Update** to save any unsaved changes made previously in the management console.

1. Choose **Configure Amazon Connect**.

1. Enter an Amazon Connect Contact Control Panel (CCP) name.
**Note**  
The name that you give your CCP will be used in the user add-in menu. Choose a name that will be meaningful to your users.

1. Enter the Amazon Connect Contact Control Panel URL that's generated by Amazon Connect. See [ Provide access to the Contact Control Panel](https://docs.aws.amazon.com/connect/latest/adminguide/amazon-connect-contact-control-panel.html) for more information on getting the URL.

1. Choose **Create Amazon Connect**.

## Update directory's Amazon Connect audio optimization details
<a name="update-audio-optimization"></a>

To update a directory's Amazon Connect audio optimization details:

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select your directory, and choose **Actions**, **Update Details**.

1. Expand **Amazon Connect Audio Optimization**.
**Note**  
Before configuring with Amazon Connect, choose **Update** to save any unsaved changes made previously in the management console.

1. Choose **Configure Amazon Connect**. 

1. Choose **Edit**.

1. Select your directory, and choose **Actions**, **Update Details**.

1. Update the Amazon Connect Contact Control Panel name and URL.

1. Choose **Save**.

## Delete directory's Amazon Connect audio optimization
<a name="delete-audio-optimization"></a>

To delete a directory’s Amazon Connect audio optimization:

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select your directory, and choose **Actions**, **Update Details**.

1. Expand **Amazon Connect Audio Optimization**.
**Note**  
Before configuring with Amazon Connect, choose **Update** to save any unsaved changes made previously in the management console.

1. Choose **Configure Amazon Connect**. 

1. Choose **Delete Amazon Connect**.

See the [ Agent training guide](https://docs.aws.amazon.com/connect/latest/adminguide/agent-user-guide.html) for more information. 

# Enable diagnostic log uploads in WorkSpaces Personal
<a name="enable-diagnostic-log-uploads"></a>

To troubleshoot WorkSpaces client issues, enable automatic diagnostic log uploads. This is currently supported for Windows, macOS, Linux, and Web Access clients.

**Note**  
The WorkSpaces client diagnostic log uploads feature is currently unavailable in the AWS GovCloud (US-West) Region.

## Diagnostic log uploads
<a name="diagnostic-log-uploads"></a>

With Diagnostic log uploads, you can upload WorkSpaces client log files directly to WorkSpaces to troubleshoot issues without interrupting use of the WorkSpaces client. If you enable diagnostic log uploads for your users, or let your users do so themselves, the log files are sent to WorkSpaces automatically. You can enable diagnostic log uploads before or during a WorkSpaces streaming session.

To automatically upload diagnostic logs from managed devices, install a WorkSpaces client that supports diagnostic uploads. Log uploading is enabled by default. You can modify the settings in either of the following ways:

### Option 1: Using the AWS console
<a name="diagnostic-log-console"></a>

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Choose the directory name that you want to enable diagnostic logging for.

1. Scroll down to **Self-service permission**.

1. Choose **View details**

1. Choose **Edit**.

1. Choose **Diagnostic log uploads**.

1. Choose **Save**.

### Option 2: Using an API call
<a name="diagnostic-log-api"></a>

You can edit the directory settings to enable or disable the WorkSpaces Windows, macOS, and Linux client to upload diagnostic logs automatically using an API call. If enabled, when a client issue occurs, the logs are sent to WorkSpaces without user interaction. For more information, see the [ WorkSpaces API reference](https://docs.aws.amazon.com/workspaces/latest/api/API_ClientProperties.html).

You can also let your users choose whether to enable automatic diagnostic log uploads after client installation. For more information, see [WorkSpaces Windows client application ](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-windows-client.html), [WorkSpaces macOS client application](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-osx-client.html), and [WorkSpaces Linux client application](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-linux-client.html).

**Note**  
Diagnostic logs don't contain sensitive information. You can disable automatic diagnostic log uploads for your users at the directory level, or allow your users to disable these features themselves.
To access the diagnostic log uploads feature, you need to install the following versions of the WorkSpaces clients:  
5.4.0 or later of the Windows client
5.8.0 or later of the macOS client
2023.1 of the Ubuntu 22.04 client
2023.1 of the Ubuntu 20.04 client
You can also access the diagnostic log upload feature with the Web Access client

# Administer WorkSpaces Personal
<a name="administer-workspaces"></a>

You can administer your WorkSpaces using the WorkSpaces console.

To perform directory administration tasks, see [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md).

**Note**  
Ensure you update networking dependency drivers like ENA, NVMe, and PV drivers on your WorkSpaces. You should do this at least once every 6 months. For more information, see [ Install or upgrade Elastic Network Adapter (ENA) driver ](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/enhanced-networking-ena.html#ena-adapter-driver-install-upgrade-win), [AWS NVMe drivers for Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/aws-nvme-drivers.html), and [Upgrade PV drivers on Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Upgrading_PV_drivers.html).
Ensure you update the EC2Config, EC2Launch, and EC2Launch V2 agents to the latest versions periodically. You should do this at least once every 6 months. For more information, see [Update EC2Config and EC2Launch](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/migrating-latest-types.html#upgdate-ec2config-ec2launch).

**Topics**
+ [Manage your Windows WorkSpaces in WorkSpaces Personal](group_policy.md)
+ [Manage your Amazon Linux 2 WorkSpaces in WorkSpaces Personal](manage_linux_workspace.md)
+ [Manage your Ubuntu WorkSpaces in WorkSpaces Personal](manage_ubuntu_workspace.md)
+ [Manage your Rocky Linux WorkSpaces](manage_rockylinux_workspace.md)
+ [Manage your Red Hat Enterprise Linux WorkSpaces](manage_rhel_workspace.md)
+ [Optimize WorkSpaces for real-time communication in WorkSpaces Personal](communication-optimization.md)
+ [Manage the running mode in WorkSpaces Personal](running-mode.md)
+ [Manage applications in WorkSpaces Personal](manage-applications.md)
+ [Modify a WorkSpace in WorkSpaces Personal](modify-workspaces.md)
+ [Customize branding in WorkSpaces Personal](customize-branding.md)
+ [Tag resources in WorkSpaces Personal](tag-workspaces-resources.md)
+ [Maintenance in WorkSpaces Personal](workspace-maintenance.md)
+ [Encrypted WorkSpaces in WorkSpaces Personal](encrypt-workspaces.md)
+ [Reboot a WorkSpace in WorkSpaces Personal](reboot-workspaces.md)
+ [Rebuild a WorkSpace in WorkSpaces Personal](rebuild-workspace.md)
+ [Restore a WorkSpace in WorkSpaces Personal](restore-workspace.md)
+ [Microsoft 365 Bring Your Own License (BYOL) in WorkSpaces Personal](byol-microsoft365-licenses.md)
+ [Upgrade Windows BYOL WorkSpaces in WorkSpaces Personal](upgrade-windows-10-byol-workspaces.md)
+ [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md)
+ [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md)

# Manage your Windows WorkSpaces in WorkSpaces Personal
<a name="group_policy"></a>

You can use Group Policy Objects (GPOs) to apply settings to manage Windows WorkSpaces or users that are part of your Windows WorkSpaces directory.

**Note**  
If you use Microsoft Entra ID or Custom WorkSpaces directory, you can manage users and groups with Microsoft Entra ID or your Identity Providers. For more inforamtion, see [Create a dedicated Microsoft Entra ID directory with WorkSpaces Personal](launch-entra-id.md).
Linux instances do not adhere to Group Policy. For information about managing Amazon Linux WorkSpaces, see [Manage your Amazon Linux 2 WorkSpaces in WorkSpaces Personal](manage_linux_workspace.md). 

Amazon recommends that you create an organizational unit for your WorkSpaces Computer Objects and an organizational unit for your WorkSpaces User Objects.

To use the Group Policy settings that are specific to Amazon WorkSpaces, you must install the Group Policy administrative template for the protocol or protocols that you are using, either PCoIP or DCV.

**Warning**  
Group Policy settings can affect the experience of your WorkSpace users as follows:  
**Implementing an interactive logon message to display a logon banner prevents users from being able to access their WorkSpaces.** The interactive logon message Group Policy setting is not currently supported by PCoIP WorkSpaces. The logon message is supported on DCV WorkSpaces, and users have to login again after accepting the logon banner. Logon messages are not supported when Certificate-Based Logon is enabled.
**Disabling removable storage through Group Policy settings causes a login failure** that results in users being logged in to temporary user profiles with no access to drive D.
**Removing users from the Remote Desktop Users local group through Group Policy settings prevents those users from being able to authenticate** through the WorkSpaces client applications. For more information about this Group Policy setting, see [ Allow log on through Remote Desktop Services](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/allow-log-on-through-remote-desktop-services) in the Microsoft documentation.
**If you remove the built-in Users group from the **Allow log on locally** security policy, your PCoIP WorkSpaces users won't be able to connect to their WorkSpaces through the WorkSpaces client applications.** Your PCoIP WorkSpaces also won't receive updates to the PCoIP agent software. PCoIP agent updates might contain security and other fixes, or they might enable new features for your WorkSpaces. For more information about working with this security policy, see [ Allow log on locally](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/allow-log-on-locally) in the Microsoft documentation.
Group Policy settings can be used to restrict drive access. **If you configure Group Policy settings to restrict access to drive C or to drive D, users can't access their WorkSpaces.** To prevent this issue from occurring, make sure that your users can access drive C and drive D. 
**The WorkSpaces audio-in feature requires local logon access inside the WorkSpace.** The audio-in feature is enabled by default for Windows WorkSpaces. However, if you have a Group Policy setting that restricts users' local logon in their WorkSpaces, audio-in won't work on your WorkSpaces. If you remove that Group Policy setting, the audio-in feature is enabled after the next reboot of the WorkSpace. For more information about this Group Policy setting, see [ Allow log on locally](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/allow-log-on-locally) in the Microsoft documentation.  
For more information about enabling or disabling audio-in redirection, see [Configure audio-in redirection for PCoIP](#gp_audio) or [Configure audio-in redirection for DCV](#gp_audio_in_wsp).
Using Group Policy to set the Windows power plan to **Balanced** or **Power saver** might cause your WorkSpaces to sleep when they're left idle. We strongly recommend using Group Policy to set the Windows power plan to **High performance**. For more information, see [My Windows WorkSpace goes to sleep when it's left idle](amazon-workspaces-troubleshooting.md#windows_workspace_sleeps_when_idle). 
Some Group Policy settings force users to log off when they are disconnected from a session. Any applications that users have open on their WorkSpaces are closed.
"Set time limit for active but idle Remote Desktop Services sessions" is currently not supported on DCV WorkSpaces. Avoid using it during DCV sessions as it causes a disconnect even when there is activity and the session is not idle.

For information about using the Active Directory administration tools to work with GPOs, see [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md).

**Contents**
+ [Install the Group Policy administrative template files for DCV](#gp_install_template_wsp)
+ [Manage Group Policy settings for DCV](#gp_configurations_dcv)
+ [Install the Group Policy administrative template for PCoIP](#gp_install_template)
+ [Manage Group Policy settings for PCoIP](#gp_configurations_pcoip)
+ [Set the maximum lifetime for a Kerberos ticket](#gp_kerberos_ticket)
+ [Configure device proxy server settings for internet access](#gp_device_proxy)
  + [Proxying desktop traffic](#w2aac11c31c11c27c15)
  + [Recommendation on the use of proxy servers](#w2aac11c31c11c27c17)
+ [Enable Zoom Meeting Media Plugin support](#zoom-integration)
  + [Enable Zoom Meeting Media Plugin for DCV](#zoom-wsp)
    + [Prerequisites](#zoom-integ-prerequisites-wsp)
    + [Before you begin](#zoom-begin-wsp)
    + [Installing the Zoom components](#installing-zoom-wsp)
  + [Enable Zoom Meeting Media Plugin for PCoIP](#zoom-pcoip)
    + [Prerequisites](#zoom-integ-prerequisites-pcoip)
    + [Create the registry key on a Windows WorkSpaces host](#zoom-integ-create-registry-key)
    + [Troubleshooting](#zoom-integ-troubleshoot)

## Install the Group Policy administrative template files for DCV
<a name="gp_install_template_wsp"></a>

To use the Group Policy settings that are specific to WorkSpaces when using DCV, you must add the Group Policy administrative template `wsp.admx` and `wsp.adml` files for DCV to the Central Store of the domain controller for your WorkSpaces directory. For more information about `.admx` and `.adml` files, see [ How to create and manage the Central Store for Group Policy Administrative Templates in Windows](https://support.microsoft.com/help/3087759/how-to-create-and-manage-the-central-store-for-group-policy-administra).

The following procedure describes how to create the Central Store and add the administrative template files to it. Perform the following procedure on a directory administration WorkSpace or Amazon EC2 instance that is joined to your WorkSpaces directory.

**To install the Group Policy administrative template files for DCV**

1. From a running Windows WorkSpace, make a copy of the `wsp.admx` and `wsp.adml` files in the `C:\Program Files\Amazon\WSP` directory.

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open Windows File Explorer, and in the address bar, enter your organization's fully qualified domain name (FQDN), such as `\\example.com`.

1. Open the `sysvol` folder.

1. Open the folder with the `FQDN` name.

1. Open the `Policies` folder. You should now be in `\\FQDN\sysvol\FQDN\Policies`.

1. If it doesn't already exist, create a folder named `PolicyDefinitions`.

1. Open the `PolicyDefinitions` folder.

1. Copy the `wsp.admx` file into the `\\FQDN\sysvol\FQDN\Policies\PolicyDefinitions` folder.

1. Create a folder named `en-US` in the `PolicyDefinitions` folder.

1. Open the `en-US` folder.

1. Copy the `wsp.adml` file into the `\\FQDN\sysvol\FQDN\Policies\PolicyDefinitions\en-US` folder.<a name="verify-admin-template"></a>

**To verify that the administrative template files are correctly installed**

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**).

1. Expand the forest (**Forest:*FQDN***).

1. Expand **Domains**. 

1. Expand your FQDN (for example, `example.com`).

1. Expand **Group Policy Objects**.

1. Select **Default Domain Policy**, open the context (right-click) menu, and choose **Edit**.
**Note**  
If the domain backing the WorkSpaces is an AWS Managed Microsoft AD directory, you cannot use the Default Domain Policy to create your GPO. Instead, you must create and link the GPO under the domain container that has delegated privileges.  
When you create a directory with AWS Managed Microsoft AD, Directory Service creates a *yourdomainname* organizational unit (OU) under the domain root. The name of this OU is based on the NetBIOS name that you typed when you created your directory. If you didn't specify a NetBIOS name, it will default to the first part of your Directory DNS name (for example, in the case of `corp.example.com`, the NetBIOS name is `corp`).  
To create your GPO, instead of selecting **Default Domain Policy**, select the *yourdomainname* OU (or any OU under that one), open the context (right-click) menu, and choose **Create a GPO in this domain, and Link it here**.   
For more information about the *yourdomainname* OU, see [ What Gets Created](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started_what_gets_created.html) in the *AWS Directory Service Administration Guide*.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **DCV**.

1. You can now use this **DCV** Group Policy object to modify the Group Policy settings that are specific to WorkSpaces when using DCV.

## Manage Group Policy settings for DCV
<a name="gp_configurations_dcv"></a>

**To use Group Policy settings to manage your Windows WorkSpaces that use DCV**

1. Make sure that the most recent [WorkSpaces Group Policy administrative template for DCV](#gp_install_template_wsp) is installed in the Central Store of the domain controller for your WorkSpaces directory.

1. Verify the administrative template files are correctly installed. For more information, see [To verify that the administrative template files are correctly installed](#verify-admin-template).

### Configure printer support for DCV
<a name="gp_local_printers_wsp"></a>

By default, WorkSpaces enables Basic remote printing, which offers limited printing capabilities because it uses a generic printer driver on the host side to ensure compatible printing.

Advanced remote printing for Windows clients connecting to Windows WorkSpaces lets you use specific features of your printer, such as double-sided printing, but it requires installation of the matching printer drivers on the host side and the client side.

You can use Group Policy settings to configure printer support as needed.


**Basic vs. Advanced Printing**  

| Aspect | Basic Printing | Advanced Printing | 
| --- | --- | --- | 
| Driver Used | Generic XPS driver | Printer-specific driver | 
| Driver Installation | Automatic | Manual (host and client) | 
| Features | Standard printing only | Full printer features (duplex, paper tray selection, finishing, etc.) | 

**When to use Advanced Printing:** - Double-sided (duplex) printing - Specific paper tray selection - Finishing options (stapling, hole-punching) - Label printing (e.g., Zebra printers) - Color management and other advanced features of a printer.

#### Configure Printer Support
<a name="w2aac11c31c11c19b5b1c13"></a>

**To configure printer support**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure remote printing** setting.

1. In the **Configure remote printing** dialog box, do one of the following:
   + **For Basic Printing:** choose **Enabled**. To automatically use the client computer's current default printer, select **Map local default printer to the remote host. **
   + **For Advanced Printing:** Choose **Enabled**, then choose **Enable Advanced Printing**.To automatically use the client computer's current default printer, select** Map local default printer to the remote host**. Once the policy is enabled, you will need to install matching printer drivers on the host and client side.
   + To disable printing, choose **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

#### Configure Advanced Printer Redirection
<a name="w2aac11c31c11c19b5b1c17"></a>

**Prerequisites**

1. **WorkSpaces Host Agent:** Version 2.2.0.2116 or later

1. **Windows Client:** Version 5.31.0 or later

1. **Printer drivers:** Matching printer drivers must be installed on both the WorkSpace and the client device

**Note**  
Advanced printing is only supported on Windows clients connecting to Windows WorkSpaces. MacOS, Linux, and Web clients will use basic printing.

#### Driver Version Matching
<a name="w2aac11c31c11c19b5b1c23"></a>

When Advanced printing is selected, three driver validation modes are supported:


**Driver Validation Modes**  

| Mode | Behavior | Use When | 
| --- | --- | --- | 
| Name Only (Default) | Matches driver name only, ignores version | Maximum compatibility needed | 
| Partial Match | Matches Major.Minor version (e.g., 10.6.x.x) | Balancing compatibility and features | 
| Exact Match | Requires exact version match | Specialized printers (e.g., Zebra label printers) | 

**To configure validation mode**, set name only, partial match, or exact match in the printer driver validation dropdown in the GPO.

**Note**  
When driver validation fails, WorkSpaces automatically falls back to basic printing.

**Verify Configuration**

1. Connect to the WorkSpace.

1. Open **Settings** > **Devices** > **Printers & scanners**.

1. Verify your local printer appears with "Redirected" prefix.

1. Print a test document and click Printer Properties to verify advanced options are available.

#### Troubleshooting
<a name="w2aac11c31c11c19b5b1c27"></a>

**Advanced features not available**: - Verify “Enable Advanced Printing” is selected in the GPO - Check driver versions match according to your validation mode - Consider using partial validation mode instead of exact. Make sure to restart for any changes on the GPO to take effect.

**Printer not appearing**: - Verify **Configure remote printing** is **Enabled** - Ensure printer is connected to client device - Restart WorkSpace session

**Print jobs fail**: - Check driver versions on both client and WorkSpace - Review logs at: **C:\$1ProgramData\$1Amazon\$1WSP\$1Logs\$1agentsession.log** - Look for "Advanced print is enabled" in logs

Enable detailed logging: In Group Policy, set Configure log verbosity to debug under **Computer Configuration** > **Policies** > **Administrative Templates** > **Amazon** > **WSP**. 

### Configure clipboard redirection (copy/paste) for DCV
<a name="gp_clipboard_wsp"></a>

By default, WorkSpaces supports two-way (copy/paste) clipboard redirection. For Windows WorkSpaces, you can use Group Policy settings to disable this feature or configure the direction where clipboard redirection is allowed. 

**To configure clipboard redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure clipboard redirection** setting.

1. In the **Configure clipboard redirection** dialog box, choose **Enabled** or **Disabled**.

   When **Configure clipboard redirection** is **Enabled**, the following **Clipboard redirection options** will become available:
   + Choose **Copy and Paste** to allow two-way clipboard copy and paste redirection.
   + Choose **Copy Only** to allow copying data from the server clipboard to the client clipboard only.
   + Choose **Paste Only** to allow pasting data from the client clipboard to the server clipboard only.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

**Known limitation**  
With clipboard redirection enabled on the WorkSpace, if you copy content that is larger than 890 KB from a Microsoft Office application, the application might become slow or unresponsive for up to 5 seconds.

### Set the session resume timeout for DCV
<a name="gp_auto_resume_wsp"></a>

When you lose network connectivity, your active WorkSpaces client session is disconnected. WorkSpaces client applications for Windows and macOS attempt to reconnect the session automatically if network connectivity is restored within a certain amount of time. The default session resume timeout is 20 minutes (1200 seconds), but you can modify that value for WorkSpaces that are controlled by your domain's Group Policy settings. 

**To set the automatic session resume timeout value**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable/disable automatic reconnect** setting.

1. In the **Enable/disable automatic reconnect** dialog box, choose **Enabled**, and then set **Reconnect timeout (seconds)** to the desired timeout in seconds.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure video-in redirection for DCV
<a name="gp_video_in_wsp"></a>

By default, WorkSpaces supports redirecting data from a local camera. If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature. 

**To configure video-in redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable/disable video-in redirection** setting.

1. In the **Enable/disable video-in redirection** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure audio-in redirection for DCV
<a name="gp_audio_in_wsp"></a>

By default, WorkSpaces supports redirecting data from a local microphone. If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature. 

**To configure audio-in redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable/disable audio-in redirection** setting.

1. In the **Enable/disable audio-in redirection** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure audio-out redirection for DCV
<a name="gp_audio_out_wsp"></a>

By default, WorkSpaces redirects data to a local speaker. If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature. 

**To configure audio-out redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable/disable audio-out redirection** setting.

1. In the **Enable/disable audio-out redirection** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace. In the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions** > **Reboot WorkSpaces**.
   + In an administrative command prompt, enter **gpupdate /force**.

### Disable time zone redirection for DCV
<a name="gp_time_zone_wsp"></a>

By default, the time within a Workspace is set to mirror the time zone of the client that is being used to connect to the WorkSpace. This behavior is controlled through time zone redirection. You might want to turn off time zone direction for various reasons. For example: 
+ Your company wants all employees to work in a certain time zone (even if some employees are in other time zones).
+ You have scheduled tasks in a WorkSpace that are meant to run at a certain time in a specific time zone.
+ Your users who travel a lot want to keep their WorkSpaces in one time zone for consistency and personal preference.

If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature.

**To disable time zone redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable/disable time zone redirection** setting.

1. In the **Enable/disable time zone redirection** dialog box, choose **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

1. Set the time zone for the WorkSpaces to the desired time zone.

The time zone of the WorkSpaces is now static and no longer mirrors the time zone of the client machines. 

### Configure DCV security settings
<a name="wsp_security"></a>

For DCV, data in transit is encrypted using TLS 1.2 encryption. By default, all of the following ciphers are allowed for encryption, and the client and server negotiate which cipher to use:
+ ECDHE-RSA-AES128-GCM-SHA256
+ ECDHE-ECDSA-AES128-GCM-SHA256
+ ECDHE-RSA-AES256-GCM-SHA384
+ ECDHE-ECDSA-AES256-GCM-SHA384
+ ECDHE-RSA-AES128-SHA256
+ ECDHE-RSA-AES256-SHA384

For Windows WorkSpaces, you can use Group Policy settings to modify the TLS Security Mode and to add new or block certain cipher suites. A detailed explanation of these settings and the supported cipher suites is provided in the **Configure security settings Group Policy **dialog box.

**To configure DCV security settings**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open **Configure security settings**.

1. In the **Configure security settings** dialog box, choose **Enabled**. Add cipher suites that you want to allow and remove cipher suites that you want to block. For more information about these settings, see the descriptions provided in the **Configure security settings** dialog box.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace, and after you restart the WorkSpace session. To apply the Group Policy changes, do one of the following:
   + To reboot the WorkSpace, in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**.
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure extensions for DCV
<a name="extensions"></a>

By default, support for WorkSpaces extensions is disabled. If needed, you can configure your WorkSpace to use extensions in the following ways:
+ Server and client – Enable extensions for both server and client
+ Server only – Enable extensions for server only
+ Client only – Enable extensions for client only

For Windows WorkSpaces, you can use Group Policy settings to configure the use of extensions.

**To configure extensions for DCV**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure extensions** setting.

1. In the **Configure extensions** dialog box, choose **Enabled** and then set the desired support option. Choose **Client Only**, **Server and Client**, or **Server only**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after you restart the WorkSpace session. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace. In the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**.
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure smart card redirection for DCV
<a name="gp_smart_cards_in_wsp"></a>

By default, Amazon WorkSpaces are not enabled to support the use of smart cards for either *pre-session authentication* or *in-session authentication*. Pre-session authentication refers to smart card authentication that's performed while users are logging in to their WorkSpaces. In-session authentication refers to authentication that's performed after logging in.

If needed, you can enable pre-session and in-session authentication for Windows WorkSpaces by using Group Policy settings. Pre-session authentication must also be enabled through your AD Connector directory settings by using the **EnableClientAuthentication** API action or the **enable-client-authentication** AWS CLI command. For more information, see [ Enable Smart Card Authentication for AD Connector](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ad_connector_clientauth.html) in the *AWS Directory Service Administration Guide*.

**Note**  
To enable the use of smart cards with Windows WorkSpaces, additional steps are required. For more information, see [Use smart cards for authentication in WorkSpaces Personal](smart-cards.md). 

**To configure smart card redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable/disable smart card redirection** setting.

1. In the **Enable/disable smart card redirection** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted. To apply the Group Policy change, reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).

### WebAuthn (FIDO2) Redirection for DCV
<a name="gp_webauthn_fido2_in_wsp"></a>

By default, Amazon WorkSpaces enables WebAuthn redirection, allowing users to use their local FIDO2-compatible security keys and biometric authenticators with applications running inside their WorkSpace. This feature securely redirects authentication requests from applications in the WorkSpace to the user's local device, providing seamless access to authentication methods including Yubikeys and Windows Hello.

Amazon WorkSpaces supports two versions of WebAuthn redirection:
+ **Standard WebAuthn** - Requires a browser extension, supported on Windows and Linux WorkSpaces, for browser-based apps
+ **Enhanced WebAuthn** - No browser extension required, with additional native application support, supported on Windows WorkSpaces only

#### Standard WebAuthn redirection
<a name="w2aac11c31c11c19b5c21b9"></a>

Standard WebAuthn redirection requires a browser extension to facilitate the redirection of WebAuthn prompts to the client device.

##### Version requirements
<a name="w2aac11c31c11c19b5c21b9b5"></a>
+ **Windows WorkSpaces**: DCV host agent version 2.0.0.1425 or higher
+ **Client versions:**
  + Windows client: 5.19.0 or above
  + Mac client: 5.19.0 or above
  + Linux client: 2024.0 or above

##### Supported browsers on WorkSpaces
<a name="w2aac11c31c11c19b5c21b9b7"></a>
+ Google Chrome 116\$1
+ Microsoft Edge 116\$1

#### Enhanced WebAuthn redirection
<a name="w2aac11c31c11c19b5c21c11"></a>

Enhanced WebAuthn redirection eliminates the need for a browser extension and provides support for WebAuthn authentication in native Windows applications that support WebAuthn authentication.

##### Version requirements
<a name="w2aac11c31c11c19b5c21c11b5"></a>
+ **Windows WorkSpaces**: DCV host agent version 2.1.0.2000 or higher
+ **Client versions:**
  + Windows client: 5.29.0 or above
  + Mac client: 5.29.0 or above

##### Key benefits
<a name="w2aac11c31c11c19b5c21c11b7"></a>
+ No browser extension required
+ Improved performance
+ Support for WebAuthn in native Windows applications
+ Seamless authentication experience across browsers and desktop applications

##### Supported browsers on WorkSpaces
<a name="w2aac11c31c11c19b5c21c11b9"></a>
+ Google Chrome 116\$1
+ Microsoft Edge 116\$1

#### Configure WebAuthn redirection
<a name="w2aac11c31c11c19b5c21c13"></a>

**To configure WebAuthn redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **DCV**.

1. Open the **Configure WebAuthn redirection** setting.

1. In the **Configure WebAuthn redirection** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted. To apply the Group Policy changes, reboot the WorkSpace by going to the Amazon WorkSpaces console and selecting the WorkSpace. Then, choose **Actions**, **Reboot WorkSpaces**.

**Note**  
This Group Policy setting enables WebAuthn redirection. The version used (Standard or Enhanced) depends on your host agent version and operating system support.

#### Configure WebAuthn process compatibility
<a name="w2aac11c31c11c19b5c21c15"></a>

When WebAuthn redirection is enabled, you can configure which applications and processes are allowed to use WebAuthn redirection through the **WebAuthn Process Compatibility List**.

##### Default process compatibility list
<a name="w2aac11c31c11c19b5c21c15b5"></a>

By default, the following processes are enabled for WebAuthn redirection:

```
['chrome.exe','msedge.exe','island.exe','firefox.exe','dcvwebauthnnativemsghost.exe','msedgewebview2.exe','Microsoft.AAD.BrokerPlugin.exe']
```

##### Required process for Standard WebAuthn
<a name="w2aac11c31c11c19b5c21c15b7"></a>
+ `dcvwebauthnnativemsghost.exe` - This process is **required** for Standard WebAuthn functionality and must remain in the compatibility list when using Standard WebAuthn.

**To configure the WebAuthn process compatibility list**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **DCV**.

1. Open the **Configure WebAuthn Redirection** setting.

1. Choose **Enabled**.

1. In the **WebAuthn process compatibility list** field, specify the list of process names that are compatible with WebAuthn redirection.
   + Use the default list as a starting point
   + Add additional process names as needed for your environment

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted.

##### Process compatibility list guidelines
<a name="w2aac11c31c11c19b5c21c15c11"></a>
+ **For Standard WebAuthn**: Always include `dcvwebauthnnativemsghost.exe` in the list
+ **Custom Applications**: Add any additional `.exe` process names that need WebAuthn support in your environment
+ **Format**: Use comma-separated process names enclosed in square brackets, with each process name in single quotes

##### Example custom process list
<a name="w2aac11c31c11c19b5c21c15c11b5"></a>

```
['chrome.exe','msedge.exe','firefox.exe','dcvwebauthnnativemsghost.exe','msedgewebview2.exe','Microsoft.AAD.BrokerPlugin.exe','myapp.exe','customapplication.exe']
```

#### Transitioning from Standard to Enhanced WebAuthn
<a name="w2aac11c31c11c19b5c21c17"></a>

When upgrading from Standard WebAuthn to Enhanced WebAuthn, **users will need to uninstall or disable the Amazon DCV WebAuthn Redirection browser extension** they previously installed for Standard WebAuthn before using Enhanced WebAuthn.

##### Why this step is important
<a name="w2aac11c31c11c19b5c21c17b5"></a>
+ Enhanced WebAuthn handles redirection natively without browser extensions
+ Leaving the extension enabled will default to Standard WebAuthn redirection

#### Installing the Amazon DCV WebAuthn Redirection Extension (Standard WebAuthn Only)
<a name="installing_webauthn"></a>

**Note**  
This section only applies to Standard WebAuthn. Enhanced WebAuthn does not require browser extensions.

Users will need to install the Amazon DCV WebAuthn Redirection Extension to use Standard WebAuthn after the feature is enabled by doing either of the following:
+ Users will be prompted to enable the browser extension in their browser.
**Note**  
 This is a one-time browser prompt. Your users will get the notification when you update the DCV agent version to 2.0.0.1425 or higher. If your end users don’t need the WebAuthn redirection, they can just remove the extension from the browser. You can also block the WebAuthn Redirection Extension installation prompt using GPO policy.
+ You can force install the redirection extension for your users using GPO policy. If you enable the GPO policy, the extension will automatically be installed when your users launch the supported browsers with internet access.
+ Users can install the extension manually with [ Microsoft Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/dcv-webauthn-redirection-/ihejeaahjpbegmaaegiikmlphghlfmeh) or the [ Chrome Web Store](https://chromewebstore.google.com/detail/dcv-webauthn-redirection/mmiioagbgnbojdbcjoddlefhmcocfpmn?pli=1).

##### Understanding WebAuthn Redirection Extension Native Messaging
<a name="installing_webauthn-understand"></a>

WebAuthn redirection in Chrome and Edge browsers utilizes a browser extension and a native messaging host. The native messaging host is a component that allows communication between the extension and the host application. In a typical configuration, all native messaging hosts are permitted by the browser by default. However, you can choose to use a native messaging blocklist, where the value of \$1 means that all native messaging hosts are denied unless explicitly allowed. In this case, you need to enable the Amazon DCV WebAuthn Redirection native messaging host by explicitly specifying the value `com.dcv.webauthnredirection.nativemessagehost` in the allow list.

For more information, follow the guidance for your browser:
+ For Google Chrome, see [Native Messaging allowed hosts](https://support.google.com/chrome/a/answer/2657289#zippy=%2Cnative-messaging-allowed-hosts).
+ For Microsoft Edge, see [Native Messaging](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-policies#native-messaging).

##### Manage and install the browser extension using Group Policy
<a name="w2aac11c31c11c19b5c21c19c11"></a>

You can install the Amazon DCV WebAuthn Redirection Extension using Group Policy, either centrally from your domain for session hosts that are joined to an Active Directory (AD) domain or using the Local Group Policy Editor for each session host. This process will change depending on which browser you're using.

**For Microsoft Edge**

1. Download and install the [ Microsoft Edge administrative template](https://learn.microsoft.com/en-us/deployedge/configure-microsoft-edge#1-download-and-install-the-microsoft-edge-administrative-template).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**).

1. Expand the forest (**Forest:*FQDN***).

1. Expand **Domains**. 

1. Expand your FQDN (for example, `example.com`).

1. Expand **Group Policy Objects**.

1. Select **Default Domain Policy**, open the context (right-click) menu, and choose **Edit**.

1. Choose **Computer Configuration **, **Administrative Templates**, **Microsoft Edge**, and **Extensions**

1. Open **Configure extension management settings** and set it to **Enabled**.

1. Under **Configure extension management settings**, enter the following:

   ```
   {"ihejeaahjpbegmaaegiikmlphghlfmeh":{"installation_mode":"force_installed","update_url":"https://edge.microsoft.com/extensionwebstorebase/v1/crx"}}
   ```

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted. To apply the Group Policy changes, reboot the WorkSpace by going to the Amazon WorkSpaces console and selecting the WorkSpace. Then, choose **Actions**, **Reboot WorkSpaces**).

**Note**  
You can block the installation of the extension by applying the following configuration management setting:  

```
{"ihejeaahjpbegmaaegiikmlphghlfmeh":{"installation_mode":"blocked","update_url":"https://edge.microsoft.com/extensionwebstorebase/v1/crx"}}
```

**For Google Chrome**

1. Download and install the Google Chrome administrative template. For more information, see [ Set Chrome Browser policies on managed PCs](https://support.google.com/chrome/a/answer/187202#zippy=%2Cwindows).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**).

1. Expand the forest (**Forest:*FQDN***).

1. Expand **Domains**. 

1. Expand your FQDN (for example, `example.com`).

1. Expand **Group Policy Objects**.

1. Select **Default Domain Policy**, open the context (right-click) menu, and choose **Edit**.

1. Choose **Computer Configuration **, **Administrative Templates**, **Google Chrome**, and **Extensions**

1. Open **Configure extension management settings** and set it to **Enabled**.

1. Under **Configure extension management settings**, enter the following:

   ```
   {"mmiioagbgnbojdbcjoddlefhmcocfpmn":{ "installation_mode":"force_installed","update_url":"https://clients2.google.com/service/update2/crx"}}
   ```

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted. To apply the Group Policy changes, reboot the WorkSpace by going to the Amazon WorkSpaces console and selecting the WorkSpace. Then, choose **Actions**, **Reboot WorkSpaces**).

**Note**  
You can block the installation of the extension by applying the following configuration management setting:  

```
{"mmiioagbgnbojdbcjoddlefhmcocfpmn":{ "installation_mode":"blocked","update_url":"https://clients2.google.com/service/update2/crx"}}
```

### Configure WebRTC redirection for DCV
<a name="gp_webrtc_in_wsp"></a>

WebRTC redirection enhances real-time communication by offloading audio and video processing from WorkSpaces to your local client, which improves performance and reduces latency. However, WebRTC redirection isn't universal and requires third-party application vendors to develop specific integrations with WorkSpaces. By default, WebRTC redirection isn't enabled on WorkSpaces. To use WebRTC redirection, ensure the following:
+ Third-party application vendor integration
+ WorkSpaces extensions are enabled through Group Policy settings
+ WebRTC redirection is enabled
+ WebRTC redirection Browser extension is installed and enabled

**Note**  
This redirection is implemented as an extension and requires you to enable support for WorkSpaces extensions using Group Policy settings. If the extensions are disabled, WebRTC redirection will not function. 

#### Requirements
<a name="w2aac11c31c11c19b5c23b9"></a>

WebRTC redirection for DCV requires the following:
+ DCV host agent version 2.0.0.1622 or higher
+ WorkSpaces clients:
  + Windows 5.21.0 or higher
  + Web client
+ Web browsers installed on your WorkSpaces running the Amazon DCV WebRTC Redirection Extension:
  + Google Chrome 116\$1
  + Microsoft Edge 116\$1

#### Enabling or disabling WebRTC redirection for Windows WorkSpaces
<a name="w2aac11c31c11c19b5c23c11"></a>

If needed, you can enable or disable support for WebRTC redirection for Windows WorkSpaces by using Group Policy settings. If you disable or don't configure this setting, WebRTC redirection will be disabled.

When feature is enabled, web applications that have integration with Amazon WorkSpaces will be able to redirect WebRTC API calls to the local client.

**To configure WebRTC redirection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure WebRTC Redirection** setting.

1. In the **Configure WebRTC Redirection** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted. To apply the Group Policy changes, reboot the WorkSpace by going to the Amazon WorkSpaces console and selecting the WorkSpace. Then, choose **Actions**, **Reboot WorkSpaces**).

#### Installing the Amazon DCV WebRTC Redirection Extension
<a name="installing_webrtc"></a>

Users install the Amazon DCV WebRTC Redirection Extension to use WebRTC redirection after the feature is enabled by doing either of the following:
+ Users will be prompted to enable the browser extension in their browser.
**Note**  
As a one-time browser prompt, users will get the notification when you enable WebRTC redirection.
+ You can force install the redirection extension for users using the following GPO policy. If you enable the GPO policy, the extension will automatically be installed when users launch the supported browsers with internet access.
+ Users can install the extension manually with [ Microsoft Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/amazon-dcv-webrtc-redirec/kjbbkjjiecchbcdoollhgffghfjnbhef) or the [ Chrome Web Store](https://chromewebstore.google.com/detail/dcv-webrtc-redirection-ex/diilpfplcnhehakckkpmcmibmhbingnd?hl=en&authuser=0&pli=1).

##### Manage and install the browser extension using Group Policy
<a name="w2aac11c31c11c19b5c23c13b7"></a>

You can install the Amazon DCV WebRTC Redirection Extension using Group Policy, either centrally from your domain, for session hosts joined to an Active Directory (AD) domain, or using the Local Group Policy Editor for each session host. This process will be different depending on which browser you're using.

**For Microsoft Edge**

1. Download and install the [ Microsoft Edge administrative template](https://learn.microsoft.com/en-us/deployedge/configure-microsoft-edge#1-download-and-install-the-microsoft-edge-administrative-template).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**).

1. Expand the forest (**Forest:*FQDN***).

1. Expand **Domains**. 

1. Expand your FQDN (for example, `example.com`).

1. Expand **Group Policy Objects**.

1. Select **Default Domain Policy**, open the context (right-click) menu, and choose **Edit**.

1. Choose **Computer Configuration **, **Administrative Templates**, **Microsoft Edge**, and **Extensions**

1. Open **Configure extension management settings** and set it to **Enabled**.

1. Under **Configure extension management settings**, enter the following:

   ```
   {"kjbbkjjiecchbcdoollhgffghfjnbhef":{"installation_mode":"force_installed","update_url":"https://edge.microsoft.com/extensionwebstorebase/v1/crx"}}
   ```

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted. To apply the Group Policy changes, reboot the WorkSpace by going to the Amazon WorkSpaces console and selecting the WorkSpace. Then, choose **Actions**, **Reboot WorkSpaces**).

**Note**  
You can block the installation of the extension by applying the following configuration management setting:  

```
{"kjbbkjjiecchbcdoollhgffghfjnbhef":{"installation_mode":"blocked","update_url":"https://edge.microsoft.com/extensionwebstorebase/v1/crx"}}
```

**For Google Chrome**

1. Download and install the Google Chrome administrative template. For more information, see [ Set Chrome Browser policies on managed PCs](https://support.google.com/chrome/a/answer/187202#zippy=%2Cwindows).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**).

1. Expand the forest (**Forest:*FQDN***).

1. Expand **Domains**. 

1. Expand your FQDN (for example, `example.com`).

1. Expand **Group Policy Objects**.

1. Select **Default Domain Policy**, open the context (right-click) menu, and choose **Edit**.

1. Choose **Computer Configuration **, **Administrative Templates**, **Google Chrome**, and **Extensions**

1. Open **Configure extension management settings** and set it to **Enabled**.

1. Under **Configure extension management settings**, enter the following:

   ```
   {"diilpfplcnhehakckkpmcmibmhbingnd":{ "installation_mode":"force_installed","update_url":"https://clients2.google.com/service/update2/crx"}}
   ```

1. Choose **OK**.

1. The Group Policy setting change takes effect after the WorkSpace session is restarted. To apply the Group Policy changes, reboot the WorkSpace by going to the Amazon WorkSpaces console and selecting the WorkSpace. Then, choose **Actions**, **Reboot WorkSpaces**).

**Note**  
You can block the installation of the extension by applying the following configuration management setting:  

```
{"diilpfplcnhehakckkpmcmibmhbingnd":{ "installation_mode":"blocked","update_url":"https://clients2.google.com/service/update2/crx"}}
```

### Configure disconnect session on screen lock for DCV
<a name="gp_lock_screen_in_wsp"></a>

If needed, you can disconnect users' WorkSpaces sessions when the Windows lock screen is detected. To reconnect from the WorkSpaces client, users can use their passwords or their smart cards to authenticate themselves, depending on which type of authentication has been enabled for their WorkSpaces.

This Group Policy setting is disabled by default. If needed, you can enable disconnecting the session when the Windows lock screen is detected for Windows WorkSpaces by using Group Policy settings.

**Note**  
This Group Policy setting applies to both password-authenticated and smart card-authenticated sessions.
To enable the use of smart cards with Windows WorkSpaces, additional steps are required. For more information, see [Use smart cards for authentication in WorkSpaces Personal](smart-cards.md). 

**To configure disconnect session on screen lock for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable/disable disconnect session on screen lock** setting.

1. In the **Enable/disable disconnect session on screen lock** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure Screen Capture Protection for DCV
<a name="screen_capture_protection"></a>

Screen Capture Protection prevents screenshots, screen recordings, and screen sharing of WorkSpaces sessions from local client tools. When enabled, attempts to capture screen content from client side will show either the background or a black rectangle, helping protect sensitive information from exfiltration.

#### Requirements
<a name="w2aac11c31c11c19b5c27b5"></a>

Screen capture protection for DCV requires the following:
+ DCV host agent version 2.2.0.2116 or higher
+ WorkSpaces clients:
  + Windows 5.30.2 or higher
  + MacOS 5.30.2 or higher

**Note**  
 This feature is not supported on Linux clients, Web Access, or PCoIP protocol. 
Protection applies to captures initiated from the client device. Users can still take screenshots from within the WorkSpace itself. 
The feature is not compatible with screen sharing on MS Teams. 

#### Known limitations
<a name="w2aac11c31c11c19b5c27b9"></a>
+ The feature cannot prevent physical camera captures of screens.
+ The feature does not protect against direct RDP connections to the host server.
+ The feature does not protect against capture attempts initiated from within the WorkSpace itself, including screen share features of collaboration and chat tools.
+ All capture methods are blocked when enabled (selective blocking is not available).
+ MacOS client window may be grayed out if the feature is enabled and a video capture is attempted (e.g. trying to screen share the client window).

**To configure Screen Capture Protection for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure Screen Capture Protection** setting.

1. In the **Configure Screen Capture Protection** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:

   1. Reboot the WorkSpace (in the WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).

   1. In an administrative command prompt, enter `gpupdate /force`.

### Configure Indirect Display Driver (IDD) for DCV
<a name="indirect_display_driver"></a>

By default, WorkSpaces supports using Indirect Display Driver (IDD). If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature.

**To configure Indirect Display Driver (IDD) for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable the AWS Indirect Display Driver** setting.

1. In the **Enable the AWS Indirect Display Driver** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:

   1. Reboot the WorkSpace (in the WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).

   1. In an administrative command prompt, enter `gpupdate /force`.

### Configure display settings for DCV
<a name="display_settings"></a>

WorkSpaces allows you to configure several different display settings, including the maximum frame rate, minimum image quality, maximum image quality, and YUV encoding. Adjust these settings based on the image quality, responsiveness, and color accuracy that you need. 

By default, the maximum frame rate value is 25. The maximum frame rate value specifies the maximum allowed frames per second (fps). A value of 0 means no limit.

By default, the minimum image quality value is 30. The minimum image quality can be optimized for best image responsiveness, or best image quality. For best responsiveness, reduce the minimum quality. For best quality, increase the minimum quality.
+ Ideal values for best responsiveness are between 30 and 90.
+ Ideal values for best quality are between 60 and 90.

By default, the maximum image quality value is 80. The maximum image quality doesn't affect the image responsiveness or quality, but sets a maximum to limit network usage.

By default, image encoding is set to YUV420. Selecting **Enable YUV444 encoding** enables YUV444 encoding for high color accuracy.

For Windows WorkSpaces, you can use Group Policy settings to configure the maximum frame rate, minimum image quality, and maximum image quality values.

**To configure display settings for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure display settings** setting.

1. In the **Configure display settings** dialog box, choose **Enabled** and then set the **Maximum frame rate (fps)**, **minimum image quality**, and **maximum image quality** values to the desired levels.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after you restart the WorkSpace session. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace. the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure VSync for the AWS Virtual Display-Only Driver for DCV
<a name="vsync"></a>

By default, WorkSpaces supports using the VSync feature for the AWS Virtual Display-Only Driver. If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature.

**To configure VSync for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Enable VSync feature of the AWS Virtual Display Only Driver** setting.

1. In the **Enable VSync feature of the AWS Virtual Display Only Driver** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do the following:

   1. Restart the WorkSpace by doing the either of the following:

      1. Option 1 — In the WorkSpaces console, choose the WorkSpace you want to reboot. Then, choose **Actions**, **Reboot WorkSpaces**.

      1. Option 2 — In an administrative command prompt, enter `gpupdate /force`.

   1. Reconnect to the WorkSpace in order to apply the setting.

   1. Reboot the Workspace again.

### Configure log verbosity for DCV
<a name="log_verbosity"></a>

By default, the log verbosity level for DCV WorkSpaces is set to **Info**. You can set log levels to verbosity levels ranging from least verbose to most verbose, as detailed here:
+ Error – least verbose
+ Warning
+ Info – default
+ Debug – most verbose

For Windows WorkSpaces, you can use Group Policy settings to configure the log verbosity levels.

**To configure log verbosity levels for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure log verbosity** setting.

1. In the **Configure log verbosity** dialog box, choose **Enabled** and then set the log verbosity level to **debug**, **error**, **info**, or **warning**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after you restart the WorkSpace session. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace. In the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**.
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure idle disconnect timeout for DCV
<a name="idle-disconnect"></a>

WorkSpaces allows you to configure how long a user can be inactive, while connected to a WorkSpace, before they are disconnected. Examples of user activity input include the following:
+ Keyboard events
+ Mouse events (cursor movement, scrolling, clicking)
+ Stylus events
+ Touch events (tapping touchscreens, tablets)
+ Gamepad events
+ File storage operations (uploads, downloads, directory creation, list items)
+ Webcam streaming

Audio in, audio out, and pixels changing don't qualify as user activity.

When enabling idle disconnect timeout, you can optionally notify your user that their session will disconnect within the configured time unless they engage.

By default, idle disconnect timeout is disabled, the timeout value is set to 0 minutes, and the notification is disabled. If you enable this policy setting, the idle disconnect timeout value defaults to 60 minutes and the idle disconnect warning value defaults to 60 seconds. For Windows WorkSpaces, you can use Group Policy settings to configure this feature.

**To configure idle disconnect timeout for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure Idle Disconnect Timeout** setting.

1. In the **Configure Idle Disconnect Timeout** dialog box, choose **Enabled** and then set the desired disconnect timeout value (in minutes), and optionally the warning timer value (in seconds).

1. Choose **Apply**, **OK**.

1. The Group Policy setting change takes effect immediately after you apply the change.

### Configure file transfer for DCV
<a name="gp-file-transfer"></a>

By default, Amazon WorkSpaces disables the file transfer function. You can enable it to allow users to upload and download files between their local computer and WorkSpaces session. The files will be saved in a **My Storage** folder on the WorkSpaces session.

**To enable file transfer for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure session storage** setting.

1. In the **Configure Session Storage** dialog box, choose **Enabled**.

1. (Optional) Specify a folder for session storage (for example, `c:/session-storage`). If not specified, the default folder for session storage will be the home folder.

1. You can configure your WorkSpaces with one of the following file transfer options:
   + Choose `Download and Upload` to allow two-way file transfer.
   + Choose `Upload Only` to only allow file uploads from a local computer to your WorkSpaces session.
   + Choose `Download Only` to only allow file downloads from your WorkSpaces session to a local computer.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after you restart the WorkSpace session. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace. In the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**.
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure USB redirection for DCV
<a name="gp_dcv_usbredirection"></a>

#### Overview
<a name="gp_dcv_usbredirection_overview"></a>

Starting with version 2.2.0.2047, Amazon WorkSpaces supports generic USB redirection for DCV-based Windows WorkSpaces, allowing users to access local USB devices within their virtual desktop environments. This feature complements existing optimized redirection solutions for specific device classes.

**Note**  
Amazon recommends using generic redirection only for devices where optimized redirection solutions are not available. Where available, optimized redirection solutions offer better performance.

#### Prerequisites
<a name="gp_dcv_usbredirection_prerequisites"></a>
+ Windows WorkSpaces using DCV protocol version 2.2.0.2047 or later
+ Latest version of WorkSpaces Windows client (version 5.30.0 or later)
+ Administrative access to configure Group Policy settings

#### Configuration
<a name="gp_dcv_usbredirection_config"></a>

USB redirection is disabled by default. You can enable the feature by using Group Policy Objects (GPO). After the feature is enabled, you can add devices to the allowlist for redirection. By default, devices not in the allowlist are not available for redirection.

##### Group Policy Configuration
<a name="gp_dcv_usbredirection_gpo"></a>

**To configure USB redirection for DCV using Group Policy**

1. Connect to the Windows WorkSpaces.

1. Copy policy template files (`wsp.admx` and `wsp.adml`) from the `C:\Program Files\Amazon\WSP` folder.

1. Paste `wsp.admx` into the `C:\Windows\PolicyDefinitions` folder.

1. Paste `wsp.adml` into the `C:\Windows\PolicyDefinitions\en-US` folder.

1. Launch Local GPO Editor (**gpedit.msc**).

1. Navigate to **Local Computer Policy** > **Computer Configuration** > **Administrative Templates** > **Amazon** > **WSP**.

1. Configure **Enable/disable USB** in the WSP setting.

1. Choose **Enabled** to activate USB redirection.

**Note**  
Changes to this setting are applied on the next connection.

#### Device Management
<a name="gp_dcv_usbredirection_device_mgmt"></a>

After USB redirection is enabled, you can configure the device allowlist in the GPO to add devices that you want to support for redirection.

##### Device Allowlist Configuration
<a name="gp_dcv_usbredirection_allowlist"></a>

USB redirection follows a default deny-all security stance. Administrators must explicitly allow devices by adding them to the allowlist in the GPO using the following format:

```
Name, Base class, Subclass, Protocol, Id Vendor, Id Product, Support Auto-share, Skip reset
// Use * to skip any values
```

**Examples:**

**Adding a device with Vendor ID/Product ID:**

```
Credit Card Reader, *, *, *, 0x0483, 0x2016, 1, 0
// Allows Credit Card Reader with VID 0x0483 and PID 0x2016 with auto-share support
```

**Adding a device with Class/Subclass:**

```
3D Mouse Devices, 03, 01, *, *, *, 1, 0
// Allows all 3D mice using HID class (03), boot interface subclass (01), with auto-share support
```

**Note**  
Test devices for compatibility and performance before adding them to the allowlist.

#### Security Considerations
<a name="gp_dcv_usbredirection_security"></a>

##### Best Practices
<a name="gp_dcv_usbredirection_best_practices"></a>
+ Use dedicated redirection methods when available for supported devices for best performance and compatibility. For example, for security keys like YubiKey, use WebAuthn redirection instead.
+ Implement strict device allowlists.
+ Monitor device access through audit logs.
+ Assess data security implications before allowing new devices.

### Configure webcam resolution for DCV
<a name="gp-webcam-resolution"></a>

Use this setting to configure webcam resolution settings. If you enable this policy setting, you can specify:
+ Maximum webcam resolution: This specifies the maximum webcam resolution that can be selected among the resolutions provided. If this value is missing or (0, 0) the default value is used.
+ Preferred webcam resolution: This specifies the preferred webcam resolution among the resolutions provided by the client. If the specified resolution is not supported, the closest matching resolution is selected. If this value is missing or (0, 0) the default value is used.

If you disable or do not configure this policy setting, the default resolutions are used.

**To configure webcam resolution for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure webcam resolution** setting.

1. In the **Configure webcam resolution** dialog box, choose **Enabled** and then set the **Maximum webcam resolution** (in pixels) and/or **Preferred webcam resolution** (in pixels).

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after you restart the WorkSpace session. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace. In the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**.
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure server keyboard layout usage for DCV
<a name="gp-server-keyboard-layout"></a>

This setting controls whether to use server side keyboard layout for key interpretation, as opposed to the default client side keyboard layout. Changes to this setting are applied on the next connection. For more details on keyboard handling please see the *Amazon WorkSpaces User Guide*.

If you enable this policy setting, you can choose one of the following options:
+ **Always Off** - Always use client layout
+ **Always On** - Always use server layout

If you disable or do not configure this policy setting, the **Always Off** option is used.

**Note**  
This feature is supported in the Amazon WorkSpaces Windows client version 5.29.2 or newer, and the Amazon WorkSpaces macOS client version 5.30.0 or newer.

**To configure server keyboard layout usage for Windows WorkSpaces**

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Amazon**, and **WSP**.

1. Open the **Configure server keyboard layout usage** setting.

1. In the **Configure server keyboard layout usage** dialog box, choose **Enabled** and then set the **Server keyboard layout option**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after you restart the WorkSpace session. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace. In the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**.
   + In an administrative command prompt, enter **gpupdate /force**.

## Install the Group Policy administrative template for PCoIP
<a name="gp_install_template"></a>

To use the Group Policy settings that are specific to Amazon WorkSpaces when using the PCoIP protocol, you must add the Group Policy administrative template that is appropriate to the version of the PCoIP agent (either 32-bit or 64-bit) that is being used for your WorkSpaces. 

**Note**  
If you have a mix of WorkSpaces with 32-bit and 64-bit agents, you can use the Group Policy administrative templates for 32-bit agents, and your Group Policy settings will be applied to both 32-bit and 64-bit agents. When all of your WorkSpaces are using the 64-bit agent, you can switch to using the administrative template for 64-bit agents.

**To determine whether your WorkSpaces have the 32-bit agent or the 64-bit agent**

1. Log in to a WorkSpace, and then open the Task Manager by choosing **View**, **Send Ctrl \$1 Alt \$1 Delete** or by right-clicking the task bar and choosing **Task Manager**.

1. In the Task Manager, go to the **Details** tab, right-click the column headers, and choose **Select Columns**.

1. In the **Select Columns** dialog box, select **Platform**, and then choose **OK**. 

1. On the **Details** tab, find `pcoip_agent.exe`, and then check its value in the **Platform** column to determine if the PCoIP agent is 32-bit or 64-bit. (You might see a mix of 32-bit and 64-bit WorkSpaces components; this is normal.)

### Install the Group Policy administrative template for PCoIP (32-Bit)
<a name="gp_install_template_pcoip_32_bit"></a>

To use the Group Policy settings that are specific to WorkSpaces when using the PCoIP protocol with the 32-bit PCoIP agent, you must install the Group Policy administrative template for PCoIP. Perform the following procedure on a directory administration WorkSpace or Amazon EC2 instance that is joined to your directory. 

For more information about working with .adm files, see [ Recommendations for managing Group Policy administrative template (.adm) files](https://docs.microsoft.com/troubleshoot/windows-server/group-policy/manage-group-policy-adm-file) in the Microsoft documentation.

**To install the Group Policy administrative template for PCoIP**

1. From a running Windows WorkSpace, make a copy of the `pcoip.adm` file in the `C:\Program Files (x86)\Teradici\PCoIP Agent\configuration` directory.

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to the organizational unit in your domain that contains your WorkSpaces machine accounts.

1. Open the context (right-click) menu for the machine account organizational unit and choose **Create a GPO in this domain, and link it here**.

1. In the **New GPO** dialog box, enter a descriptive name for the GPO, such as **WorkSpaces Machine Policies**, and leave **Source Starter GPO** set to **(none)**. Choose **OK**.

1. Open the context (right-click) menu for the new GPO and choose **Edit**.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, and **Administrative Templates**. Choose **Action**, **Add/Remove Templates** from the main menu. 

1. In the **Add/Remove Templates** dialog box, choose **Add**, select the `pcoip.adm` file copied previously, and then choose **Open**, **Close**.

1. Close the Group Policy Management Editor. You can now use this GPO to modify the Group Policy settings that are specific to WorkSpaces.

**To verify that the administrative template file is correctly installed**

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to and select the WorkSpaces GPO for your WorkSpaces machine accounts. Choose **Action**, **Edit** in the main menu.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Classic Administrative Templates**, and **PCoIP Session Variables**.

1. You can now use this **PCoIP Session Variables** Group Policy object to modify the Group Policy settings that are specific to Amazon WorkSpaces when using PCoIP. 
**Note**  
To allow the user to override your settings, choose **Overridable Administrator Settings**; otherwise, choose **Not Overridable Administrator Settings**.

### Install the Group Policy administrative template for PCoIP (64-Bit)
<a name="gp_install_template_pcoip_64_bit"></a>

To use the Group Policy settings that are specific to WorkSpaces when using the PCoIP protocol, you must add the Group Policy administrative template `PCoIP.admx` and `PCoIP.adml` files for PCoIP to the Central Store of the domain controller for your WorkSpaces directory. For more information about `.admx` and `.adml` files, see [ How to create and manage the Central Store for Group Policy Administrative Templates in Windows](https://support.microsoft.com/help/3087759/how-to-create-and-manage-the-central-store-for-group-policy-administra).

The following procedure describes how to create the Central Store and add the administrative template files to it. Perform the following procedure on a directory administration WorkSpace or Amazon EC2 instance that is joined to your WorkSpaces directory.

**To install the Group Policy administrative template files for PCoIP**

1. From a running Windows WorkSpace, make a copy of the `PCoIP.admx` and `PCoIP.adml` files in the `C:\Program Files\Teradici\PCoIP Agent\configuration\policyDefinitions` directory. The `PCoIP.adml` file is in the `en-US` subfolder of that directory.

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open Windows File Explorer, and in the address bar, enter your organization's fully qualified domain name (FQDN), such as `\\example.com`.

1. Open the `sysvol` folder.

1. Open the folder with the `FQDN` name.

1. Open the `Policies` folder. You should now be in `\\FQDN\sysvol\FQDN\Policies`.

1. If it doesn't already exist, create a folder named `PolicyDefinitions`.

1. Open the `PolicyDefinitions` folder.

1. Copy the `PCoIP.admx` file into the `\\FQDN\sysvol\FQDN\Policies\PolicyDefinitions` folder.

1. Create a folder named `en-US` in the `PolicyDefinitions` folder.

1. Open the `en-US` folder.

1. Copy the `PCoIP.adml` file into the `\\FQDN\sysvol\FQDN\Policies\PolicyDefinitions\en-US` folder.

**To verify that the administrative template files are correctly installed**

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**).

1. Expand the forest (**Forest:*FQDN***).

1. Expand **Domains**. 

1. Expand your FQDN (for example, `example.com`).

1. Expand **Group Policy Objects**.

1. Select **Default Domain Policy**, open the context (right-click) menu, and choose **Edit**.
**Note**  
If the domain backing the WorkSpaces is an AWS Managed Microsoft AD directory, you cannot use the Default Domain Policy to create your GPO. Instead, you must create and link the GPO under the domain container that has delegated privileges.  
When you create a directory with AWS Managed Microsoft AD, Directory Service creates a *yourdomainname* organizational unit (OU) under the domain root. The name of this OU is based on the NetBIOS name that you typed when you created your directory. If you didn't specify a NetBIOS name, it will default to the first part of your Directory DNS name (for example, in the case of `corp.example.com`, the NetBIOS name is `corp`).  
To create your GPO, instead of selecting **Default Domain Policy**, select the *yourdomainname* OU (or any OU under that one), open the context (right-click) menu, and choose **Create a GPO in this domain, and Link it here**.   
For more information about the *yourdomainname* OU, see [ What Gets Created](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started_what_gets_created.html) in the *AWS Directory Service Administration Guide*.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, and **PCoIP Session Variables**.

1. You can now use this **PCoIP Session Variables** Group Policy object to modify the Group Policy settings that are specific to WorkSpaces when using PCoIP.
**Note**  
To allow the user to override your settings, choose **Overridable Administrator Settings**; otherwise, choose **Not Overridable Administrator Settings**.

## Manage Group Policy settings for PCoIP
<a name="gp_configurations_pcoip"></a>

Use Group Policy settings to manage your Windows WorkSpaces that use PCoIP.

### Configure printer support for PCoIP
<a name="gp_local_printers"></a>

By default, WorkSpaces enables Basic remote printing, which offers limited printing capabilities because it uses a generic printer driver on the host side to ensure compatible printing.

Advanced remote printing for Windows clients lets you use specific features of your printer, such as double-sided printing, but it requires installation of the matching printer driver on the host side.

Remote printing is implemented as a virtual channel. If virtual channels are disabled, remote printing does not function.

For Windows WorkSpaces, you can use Group Policy settings to configure printer support as needed.

**To configure printer support**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Configure remote printing** setting.

1. In the **Configure remote printing** dialog box, do one of the following:
   + To enable Advanced remote printing, choose **Enabled**, and then under **Options,** **Configure remote printing**, choose **Basic and Advanced printing for Windows clients**. To automatically use the client computer's current default printer, select **Automatically set default printer**.
   + To disable printing, choose **Enabled**, and then under **Options,** **Configure remote printing**, choose **Printing disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

By default, local printer auto-redirection is disabled. You can use Group Policy settings to enable this feature so that your local printer is set as the default printer every time that you connect to your WorkSpace.

**Note**  
Local printer redirection is not available for Amazon Linux WorkSpaces. 

**To enable local printer auto-redirection**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Configure remote printing** setting.

1. Choose **Enabled**, and then under **Options**, **Configure remote printing**, choose one of the following:
   + **Basic and Advanced printing for Windows clients**
   + **Basic printing**

1. Select **Automatically set default printer**, and then choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure clipboard redirection (copy/paste) for PCoIP
<a name="gp_clipboard"></a>

By default, WorkSpaces supports clipboard redirection. If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature. 

**To enable or disable clipboard redirection**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Configure clipboard redirection** setting.

1. In the **Configure clipboard redirection** dialog box, choose **Enabled** and then choose one of the following settings to determine the direction in which clipboard redirection is allowed. When you're done, choose **OK**.
   + Disabled in both directions
   + Enabled agent to client only (WorkSpace to local computer)
   + Enabled client to agent only (local computer to WorkSpace)
   + Enabled in both directions 

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

**Known limitation**  
With clipboard redirection enabled on the WorkSpace, if you copy content that is larger than 890 KB from a Microsoft Office application, the application might become slow or unresponsive for up to 5 seconds.

### Set the session resume timeout for PCoIP
<a name="gp_auto_resume"></a>

When you lose network connectivity, your active WorkSpaces client session is disconnected. WorkSpaces client applications for Windows and macOS attempt to reconnect the session automatically if network connectivity is restored within a certain amount of time. The default session resume timeout is 20 minutes, but you can modify that value for WorkSpaces that are controlled by your domain's Group Policy settings.

**To set the automatic session resume timeout value**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Configure Session Automatic Reconnection Policy** setting.

1. In the **Configure Session Automatic Reconnection Policy** dialog box, choose **Enabled**, set the **Configure Session Automatic Reconnection Policy** option to the desired timeout, in minutes, and choose **OK**. 

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure audio-in redirection for PCoIP
<a name="gp_audio"></a>

By default, Amazon WorkSpaces supports redirecting data from a local microphone. If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature.

**Note**  
If you have a Group Policy setting that restricts users' local logon in their WorkSpaces, audio-in won't work on your WorkSpaces. If you remove that Group Policy setting, the audio-in feature is enabled after the next reboot of the WorkSpace. For more information about this Group Policy setting, see [ Allow logon locally](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/allow-log-on-locally) in the Microsoft documentation.

**To enable or disable audio-in redirection**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Enable/disable audio in the PCoIP session** setting.

1. In the **Enable/disable audio in the PCoIP session** dialog box, choose **Enabled** or **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Disable time zone redirection for PCoIP
<a name="gp_time_zone"></a>

By default, the time within a Workspace is set to mirror the time zone of the client that is being used to connect to the WorkSpace. This behavior is controlled through time zone redirection. You might want to turn off time zone direction for various reasons: 
+ Your company wants all employees to work in a certain time zone (even if some employees are in other time zones).
+ You have scheduled tasks in a WorkSpace that are meant to run at a certain time in a specific time zone.
+ Your users who travel a lot want to keep their WorkSpaces in one time zone for consistency and personal preference.

If needed for Windows WorkSpaces, you can use Group Policy settings to disable this feature.

**To disable time zone redirection**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Configure timezone redirection** setting.

1. In the **Configure timezone redirection** dialog box, choose **Disabled**.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

1. Set the time zone for the WorkSpaces to the desired time zone.

The time zone of the WorkSpaces is now static and no longer mirrors the time zone of the client machines. 

### Configure PCoIP security settings
<a name="gp_security"></a>

For PCoIP, data in transit is encrypted using TLS 1.2 encryption and SigV4 request signing. The PCoIP protocol uses encrypted UDP traffic, with AES encryption, for streaming pixels. The streaming connection, using port 4172 (TCP and UDP), is encrypted by using AES-128 and AES-256 ciphers, but the encryption defaults to 128-bit. You can change this default to 256-bit by using the **Configure PCoIP Security Settings** Group Policy setting.

You can also use this Group Policy setting to modify the TLS Security Mode and to block certain cipher suites. A detailed explanation of these settings and the supported cipher suites is provided in the **Configure PCoIP Security Settings** Group Policy dialog box. 

**To configure PCoIP security settings**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Configure PCoIP Security Settings** setting.

1. In the **Configure PCoIP Security Settings** dialog box, choose **Enabled**. To set the default encryption for streaming traffic to 256-bit, go to the **PCoIP Data Encryption Ciphers** option, and select **AES-256-GCM only**.

1. (Optional) Adjust the **TLS Security Mode** setting, and then list any cipher suites that you want to block. For more information about these settings, see the descriptions provided in the **Configure PCoIP Security Settings** dialog box.

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

### Configure USB redirection for PCoIP
<a name="gp_usbredirection"></a>

**Note**  
Amazon WorkSpaces currently supports USB redirection only for YubiKey U2F. Other types of USB devices might be redirected but they are not supported and might not work properly. 

**To enable USB redirection for PCoIP**

1. Make sure that you've installed the most recent [WorkSpaces Group Policy administrative template for PCoIP (32-Bit)](#gp_install_template_pcoip_32_bit) or [WorkSpaces Group Policy administrative template for PCoIP (64-Bit)](#gp_install_template_pcoip_64_bit).

1. On a directory administration WorkSpace or an Amazon EC2 instance that is joined to your WorkSpaces directory, open the Group Policy Management tool (**gpmc.msc**) and navigate to **PCoIP Session Variables**.

1. Open the **Enable/disable USB in the PCOIP session** setting.

1.  Choose **Enabled**, and then choose **OK**. 

1. Open the **Configure PCoIP USB allowed and unallowed device rules** setting.

1. Choose **Enabled**, and under **Enter the USB authorization table (maximum ten rules)**, configure your USB device allow list rules.

   1. Authorization rule - 110500407. This value is a combination of a Vendor ID (VID) and a Product ID (PID). The format for a VID/PID combination is 1xxxxyyyy, where xxxx is the VID in hexadecimal format and yyyy is the PID in hexadecimal format. For this example, 1050 is the VID, and 0407 is the PID. For more YubiKey USB values, see [YubiKey USB ID Values](https://support.yubico.com/hc/en-us/articles/360016614920-YubiKey-USB-ID-Values).

1. Under **Enter the USB authorization table (maximum ten rules)**, configure your USB device block list rules. 

   1. For **Unauthorization Rule**, set an empty string. This means that only USB devices in the authorization list are allowed.
**Note**  
You can define a maximum of 10 USB authorization rules and a maximum of 10 USB unauthorization rules. Use the vertical bar (\$1) character to separate multiple rules. For detailed information about the authorization/unauthorization rules, see [Teradici PCoIP Standard Agent for Windows](https://www.teradici.com/web-help/pcoip_agent/standard_agent/windows/20.10/admin-guide/configuring/configuring/#pcoip-usb-allowed-and-unallowed-device-rules). 

1. Choose **OK**.

1. The Group Policy setting change takes effect after the next Group Policy update for the WorkSpace and after the WorkSpace session is restarted. To apply the Group Policy changes, do one of the following:
   + Reboot the WorkSpace (in the Amazon WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + In an administrative command prompt, enter **gpupdate /force**.

After the setting takes effect, all supported USB devices can redirect to WorkSpaces unless restrictions are configured through the USB device rules setting.

## Set the maximum lifetime for a Kerberos ticket
<a name="gp_kerberos_ticket"></a>

If you have not disabled the **Remember Me** feature of your Windows WorkSpaces, your WorkSpace users can use the **Remember Me** or **Keep me logged in** check box in their WorkSpaces client application to save their credentials. This feature allows users to easily connect to their WorkSpaces while the client application remains running. Their credentials are securely cached up to the maximum lifetime of their Kerberos tickets.

If your WorkSpace uses an AD Connector directory, you can modify the maximum lifetime of the Kerberos tickets for your WorkSpaces users through Group Policy by following the steps in [ Maximum Lifetime for a User Ticket](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/maximum-lifetime-for-user-ticket) in the Microsoft Windows documentation.

To enable or disable the **Remember Me** feature, see [Enable self-service WorkSpaces management capabilities for your users in WorkSpaces Personal](enable-user-self-service-workspace-management.md).

## Configure device proxy server settings for internet access
<a name="gp_device_proxy"></a>

By default, the WorkSpaces client applications use the proxy server that’s specified in the device operating system settings for HTTPS (port 443) traffic. The Amazon WorkSpaces client applications use the HTTPS port for updates, registration, and authentication. 

**Note**  
Proxy servers that require authentication with sign-in credentials are not supported.

You can configure the device proxy server settings for your Windows WorkSpaces through Group Policy by following the steps in [ Configure device proxy and internet connectivity settings](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/configure-proxy-internet) in the Microsoft documentation.

For more information about configuring the proxy settings in the WorkSpaces Windows client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-windows-client.html#windows_proxy_server) in the *Amazon WorkSpaces User Guide*. 

For more information about configuring the proxy settings in the WorkSpaces macOS client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-osx-client.html#osx_proxy_server) in the *Amazon WorkSpaces User Guide*.

For more information about configuring the proxy settings in the WorkSpaces Web Access client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-web-access.html#web-access-proxy) in the *Amazon WorkSpaces User Guide*.

### Proxying desktop traffic
<a name="w2aac11c31c11c27c15"></a>

For PCoIP WorkSpaces, the desktop client applications do not support the use of a proxy server nor TLS decryption and inspection for port 4172 traffic in UDP (for desktop traffic). They require a direct connection to ports 4172. 

For DCV WorkSpaces, the WorkSpaces Windows client application (version 5.1 and above) and macOS client application (version 5.4 and above) support the use of HTTP proxy servers for port 4195 TCP traffic. TLS decryption and inspection are not supported.

DCV does not support the use of proxy for desktop traffic over UDP. Only WorkSpaces Windows and macOS desktop client applications and web access support the use of proxy, for TCP traffic. 

**Note**  
If you choose to use a proxy server, the API calls that the client application makes to the WorkSpaces services are also proxied. Both API calls and desktop traffic should pass through the same proxy server. 

### Recommendation on the use of proxy servers
<a name="w2aac11c31c11c27c17"></a>

We do not recommend the use of a proxy server with your WorkSpaces desktop traffic.

Amazon WorkSpaces desktop traffic is already encrypted, so proxies do not improve security. A proxy represents an additional hop in the network path that could impact streaming quality by introducing latency. Proxies could also potentially reduce throughput if a proxy is not properly sized to handle desktop streaming traffic. Furthermore, most proxies are not designed for supporting long running WebSocket (TCP) connections and may affect streaming quality and stability. 

If you must use a proxy, please locate your proxy server as close to the WorkSpace client as possible, preferably in the same network, to avoid adding network latency, which could negatively impact streaming quality and responsiveness.

## Enable Amazon WorkSpaces for Zoom Meeting Media Plugin support
<a name="zoom-integration"></a>

Zoom supports optimized real-time communication for DCV and PCoIP Windows-based WorkSpaces, with the Zoom VDI Plugin. Direct client communication allows video calls to bypass the cloud-based virtual desktop and provide a local-like Zoom experience when the meeting is running inside the your user’s WorkSpace.

### Enable Zoom Meeting Media Plugin for DCV
<a name="zoom-wsp"></a>

Before installing the Zoom VDI components, update your WorkSpaces configuration to support Zoom optimization.

#### Prerequisites
<a name="zoom-integ-prerequisites-wsp"></a>

Before using the plugin, make sure the following requirements are met.
+ Windows WorkSpaces client version 5.10.0\$1 with [ Zoom VDI Plugin](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0066757#h_01H6PE29K2S6NPYCC3SWB667AT:~:text=Zoom%20Meeting%20client.-,Install%20the%20Zoom%20VDI%20plugin,-To%20complete%20your) version 5.17.10\$1
+ Within your WorkSpaces — [ Zoom VDI Meeting](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0063810) client version 5.17.10\$1

#### Before you begin
<a name="zoom-begin-wsp"></a>

1. Enable the **Extensions** Group Policy setting. For more information, see [Configure extensions for DCV](#extensions).

1. Disable the **Automatic reconnect** Group Policy setting. For more information, see [Set the session resume timeout for DCV](#gp_auto_resume_wsp).

#### Installing the Zoom components
<a name="installing-zoom-wsp"></a>

To enable Zoom optimization, install two components, provided by Zoom, on your Windows WorkSpaces. For more information, see[ Using Zoom for Amazon Web Services](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0066757#h_01H6PE29K2S6NPYCC3SWB667AT).

1. Install the Zoom VDI Meeting client version 5.12.6\$1 within your WorkSpace.

1. Install the Zoom VDI Plugin (Windows Universal Installer) version 5.12.6\$1 on the client where your WorkSpace is installed

1. Validate the plugin is optimizing the Zoom traffic, by confirming that your VDI Plugin Status shows as **Connected** within the Zoom VDI client. For more information, see [ How to confirm Amazon WorkSpaces optimization ](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0066757#h_01H6PE1MA5YMYFX5B5XM873V1Y).

### Enable Zoom Meeting Media Plugin for PCoIP
<a name="zoom-pcoip"></a>

Users with administrative permission to Active Directory can generate a registry key using their Group Policy Object (GPO). This allows users to send the registry key to all the Windows WorkSpaces within your domain using a forced update. Alternatively, users with administrative rights can also install registry keys individually on their WorkSpaces host.

#### Prerequisites
<a name="zoom-integ-prerequisites-pcoip"></a>

Before using the plugin, make sure the following requirements are met.
+ Windows WorkSpaces client version 5.4.0\$1 with [ Zoom VDI Plugin](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0066757#h_01H6PE29K2S6NPYCC3SWB667AT:~:text=Zoom%20Meeting%20client.-,Install%20the%20Zoom%20VDI%20plugin,-To%20complete%20your) version 5.12.6\$1.
+ Within your WorkSpaces — [ Zoom VDI Meeting](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0063810) client version 5.12.6\$1.

#### Create the registry key on a Windows WorkSpaces host
<a name="zoom-integ-create-registry-key"></a>

Complete the following procedure to create a registry key on a Windows WorkSpaces host. The registry key is required to use Zoom on Windows WorkSpaces.

1. Open Windows Registry Editor as an administrator.

1. Go to `\HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Amazon`.

1. If the **Extension** key doesn't exist, right-click and choose **New** > **Key** and name it **Extension**.

1. In the new **Extension** key, right-click and choose **New** > **DWORD** and name it **enable**. The name must be in lower-case.

1. Choose the new **DWORD** and change the **Value** to **1**.

1. Reboot the computer to complete the process.

1. On your WorkSpaces host, download and install the latest Zoom VDI client. On your WorkSpaces client (5.4 or higher), download and install the latest Zoom VDI client plugin for Amazon WorkSpaces. For more information, see [VDI releases and downloads](https://support.zoom.us/hc/en-us/articles/4415057249549-VDI-releases-and-downloads) on the *Zoom support website*.

Launch Zoom to start your video call.

#### Troubleshooting
<a name="zoom-integ-troubleshoot"></a>

Complete the following actions to troubleshoot Zoom on Windows WorkSpaces.
+ Confirm that The Registry Key Activation and Applied Correctly.
+ Go to `C:\ProgramData\Amazon\Amazon WorkSpaces Extension`. You should see `wse_core_dll`.
+ Make sure that the versions on the host and clients are correct and the same.

If you continue to experience difficulty, contact Support using the [Support Center](https://console.aws.amazon.com/support/home#/). 

You can use the following examples to apply a GPO as an administrator of your directory.
+ **WSE.adml**

  ```
  <?xml version="1.0" encoding="utf-8"?>
  <policyDefinitionResources xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.0" schemaVersion="1.0" xmlns="http://www.microsoft.com/GroupPolicy/PolicyDefinitions">
      <!-- 'displayName' and 'description' don't appear anywhere. All Windows native GPO template files have them set like this. -->
      <displayName>enter display name here</displayName>
      <description>enter description here</description>
  
      <resources>
      <stringTable>
          <string id="SUPPORTED_ProductOnly">N/A</string>
          <string id="Amazon">Amazon</string>
          <string id="Amazon_Help">Amazon Group Policies</string>
          <string id="WorkspacesExtension">Workspaces Extension</string>
          <string id="WorkspacesExtension_Help">Workspace Extension Group Policies</string>
  
          <!-- Extension Itself -->
          <string id="ToggleExtension">Enable/disable Extension Virtual Channel</string>
          <string id="ToggleExtension_Help">
  Allows two-way Virtual Channel data communication for multiple purposes
  
  By default, Extension is disabled.</string>
  
      </stringTable>
      </resources>
  </policyDefinitionResources>
  ```
+ **WSE.admx**

  ```
  <?xml version="1.0" encoding="utf-8"?>
  <policyDefinitions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.0" schemaVersion="1.0" xmlns="http://www.microsoft.com/GroupPolicy/PolicyDefinitions">
      <policyNamespaces>
          <target prefix="WorkspacesExtension" namespace="Microsoft.Policies.Amazon.WorkspacesExtension" />
      </policyNamespaces>
      <supersededAdm fileName="wse.adm" />
      <resources minRequiredRevision="1.0" />
      <supportedOn>
          <definitions>
              <definition name="SUPPORTED_ProductOnly" displayName="$(string.SUPPORTED_ProductOnly)"/>
          </definitions>
      </supportedOn>
      <categories>
          <category name="Amazon" displayName="$(string.Amazon)" explainText="$(string.Amazon_Help)" />
          <category name="WorkspacesExtension" displayName="$(string.WorkspacesExtension)" explainText="$(string.WorkspacesExtension_Help)">
              <parentCategory ref="Amazon" />
          </category>
      </categories>
  
      <policies>
          <policy name="ToggleExtension" class="Machine" displayName="$(string.ToggleExtension)" explainText="$(string.ToggleExtension_Help)" key="Software\Policies\Amazon\Extension" valueName="enable">
              <parentCategory ref="WorkspacesExtension" />
              <supportedOn ref="SUPPORTED_ProductOnly" />
              <enabledValue>
                  <decimal value="1" />
              </enabledValue>
              <disabledValue>
                  <decimal value="0" />
              </disabledValue>
          </policy>
      </policies>
  </policyDefinitions>
  ```

# Manage your Amazon Linux 2 WorkSpaces in WorkSpaces Personal
<a name="manage_linux_workspace"></a>

For workloads that require RPM Package Manager (RPM), we recommend using [ Red Hat Enterprise Linux](https://docs.aws.amazon.com/workspaces/latest/adminguide/manage_rhel_workspace.html) or [Rocky Linux](https://docs.aws.amazon.com/workspaces/latest/adminguide/manage_rockylinux_workspace.html). Amazon Linux 2 may not provide the latest versions of some applications and libraries, such as Firefox and glibc, that you may need.

Because Linux instances do not adhere to Group Policy, we recommend that you use a configuration management solution to distribute and enforce policy. For example, you can use [Ansible](https://www.ansible.com/).

**Note**  
Local printer redirection is not available for Amazon Linux WorkSpaces.

## Control DCV behavior on Amazon Linux WorkSpaces
<a name="wsp_agent_linux"></a>

The behavior of DCV is controlled by configuration settings in the `wsp.conf` file, which is located in the `/etc/wsp/` directory. To deploy and enforce changes to the policy, use a configuration management solution that supports Amazon Linux. Any changes take effect when the agent starts up.

**Note**  
If you make incorrect or unsupported changes to the `wsp.conf` file, policy changes may not be applied to the newly established connections on your WorkSpace.
Amazon Linux WorkSpaces on DCV bundles currently have the following limitations:  
Currently only available in the AWS GovCloud (US-West) and AWS GovCloud (US-East).
Video-in is not supported. 
Disconnect session on screen lock is not supported.

The following sections describe how to enable or disable certain features.

## Configure clipboard redirection for DCV Amazon Linux WorkSpaces
<a name="wsp_linux_clipboard"></a>

By default, WorkSpaces supports clipboard redirection. Use the DCV configuration file to configure this feature, if needed. This setting takes effect when you disconnect and reconnect the WorkSpace.

**To configure clipboard redirection for DCV Amazon Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. 

   ```
   clipboard = X
   ```

   Where the possible values for *X* are:

   `enabled` — Clipboard redirection is enabled in both directions (default)

   `disabled` — Clipboard redirection is disabled in both directions

   `paste-only` — Clipboard redirection is enabled but only allows you to copy contents from the local client device and paste it to the remote host desktop

   `copy-only` — Clipboard redirection is enabled but only allows you to copy contents from the remote host desktop and paste it to the local client device

## Enable or disable audio-in redirection for DCV Amazon Linux WorkSpaces
<a name="wsp_linux_audio"></a>

By default, WorkSpaces supports audio-in redirection. Use the DCV configuration file to disable this feature, if needed. This setting takes effect when you disconnect and reconnect to the WorkSpace.

**To enable or disable audio-in redirection for DCV Amazon Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the file.

   ```
   audio-in = X
   ```

   Where the possible values for *X* are:

   `enabled` — Audio-in redirection is enabled (default)

   `disabled` — Audio-in redirection is disabled

## Enable or disable time zone redirection for DCV Amazon Linux WorkSpaces
<a name="linux_time_zone_wsp"></a>

By default, the time within a Workspace is set to mirror the time zone of the client that is being used to connect to the WorkSpace. This behavior is controlled through time zone redirection. You might want to turn off time zone direction for reasons such as the following: 
+ Your company wants all employees to work in a certain time zone (even if some employees are in other time zones).
+ You have scheduled tasks in a WorkSpace that are meant to run at a certain time in a specific time zone.
+ Your users who travel a lot want to keep their WorkSpaces in one time zone for consistency and personal preference.

Use the DCV configuration file to configure this feature, if needed. This setting takes effect after you disconnect and reconnect to the WorkSpace.

**To enable or disable time zone redirection for DCV Amazon Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp-agent/wsp.conf
   ```

1. Add the following line to the end of the file.

   ```
   timezone_redirect= X
   ```

   Where the possible values for *X* are:

   **enabled** — Time zone redirection is enabled (default)

   **disabled** — Time zone redirection is disabled

## Control PCoIP Agent behavior on Amazon Linux WorkSpaces
<a name="pcoip_agent_linux"></a>

The behavior of the PCoIP Agent is controlled by configuration settings in the `pcoip-agent.conf` file, which is located in the `/etc/pcoip-agent/` directory. To deploy and enforce changes to the policy, use a configuration management solution that supports Amazon Linux. Any changes take effect when the agent starts up. Restarting the agent ends any open connections and restarts the window manager. To apply any changes, we recommend rebooting the WorkSpace. 

**Note**  
If you make incorrect or unsupported changes to the `pcoip-agent.conf` file, you might cause your WorkSpace to stop working. If your WorkSpace stops working, you might need to either [connect to your WorkSpace using SSH](connect-to-linux-workspaces-with-ssh.md) to roll back the changes, or you might have to [ rebuild the WorkSpace](rebuild-workspace.md).

The following sections describe how to enable or disable certain features. For a full listing of the available settings, run `man pcoip-agent.conf` from the terminal on any Amazon Linux WorkSpace.

## Configure clipboard redirection for PCoIP Amazon Linux WorkSpaces
<a name="linux_clipboard"></a>

By default, WorkSpaces supports clipboard redirection. Use the PCoIP Agent conf to disable this feature, if needed. This setting takes effect when you reboot the WorkSpace.

**To configure clipboard redirection for PCoIP Amazon Linux WorkSpaces**

1. Open the `pcoip-agent.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/pcoip-agent/pcoip-agent.conf
   ```

1. Add the following line to the end of the file.

   ```
   pcoip.server_clipboard_state = X
   ```

   Where the possible values for *X* are:

   0 — Clipboard redirection is disabled in both directions

   1 — Clipboard redirection is enabled in both directions

   2 — Clipboard redirection is enabled client to agent only (allow copy and paste only from local client device to the remote host desktop)

   3 — Clipboard redirection is enabled agent to client only (allow copy and paste only from the remote host desktop to the local client device)

**Note**  
Clipboard redirection is implemented as a virtual channel. If virtual channels are disabled, clipboard redirection doesn't work. To enable virtual channels, see [ PCoIP Virtual Channels](https://www.teradici.com/web-help/pcoip_agent/standard_agent/linux/20.07/admin-guide/configuring/configuring/#pcoip-virtual-channels) in the Teradici documentation.

## Enable or disable audio-in redirection for PCoIP Amazon Linux WorkSpaces
<a name="linux_audio"></a>

By default, WorkSpaces supports audio-in redirection. Use the PCoIP Agent conf to disable this feature, if needed. This setting takes effect when you reboot the WorkSpace.

**To enable or disable audio-in redirection for PCoIP Amazon Linux WorkSpaces**

1. Open the `pcoip-agent.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/pcoip-agent/pcoip-agent.conf
   ```

1. Add the following line to the end of the file.

   ```
   pcoip.enable_audio = X
   ```

   Where the possible values for *X* are:

   0 — Audio-in redirection is disabled

   1 — Audio-in redirection is enabled

## Enable or disable time zone redirection for PCoIP Amazon Linux WorkSpaces
<a name="linux_time_zone"></a>

By default, the time within a Workspace is set to mirror the time zone of the client that is being used to connect to the WorkSpace. This behavior is controlled through time zone redirection. You might want to turn off time zone direction for reasons such as the following: 
+ Your company wants all employees to work in a certain time zone (even if some employees are in other time zones).
+ You have scheduled tasks in a WorkSpace that are meant to run at a certain time in a specific time zone.
+ Your users who travel a lot want to keep their WorkSpaces in one time zone for consistency and personal preference.

If needed for Linux WorkSpaces, you can use the PCoIP Agent conf to disable this feature. This setting takes effect when you reboot the WorkSpace.

**To enable or disable time zone redirection for PCoIP Amazon Linux WorkSpaces**

1. Open the `pcoip-agent.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/pcoip-agent/pcoip-agent.conf
   ```

1. Add the following line to the end of the file.

   ```
   pcoip.enable_timezone_redirect= X
   ```

   Where the possible values for *X* are:

   0 — Time zone redirection is disabled

   1 — Time zone redirection is enabled

## Grant SSH access to Amazon Linux WorkSpaces administrators
<a name="linux_ssh"></a>

By default, only assigned users and accounts in the Domain Admins group can connect to Amazon Linux WorkSpaces by using SSH. 

We recommend that you create a dedicated administrators group for your Amazon Linux WorkSpaces administrators in Active Directory.

**To enable sudo access for members of the Linux\$1Workspaces\$1Admins Active Directory group**

1. Edit the `sudoers` file by using `visudo`, as shown in the following example.

   ```
   [example\username@workspace-id ~]$ sudo visudo
   ```

1. Add the following line.

   ```
   %example.com\\Linux_WorkSpaces_Admins ALL=(ALL) ALL 
   ```

After you create the dedicated administrators group, follow these steps to enable login for members of the group.

**To enable login for members of the Linux\$1WorkSpaces\$1Admins Active Directory group**

1. Edit `/etc/security/access.conf` with elevated rights.

   ```
   [example\username@workspace-id ~]$ sudo vi /etc/security/access.conf
   ```

1. Add the following line.

   ```
   +:(example\Linux_WorkSpaces_Admins):ALL 
   ```

For more information about enabling SSH connections, see [Enable SSH connections for your Linux WorkSpaces in WorkSpaces Personal](connect-to-linux-workspaces-with-ssh.md).

## Override the default shell for Amazon Linux WorkSpaces
<a name="linux_shell"></a>

To override the default shell for Linux WorkSpaces, we recommend that you edit the user's `~/.bashrc` file. For example, to use `Z shell` instead of `Bash` shell, add the following lines to `/home/username/.bashrc`.

```
export SHELL=$(which zsh)
[ -n "$SSH_TTY" ] && exec $SHELL
```

**Note**  
After making this change, you must either reboot the WorkSpace or log out of the WorkSpace (not just disconnect) and then log back in for the change to take effect.

## Protect custom repositories from unauthorized access
<a name="password_protect_repos"></a>

To control access to your custom repositories, we recommend using the security features built into Amazon Virtual Private Cloud (Amazon VPC) rather than using passwords. For example, use network access control lists (ACLs) and security groups. For more information about these features, see [Security](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Security.html) in the *Amazon VPC User Guide*.

If you must use passwords to protect your repositories, be sure to create your `yum` repository definition files as shown in [Repository Definition Files](https://docs.fedoraproject.org/en-US/Fedora_Core/3/html/Software_Management_Guide/sn-writing-repodefs.html) in the Fedora documentation.

## Use the Amazon Linux Extras Library repository
<a name="linux_extras"></a>

With Amazon Linux, you can use the Extras Library to install application and software updates on your instances. For information about using the Extras Library, see [Extras Library (Amazon Linux)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-linux-ami-basics.html#extras-library) in the *Amazon EC2 User Guide for Linux Instances*.

**Note**  
If you are using the Amazon Linux repository, your Amazon Linux WorkSpaces must have internet access, or you must configure virtual private cloud (VPC) endpoints to this repository and to the main Amazon Linux repository. For more information, see [Provide internet access for WorkSpaces Personal](amazon-workspaces-internet-access.md).

## Use smart cards for authentication on Linux WorkSpaces
<a name="linux_smart_cards"></a>

Linux WorkSpaces on DCV bundles allow the use of [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card) and [Personal Identity Verification (PIV)](https://piv.idmanagement.gov/) smart cards for authentication. For more information, see [Use smart cards for authentication in WorkSpaces Personal](smart-cards.md).

## Configure device proxy server settings for internet access
<a name="gp_device_proxy_linux"></a>

By default, the WorkSpaces client applications use the proxy server that’s specified in the device operating system settings for HTTPS (port 443) traffic. The Amazon WorkSpaces client applications use the HTTPS port for updates, registration, and authentication. 

**Note**  
Proxy servers that require authentication with sign-in credentials are not supported.

You can configure the device proxy server settings for your Linux WorkSpaces through Group Policy by following the steps in [ Configure device proxy and internet connectivity settings](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/configure-proxy-internet) in the Microsoft documentation.

For more information about configuring the proxy settings in the WorkSpaces Windows client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-windows-client.html#windows_proxy_server) in the *Amazon WorkSpaces User Guide*. 

For more information about configuring the proxy settings in the WorkSpaces macOS client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-osx-client.html#osx_proxy_server) in the *Amazon WorkSpaces User Guide*.

For more information about configuring the proxy settings in the WorkSpaces Web Access client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-web-access.html#web-access-proxy) in the *Amazon WorkSpaces User Guide*.

### Proxying desktop traffic
<a name="w2aac11c31c13c35c15"></a>

For PCoIP WorkSpaces, the desktop client applications do not support the use of a proxy server nor TLS decryption and inspection for port 4172 traffic in UDP (for desktop traffic). They require a direct connection to ports 4172. 

For DCV WorkSpaces, the WorkSpaces Windows client application (version 5.1 and above) and macOS client application (version 5.4 and above) support the use of HTTP proxy servers for port 4195 TCP traffic. TLS decryption and inspection are not supported.

DCV does not support the use of proxy for desktop traffic over UDP. Only WorkSpaces Windows and macOS desktop client applications and web access support the use of proxy, for TCP traffic. 

**Note**  
If you choose to use a proxy server, the API calls that the client application makes to the WorkSpaces services are also proxied. Both API calls and desktop traffic should pass through the same proxy server. 

### Recommendation on the use of proxy servers
<a name="w2aac11c31c13c35c17"></a>

We do not recommend the use of a proxy server with your WorkSpaces desktop traffic.

Amazon WorkSpaces desktop traffic is already encrypted, so proxies do not improve security. A proxy represents an additional hop in the network path that could impact streaming quality by introducing latency. Proxies could also potentially reduce throughput if a proxy is not properly sized to handle desktop streaming traffic. Furthermore, most proxies are not designed for supporting long running WebSocket (TCP) connections and may affect streaming quality and stability. 

If you must use a proxy, please locate your proxy server as close to the WorkSpace client as possible, preferably in the same network, to avoid adding network latency, which could negatively impact streaming quality and responsiveness.

# Manage your Ubuntu WorkSpaces in WorkSpaces Personal
<a name="manage_ubuntu_workspace"></a>

Your Ubuntu WorkSpaces bundle includes a subscription of Ubuntu Pro from Canonical. As with Windows and Amazon Linux WorkSpaces, Ubuntu WorkSpaces are domain joined, so you can use Active Directory Users and Groups to:
+ Administer your Ubuntu WorkSpaces
+ Provide access to those WorkSpaces for users

You can manage Ubuntu WorkSpaces with Group Policy by using ADsys. See the [Ubuntu Active Directory integration FAQ](https://ubuntu.com/blog/new-active-directory-integration-features-in-ubuntu-22-04-faq) for more information. You can also use other configuration and management solutions, such as [Landscape](https://ubuntu.com/landscape) and [Ansible](https://www.ansible.com/). 

## Control DCV behavior on Ubuntu WorkSpaces
<a name="wsp_ubuntu"></a>

The behavior of DCV is controlled by configuration settings in the `wsp.conf` file, which is located in the `/etc/wsp/` directory. To deploy and enforce changes to the policy, use a configuration management solution that supports Ubuntu. Any changes take effect when the agent starts up.

**Note**  
If you make incorrect or unsupported changes to the `wsp.conf` policies may not be applied to the new established connections to your WorkSpace.

The following sections describe how to enable or disable certain features.

## Enable or disable clipboard redirection for Ubuntu WorkSpaces
<a name="ubuntu_clipboard"></a>

By default, WorkSpaces supports clipboard redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable clipboard redirection for Ubuntu WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   clipboard = X
   ```

   Where the possible values for *X* are:

   **enabled** — Clipboard redirection is enabled in both directions (default)

   **disabled** — Clipboard redirection is disabled in both directions

   **paste-only** — Clipboard redirection is enabled and only allows you to copy contents from the local client device and paste it to the remote host desktop

   **copy-only** — Clipboard redirection is enabled and only allows you to copy contents from the remote host desktop and paste it to the local client device

## Enable or disable audio-in redirection for Ubuntu WorkSpaces
<a name="ubuntu_audio"></a>

By default, WorkSpaces supports audio-in redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable audio-in redirection for Ubuntu WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   audio-in = X
   ```

   Where the possible values for *X* are:

   **enabled** — Audio-in redirection is enabled (default)

   **disabled** — Audio-in redirection is disabled

## Enable or disable video-in redirection for Ubuntu WorkSpaces
<a name="ubuntu_video"></a>

By default, WorkSpaces supports video-in redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable video-in redirection for Ubuntu WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   video-in = X
   ```

   Where the possible values for *X* are:

   **enabled** — Video-in redirection is enabled (default)

   **disabled** — Video-in redirection is disabled

## Enable or disable time zone redirection for Ubuntu WorkSpaces
<a name="ubuntu-time-zone"></a>

By default, the time within a Workspace is set to mirror the time zone of the client that is being used to connect to the WorkSpace. This behavior is controlled through time zone redirection. You might want to turn off time zone direction for reasons such as the following:
+ Your company wants all employees to work in a certain time zone (even if some employees are in other time zones).
+ You have scheduled tasks in a WorkSpace that are meant to run at a certain time in a specific time zone.
+ Your users travel a lot and want to keep their WorkSpaces in one time zone for consistency and personal preference.

Use the DCV configuration file to configure this feature, if needed.

**To enable or disable time zone redirection for Ubuntu WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   timezone-redirection = X
   ```

   Where the possible values for *X* are:

   **enabled** — Time zone redirection is enabled (default)

   **disabled** — Time zone redirection is disabled

## Enable or disable printer redirection for Ubuntu WorkSpaces
<a name="ubuntu_printer"></a>

By default, WorkSpaces supports printer redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable printer redirection for Ubuntu WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   remote-printing = X
   ```

   Where the possible values for *X* are:

   **enabled** — Printer redirection is enabled (default)

   **disabled** — Printer redirection is disabled

## Enable or disable disconnect session on screen lock for DCV
<a name="ubuntu_screenlock"></a>

Enable disconnect session on screen lock to allow your users to end their WorkSpaces session when the lock screen is detected. To reconnect from the WorkSpaces client, users can use their passwords or their smart cards to authenticate themselves, depending on which type of authentication has been enabled for their WorkSpaces.

By default, WorkSpaces doesn’t support disconnecting session on screen lock. Use the DCV configuration file to enable this feature, if needed.

**To enable or disable disconnect session on screen lock for Ubuntu WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   disconnect-on-lock = X
   ```

   Where the possible values for *X* are:

   **enabled** — Disconnect on screen lock is enabled

   **disabled** — Disconnect on screen lock is disabled (default)

## Grant SSH access to Ubuntu WorkSpaces administrators
<a name="grant_ssh_access_ubuntu"></a>

By default, only assigned users and accounts in the Domain Admins group can connect to Ubuntu WorkSpaces by using SSH. To enable other users and accounts to connect to Ubuntu WorkSpaces using SSH, we recommend that you create a dedicated administrators group for your Ubuntu WorkSpaces administrators in Active Directory.

**To enable sudo access for members of the `Linux_WorkSpaces_Admins` Active Directory group**

1. Edit the `sudoers` file by using `visudo`, as shown in the following example.

   ```
   [username@workspace-id ~]$ sudo visudo
   ```

1. Add the following line.

   ```
   %Linux_WorkSpaces_Admins ALL=(ALL) ALL
   ```

After you create the dedicated administrators group, follow these steps to enable login for members of the group.

**To enable login for members of the `Linux_WorkSpaces_Admins` Active Directory group**

1. Edit /`etc/security/access.conf` with elevated rights.

   ```
   [username@workspace-id ~]$ sudo vi /etc/security/access.conf
   ```

1. Add the following line.

   ```
   +:(Linux_WorkSpaces_Admins):ALL
   ```

 With Ubuntu WorkSpaces you do not need to add a domain name when specifying username for SSH connection, and by default, password authentication is disabled. To connect via SSH, you needs to either add your SSH public key to `$HOME/.ssh/authorized_keys` on your Ubuntu WorkSpace, or edit `/etc/ssh/sshd_config` to set PasswordAuthentication to `yes`. For more information about enabling SSH connections, see [ Enable SSH connections for your Linux WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/connect-to-linux-workspaces-with-ssh.html). 

## Override the default shell for Ubuntu WorkSpaces
<a name="override_default_shell_ubuntu"></a>

To override the default shell for Ubuntu WorkSpaces, we recommend that you edit the user's `~/.bashrc` file. For example, to use `Z shell` instead of `Bash` shell, add the following lines to `/home/username/.bashrc`.

```
export SHELL=$(which zsh)
[ -n "$SSH_TTY" ] && exec $SHELL
```

**Note**  
After making this change, you must either reboot the WorkSpace or log out of the WorkSpace (not just disconnect) and then log back in for the change to take effect.

## Use smart cards for authentication on Ubuntu WorkSpaces
<a name="linux_smart_cards"></a>

Ubuntu WorkSpaces bundles allow the use of [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card) and [Personal Identity Verification (PIV)](https://piv.idmanagement.gov/) smart cards for authentication. For more information, see [Use smart cards for authentication in WorkSpaces Personal](smart-cards.md).

## Configure device proxy server settings for internet access
<a name="gp_device_proxy_ubuntu"></a>

By default, the WorkSpaces client applications use the proxy server that’s specified in the device operating system settings for HTTPS (port 443) traffic. The Amazon WorkSpaces client applications use the HTTPS port for updates, registration, and authentication. 

**Note**  
Proxy servers that require authentication with sign-in credentials are not supported.

You can configure the device proxy server settings for your Ubuntu WorkSpaces through Group Policy by following the steps in [ Configure device proxy and internet connectivity settings](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/configure-proxy-internet) in the Microsoft documentation.

For more information about configuring the proxy settings in the WorkSpaces Windows client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-windows-client.html#windows_proxy_server) in the *Amazon WorkSpaces User Guide*. 

For more information about configuring the proxy settings in the WorkSpaces macOS client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-osx-client.html#osx_proxy_server) in the *Amazon WorkSpaces User Guide*.

For more information about configuring the proxy settings in the WorkSpaces Web Access client application, see [ Proxy Server](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-web-access.html#web-access-proxy) in the *Amazon WorkSpaces User Guide*.

### Proxying desktop traffic
<a name="w2aac11c31c15c29c15"></a>

For PCoIP WorkSpaces, the desktop client applications do not support the use of a proxy server nor TLS decryption and inspection for port 4172 traffic in UDP (for desktop traffic). They require a direct connection to ports 4172. 

For DCV WorkSpaces, the WorkSpaces Windows client application (version 5.1 and above) and macOS client application (version 5.4 and above) support the use of HTTP proxy servers for port 4195 TCP traffic. TLS decryption and inspection are not supported.

DCV does not support the use of proxy for desktop traffic over UDP. Only WorkSpaces Windows and macOS desktop client applications and web access support the use of proxy, for TCP traffic. 

**Note**  
If you choose to use a proxy server, the API calls that the client application makes to the WorkSpaces services are also proxied. Both API calls and desktop traffic should pass through the same proxy server. 

### Recommendation on the use of proxy servers
<a name="w2aac11c31c15c29c17"></a>

We do not recommend the use of a proxy server with your WorkSpaces desktop traffic.

Amazon WorkSpaces desktop traffic is already encrypted, so proxies do not improve security. A proxy represents an additional hop in the network path that could impact streaming quality by introducing latency. Proxies could also potentially reduce throughput if a proxy is not properly sized to handle desktop streaming traffic. Furthermore, most proxies are not designed for supporting long running WebSocket (TCP) connections and may affect streaming quality and stability. 

If you must use a proxy, please locate your proxy server as close to the WorkSpace client as possible, preferably in the same network, to avoid adding network latency, which could negatively impact streaming quality and responsiveness.

# Manage your Rocky Linux WorkSpaces
<a name="manage_rockylinux_workspace"></a>

You can manage Rocky Linux WorkSpaces with configuration and management solutions, such as [Ansible](https://www.ansible.com/). 

**Note**  
You may not remove, modify, or obscure any copyright, trademark, or other proprietary or confidentiality notices that are contained in or on the Rocky Linux software. 

## Control DCV behavior on Rocky Linux WorkSpaces
<a name="wsp_rockylinux"></a>

The behavior of DCV is controlled by configuration settings in the `wsp.conf` file, which is located in the `/etc/wsp/` directory. To deploy and enforce changes to the policy, use a configuration management solution that supports Rocky Linux. Any changes take effect when the agent starts up.

**Note**  
If you make incorrect or unsupported changes to the `wsp.conf` policies may not be applied to the new established connections to your WorkSpace.

The following sections describe how to enable or disable certain features.

## Enable or disable clipboard redirection for Rocky Linux WorkSpaces
<a name="rockylinux_clipboard"></a>

By default, WorkSpaces supports clipboard redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable clipboard redirection for Rocky Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   clipboard = X
   ```

   Where the possible values for *X* are:

   **enabled** — Clipboard redirection is enabled in both directions (default)

   **disabled** — Clipboard redirection is disabled in both directions

   **paste-only** — Clipboard redirection is enabled and only allows you to copy contents from the local client device and paste it to the remote host desktop

   **copy-only** — Clipboard redirection is enabled and only allows you to copy contents from the remote host desktop and paste it to the local client device

## Enable or disable audio-in redirection for Rocky Linux WorkSpaces
<a name="rockylinux_audio"></a>

By default, WorkSpaces supports audio-in redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable audio-in redirection for Rocky Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   audio-in = X
   ```

   Where the possible values for *X* are:

   **enabled** — Audio-in redirection is enabled (default)

   **disabled** — Audio-in redirection is disabled

## Enable or disable video-in redirection for Rocky Linux WorkSpaces
<a name="rockylinux_video"></a>

By default, WorkSpaces supports video-in redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable video-in redirection for Rocky Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   video-in = X
   ```

   Where the possible values for *X* are:

   **enabled** — Video-in redirection is enabled (default)

   **disabled** — Video-in redirection is disabled

## Enable or disable time zone redirection for Rocky Linux WorkSpaces
<a name="rockylinux-time-zone"></a>

By default, the time within a Workspace is set to mirror the time zone of the client that is being used to connect to the WorkSpace. This behavior is controlled through time zone redirection. You might want to turn off time zone direction for reasons such as the following:
+ Your company wants all employees to work in a certain time zone (even if some employees are in other time zones).
+ You have scheduled tasks in a WorkSpace that are meant to run at a certain time in a specific time zone.
+ Your users travel a lot and want to keep their WorkSpaces in one time zone for consistency and personal preference.

Use the DCV configuration file to configure this feature, if needed.

**To enable or disable time zone redirection for Rocky Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   timezone-redirection = X
   ```

   Where the possible values for *X* are:

   **enabled** — Time zone redirection is enabled (default)

   **disabled** — Time zone redirection is disabled

## Enable or disable printer redirection for Rocky Linux WorkSpaces
<a name="rockylinux_printer"></a>

By default, WorkSpaces supports printer redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable printer redirection for Rocky Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   remote-printing = X
   ```

   Where the possible values for *X* are:

   **enabled** — Printer redirection is enabled (default)

   **disabled** — Printer redirection is disabled

## Enable or disable disconnect session on screen lock for DCV
<a name="rockylinux_screenlock"></a>

Enable disconnect session on screen lock to allow your users to end their WorkSpaces session when the lock screen is detected. To reconnect from the WorkSpaces client, users can use their passwords or their smart cards to authenticate themselves, depending on which type of authentication has been enabled for their WorkSpaces.

By default, WorkSpaces doesn’t support disconnecting session on screen lock. Use the DCV configuration file to enable this feature, if needed.

**To enable or disable disconnect session on screen lock for Rocky Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   disconnect-on-lock = X
   ```

   Where the possible values for *X* are:

   **enabled** — Disconnect on screen lock is enabled

   **disabled** — Disconnect on screen lock is disabled (default)

## Grant SSH access to Rocky Linux WorkSpaces administrators
<a name="grant_ssh_access_rockylinux"></a>

By default, only assigned users and accounts in the Domain Admins group can connect to Rocky Linux WorkSpaces by using SSH. To enable other users and accounts to connect to Rocky Linux WorkSpaces using SSH, we recommend that you create a dedicated administrators group for your Rocky Linux WorkSpaces administrators in Active Directory.

**To enable sudo access for members of the `Linux_WorkSpaces_Admins` Active Directory group**

1. Edit the `sudoers` file by using `visudo`, as shown in the following example.

   ```
   [username@workspace-id ~]$ sudo visudo
   ```

1. Add the following line.

   ```
   %Linux_WorkSpaces_Admins ALL=(ALL) ALL
   ```

After you create the dedicated administrators group, follow these steps to enable login for members of the group.

**To enable login for members of the `Linux_WorkSpaces_Admins` Active Directory group**

1. Edit /`etc/security/access.conf` with elevated rights.

   ```
   [username@workspace-id ~]$ sudo vi /etc/security/access.conf
   ```

1. Add the following line.

   ```
   +:(Linux_WorkSpaces_Admins):ALL
   ```

 With Rocky Linux WorkSpaces you do not need to add a domain name when specifying username for SSH connection, and by default, password authentication is disabled. To connect via SSH, you needs to either add your SSH public key to `$HOME/.ssh/authorized_keys` on your Rocky Linux WorkSpace, or edit `/etc/ssh/sshd_config` to set PasswordAuthentication to `yes`. For more information about enabling SSH connections, see [ Enable SSH connections for your Linux WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/connect-to-linux-workspaces-with-ssh.html). 

## Override the default shell for Rocky Linux WorkSpaces
<a name="override_default_shell_rockylinux"></a>

To override the default shell for Rocky Linux WorkSpaces, we recommend that you edit the user's `~/.bashrc` file. For example, to use `Z shell` instead of `Bash` shell, add the following lines to `/home/username/.bashrc`.

```
export SHELL=$(which zsh)
[ -n "$SSH_TTY" ] && exec $SHELL
```

**Note**  
After making this change, you must either reboot the WorkSpace or log out of the WorkSpace (not just disconnect) and then log back in for the change to take effect.

## Use smart cards for authentication on Rocky Linux WorkSpaces
<a name="linux_smart_cards"></a>

Rocky Linux WorkSpaces bundles allow the use of [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card) and [Personal Identity Verification (PIV)](https://piv.idmanagement.gov/) smart cards for authentication. For more information, see [Use smart cards for authentication in WorkSpaces Personal](smart-cards.md).

# Manage your Red Hat Enterprise Linux WorkSpaces
<a name="manage_rhel_workspace"></a>

You can manage Red Hat Enterprise Linux WorkSpaces with configuration and management solutions, such as [Ansible](https://www.ansible.com/). 

## Control DCV behavior on Red Hat Enterprise Linux WorkSpaces
<a name="wsp_rhel"></a>

The behavior of DCV is controlled by configuration settings in the `wsp.conf` file, which is located in the `/etc/wsp/` directory. To deploy and enforce changes to the policy, use a configuration management solution that supports Red Hat Enterprise Linux. Any changes take effect when the agent starts up.

**Note**  
If you make incorrect or unsupported changes to the `wsp.conf` policies may not be applied to the new established connections to your WorkSpace.

The following sections describe how to enable or disable certain features.

## Enable or disable clipboard redirection for Red Hat Enterprise Linux WorkSpaces
<a name="rhel_clipboard"></a>

By default, WorkSpaces supports clipboard redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable clipboard redirection for Red Hat Enterprise Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   clipboard = X
   ```

   Where the possible values for *X* are:

   **enabled** — Clipboard redirection is enabled in both directions (default)

   **disabled** — Clipboard redirection is disabled in both directions

   **paste-only** — Clipboard redirection is enabled and only allows you to copy contents from the local client device and paste it to the remote host desktop

   **copy-only** — Clipboard redirection is enabled and only allows you to copy contents from the remote host desktop and paste it to the local client device

## Enable or disable audio-in redirection for Red Hat Enterprise Linux WorkSpaces
<a name="rhel_audio"></a>

By default, WorkSpaces supports audio-in redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable audio-in redirection for Red Hat Enterprise Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   audio-in = X
   ```

   Where the possible values for *X* are:

   **enabled** — Audio-in redirection is enabled (default)

   **disabled** — Audio-in redirection is disabled

## Enable or disable video-in redirection for Red Hat Enterprise Linux WorkSpaces
<a name="rhel_video"></a>

By default, WorkSpaces supports video-in redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable video-in redirection for Red Hat Enterprise Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   video-in = X
   ```

   Where the possible values for *X* are:

   **enabled** — Video-in redirection is enabled (default)

   **disabled** — Video-in redirection is disabled

## Enable or disable time zone redirection for Red Hat Enterprise Linux WorkSpaces
<a name="rhel-time-zone"></a>

By default, the time within a Workspace is set to mirror the time zone of the client that is being used to connect to the WorkSpace. This behavior is controlled through time zone redirection. You might want to turn off time zone direction for reasons such as the following:
+ Your company wants all employees to work in a certain time zone (even if some employees are in other time zones).
+ You have scheduled tasks in a WorkSpace that are meant to run at a certain time in a specific time zone.
+ Your users travel a lot and want to keep their WorkSpaces in one time zone for consistency and personal preference.

Use the DCV configuration file to configure this feature, if needed.

**To enable or disable time zone redirection for Red Hat Enterprise Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   timezone-redirection = X
   ```

   Where the possible values for *X* are:

   **enabled** — Time zone redirection is enabled (default)

   **disabled** — Time zone redirection is disabled

## Enable or disable printer redirection for Red Hat Enterprise Linux WorkSpaces
<a name="rhel_printer"></a>

By default, WorkSpaces supports printer redirection. Use the DCV configuration file to disable this feature, if needed.

**To enable or disable printer redirection for Red Hat Enterprise Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   remote-printing = X
   ```

   Where the possible values for *X* are:

   **enabled** — Printer redirection is enabled (default)

   **disabled** — Printer redirection is disabled

## Enable or disable disconnect session on screen lock for DCV
<a name="rhel_screenlock"></a>

Enable disconnect session on screen lock to allow your users to end their WorkSpaces session when the lock screen is detected. To reconnect from the WorkSpaces client, users can use their passwords or their smart cards to authenticate themselves, depending on which type of authentication has been enabled for their WorkSpaces.

By default, WorkSpaces doesn’t support disconnecting session on screen lock. Use the DCV configuration file to enable this feature, if needed.

**To enable or disable disconnect session on screen lock for Red Hat Enterprise Linux WorkSpaces**

1. Open the `wsp.conf` file in an editor with elevated rights by using the following command.

   ```
   [domain\username@workspace-id ~]$ sudo vi /etc/wsp/wsp.conf
   ```

1. Add the following line to the end of the `[policies]` group.

   ```
   disconnect-on-lock = X
   ```

   Where the possible values for *X* are:

   **enabled** — Disconnect on screen lock is enabled

   **disabled** — Disconnect on screen lock is disabled (default)

## Grant SSH access to Red Hat Enterprise Linux WorkSpaces administrators
<a name="grant_ssh_access_rhel"></a>

By default, only assigned users and accounts in the Domain Admins group can connect to Red Hat Enterprise Linux WorkSpaces by using SSH. To enable other users and accounts to connect to Red Hat Enterprise Linux WorkSpaces using SSH, we recommend that you create a dedicated administrators group for your Red Hat Enterprise Linux WorkSpaces administrators in Active Directory.

**To enable sudo access for members of the `Linux_WorkSpaces_Admins` Active Directory group**

1. Edit the `sudoers` file by using `visudo`, as shown in the following example.

   ```
   [username@workspace-id ~]$ sudo visudo
   ```

1. Add the following line.

   ```
   %Linux_WorkSpaces_Admins ALL=(ALL) ALL
   ```

After you create the dedicated administrators group, follow these steps to enable login for members of the group.

**To enable login for members of the `Linux_WorkSpaces_Admins` Active Directory group**

1. Edit /`etc/security/access.conf` with elevated rights.

   ```
   [username@workspace-id ~]$ sudo vi /etc/security/access.conf
   ```

1. Add the following line.

   ```
   +:(Linux_WorkSpaces_Admins):ALL
   ```

 With Red Hat Enterprise Linux WorkSpaces you do not need to add a domain name when specifying username for SSH connection, and by default, password authentication is disabled. To connect via SSH, you needs to either add your SSH public key to `$HOME/.ssh/authorized_keys` on your Red Hat Enterprise Linux WorkSpace, or edit `/etc/ssh/sshd_config` to set PasswordAuthentication to `yes`. For more information about enabling SSH connections, see [ Enable SSH connections for your Linux WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/connect-to-linux-workspaces-with-ssh.html). 

## Override the default shell for Red Hat Enterprise Linux WorkSpaces
<a name="override_default_shell_rhel"></a>

To override the default shell for Red Hat Enterprise Linux WorkSpaces, we recommend that you edit the user's `~/.bashrc` file. For example, to use `Z shell` instead of `Bash` shell, add the following lines to `/home/username/.bashrc`.

```
export SHELL=$(which zsh)
[ -n "$SSH_TTY" ] && exec $SHELL
```

**Note**  
After making this change, you must either reboot the WorkSpace or log out of the WorkSpace (not just disconnect) and then log back in for the change to take effect.

## Use smart cards for authentication on Red Hat Enterprise Linux WorkSpaces
<a name="linux_smart_cards"></a>

Red Hat Enterprise Linux WorkSpaces bundles allow the use of [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card) and [Personal Identity Verification (PIV)](https://piv.idmanagement.gov/) smart cards for authentication. For more information, see [Use smart cards for authentication in WorkSpaces Personal](smart-cards.md).

# Optimize WorkSpaces for real-time communication in WorkSpaces Personal
<a name="communication-optimization"></a>

Amazon WorkSpaces offers a diverse range of techniques to facilitate the deployment of Unified Communication (UC) applications like Microsoft Teams, Zoom, Webex and others. In contemporary application landscapes, most UC applications consist of a variety of features, including 1:1 chat rooms, collaborative group chat channels, seamless file storage and exchange, live events, webinars, broadcasts, interactive screen sharing and control, whiteboarding, and offline audio/video messaging capabilities. Most of this functionality is seamlessly available on WorkSpaces as standard features, without the need for additional fine-tuning or enhancement. However, it's worth noting that real-time communication elements, particularly one-on-one calling and collective group meetings, represent an exception to this rule. The successful incorporation of such functionality frequently demands dedicated focus and planning during the process of WorkSpaces deployment.

When planning your implementation of real-time communication functionalities of UC applications on Amazon WorkSpaces, you have three distinct Real-Time Communication (RTC) configuration modes to choose from. The selection of which depends on the specific application or applications that you intend to provide to your users and the client devices you plan to use.

This document focus on optimizing the user experience for the most common UC applications in Amazon WorkSpaces. For WorkSpaces Core specific optimizations, please refer to the partner-specific documentation.

**Topics**
+ [Overview of media optimization modes](#media-optimization-modes-overview)
+ [Which RTC optimization mode to use?](#choosing-optimization-mode)
+ [RTC Optimization Guidance](#rtc-optimization-guidance)

## Overview of media optimization modes
<a name="media-optimization-modes-overview"></a>

Following are the media optimization options available.

### Option 1: Media Optimized Real-Time Communication (Media Optimized RTC)
<a name="media-optimized-rtc"></a>

In this mode, third-party UC and VoIP applications are executed on the remote WorkSpace, while their media framework is offloaded to the supported client for direct communication. The following UC applications use this approach on Amazon WorkSpaces:
+ [Zoom meetings](https://support.zoom.us/hc/en-us/articles/10372235268749-Using-Zoom-for-Amazon-WorkSpaces)
+ [Cisco Webex meetings](https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cloudCollaboration/wbxt/vdi/wbx-vdi-deployment-guide.html)
+ [Microsoft Teams 2.0 (Public Preview)](https://learn.microsoft.com/en-us/microsoftteams/vdi-2)

For Media Optimized RTC mode to function, the UC application vendor should develop the integration with WorkSpaces using one of the available Software Development Kits (SDK), such as the [DCV Extension SDK](https://docs.aws.amazon.com/dcv/latest/extsdkguide/what-is.html). This mode requires the UC components to be installed on the client device.

For more information about configuring this mode, see [Configure Media Optimized RTC](#configure-media-optimized-rtc).

### Option 2: In-Session Optimized Real-Time Communication (In-session Optimized RTC)
<a name="in-session-optimized-rtc"></a>

In this mode, the unaltered UC application runs on the WorkSpace, channeling audio and video traffic via the DCV to the client device. Local audio from the microphone and video stream from a webcam are redirected to the WorkSpace, where they are consumed by the UC application. This mode provides broad application compatibility and efficiently delivers the UC application from the remote WorkSpace to a variety of client platforms. You don't need to deploy the UC application components to the client device.

For more information about configuring this mode, see [Configure In-session Optimized RTC](#configure-in-session-optimized-rtc).

### Option 3: Direct Real-Time Communication (Direct RTC)
<a name="direct-rtc"></a>

In this mode, the application operating within the WorkSpace takes control over the physical or virtual telephone set located on the user's desk or client OS. This results in the audio traffic traversing directly from the physical telephone at the user's workstation or the virtual phone operating on the client device to the remote call peer. Notable instances of applications functioning within this mode encompass:
+ [Amazon Connect Optimization for Amazon WorkSpaces](https://docs.aws.amazon.com/whitepapers/latest/best-practices-deploying-amazon-workspaces/connect-optimization.html)
+ [Genesys Cloud WebRTC media helper](https://help.mypurecloud.com/articles/about-webrtc-media-helper/)
+ [Microsoft Teams SIP Gateway](https://learn.microsoft.com/en-us/microsoftteams/sip-gateway-plan)
+ [Microsoft Teams Desk phones and Teams displays](https://www.microsoft.com/en-us/microsoft-teams/across-devices/devices/category/desk-phones-teams-displays/34)
+ Participation in audio conferencing through the dial-in or "dial my phone" features of the UC application.

For more information about configuring this mode, see [Configure Direct RTC](#configure-direct-rtc).

## Which RTC optimization mode to use?
<a name="choosing-optimization-mode"></a>

Different RTC optimization modes can be employed concurrently or set up to complement each other as a fallback. For instance, consider enabling Media Optimized RTC for Cisco Webex meetings. This configuration ensures that users experience optimized communication when accessing WorkSpace through a desktop client. However, in scenarios where Webex is accessed from a shared internet kiosk lacking UC optimization components, Webex will seamlessly transition to In-session Optimized RTC mode to maintain functionality. When users engage with multiple UC applications, the RTC configuration modes may vary based on their unique requirements.

The following table represents common UC application features and defines which RTC configuration mode provides the best result.


| Feature | Direct RTC | Media Optimized RTC | In-session Optimized RTC | 
| --- | --- | --- | --- | 
| **1:1 chat** | Does not require RTC configuration | 
| **Group chat rooms** | Does not require RTC configuration | 
| **Group audio conferencing** | Best | Best | Good | 
| **Group video conferencing** | Good | Best | Good | 
| **1:1 audio calls** | Best | Best | Good | 
| **1:1 video calls** | Good | Best | Good | 
| **Whiteboarding** | Does not require RTC configuration | 
| **Audio/video clips/messaging** | Not applicable | Good | Best | 
| **File Sharing** | Not applicable | Depends on UC application | Best | 
| **Screen sharing and control** | Not applicable | Depends on UC application | Best | 
| **Webinars/Broadcast events** | Not applicable | Good | Best | 

## RTC Optimization Guidance
<a name="rtc-optimization-guidance"></a>

### Configure Media Optimized RTC
<a name="configure-media-optimized-rtc"></a>

Media Optimized RTC mode is made possible by the UC application vendor use of the SDKs provided by Amazon. The architecture requires UC vendor to develop a UC-specific plugin or extension and deploy it to the client.

The SDK, which includes publicly available options like the DCV Extension SDK and customized private versions, establishes a control channel between the UC application module operating within the WorkSpace and a plugin on the client side. Typically, this control channel instructs the client extension to initiate or join a call. Once the call is established through the client-side extension, the UC plugin captures audio from the microphone and video from the webcam, which are then transmitted directly to the UC cloud or a call peer. The incoming audio is played locally, and video is overlaid on the remote client UI. The control channel is responsible for communicating the call's status.

![\[Diagram showing the Media Optimized RTC configuration.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/media-optimized-rtc.png)


Amazon WorkSpaces currently supports following applications with Media Optimized RTC mode:
+ [Zoom meetings](https://support.zoom.us/hc/en-us/articles/10372235268749-Using-Zoom-for-Amazon-WorkSpaces) (for PCoIP and DCV WorkSpaces)
+ [Cisco Webex meetings](https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cloudCollaboration/wbxt/vdi/wbx-vdi-deployment-guide.html) (for DCV WorkSpaces only)
+ [Microsoft Teams 2.0 (Public Preview)](https://learn.microsoft.com/en-us/microsoftteams/vdi-2) (for DCV WorkSpaces only)

If you are using an application that is not on the list, it is advisable to engage the application vendor and request support for WorkSpaces Media Optimized RTC. To expedite this process, encourage them to contact [aws-av-offloading@amazon.com](mailto:aws-av-offloading@amazon.com).

While Media Optimized RTC mode enhances call performance and minimizes WorkSpace resource utilization, it does possess certain limitations:
+ The UC client extension must be installed on the client device.
+ The UC client extension requires independent management and updates.
+ UC client extensions might not be available on certain client platforms, such as, mobile platforms, or web clients.
+ Some UC application functionalities could be constrained in this mode; for instance, screen sharing behavior might differ.
+ Usage of client-side extensions might not be suitable for scenarios like Bring Your Own Device (BYOD) or shared kiosks.

If Media Optimized RTC mode proves unsuitable for your environment or certain users are unable to install the client extension, configuring In-session Optimized RTC mode as a fallback option is recommended.

### Configure In-session Optimized RTC
<a name="configure-in-session-optimized-rtc"></a>

In the In-session Optimized RTC mode, the UC application operates on the WorkSpace without any modifications, providing a like-local experience. The audio and video streams generated by the application are captured by DCV and transmitted to the client side. At the client, the microphone (on both DCV and PCoIP WorkSpaces) and webcam (only on DCV WorkSpaces) signals are captured, redirected back to the WorkSpace, and seamlessly passed to the UC application.

Notably, this option ensures exceptional compatibility, even with legacy applications, offering a cohesive user experience regardless of the application's origin. In-session optimization works with web client as well.

![\[Diagram showing the In-session Optimized RTC configuration.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/in-session-optimized-rtc.png)


DCV has been meticulously optimized to enhance the performance of Remote RTC mode. The optimization measures encompass:
+ Utilization of an Adaptive UDP-based QUIC transport, ensuring efficient data transmission.
+ Establishment of a low-latency audio path, facilitating fast audio input and output.
+ Implementation of voice-optimized audio codecs to maintain audio quality while reducing CPU and network utilization.
+ Webcam redirection, enabling the integration of webcam functionalities.
+ Configuration of webcam resolution to optimize performance.
+ Integration of adaptive display codecs to balance speed and visual quality.
+ Audio jitter correction, guaranteeing smooth audio transmission.

These optimizations collectively contribute to a robust and fluid experience in Remote RTC mode.

#### Sizing recommendations
<a name="sizing-recommendations"></a>

To effectively support Remote RTC mode, it's crucial to ensure proper sizing of Amazon WorkSpaces. The remote WorkSpace must meet or exceed the system requirements of the respective Unified Communication (UC) application. The following table outlines the minimum supported and recommended WorkSpaces configurations for popular UC applications when used for video and audio calls:


|   | Video calls | Audio calls |   | Application | CPU requirements for RTC app | RAM requirements for RTC app | Minimally supported WorkSpace | Recommended WorkSpace | Minimally supported WorkSpace | Recommended WorkSpace | Reference | 
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | 
| Microsoft Teams | 2 core required, 4 core recommended | 4.0 GB RAM | Power (4 vCPU, 16 GB memory) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/communication-optimization.html)  | Performance (2 vCPU, 8 GB memory) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/communication-optimization.html)  | [Hardware requirements for Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/hardware-requirements-for-the-teams-app) | 
| Zoom | 2 core required, 4 core recommended | 4.0 GB RAM | Power (4 vCPU, 16 GB memory) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/communication-optimization.html)  | Performance (2 vCPU, 8 GB memory) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/communication-optimization.html)  | [Zoom system requirements: Windows, macOS, Linux](https://support.zoom.us/hc/en-us/articles/201362023-Zoom-system-requirements-Windows-macOS-Linux) | 
| Webex | 2 core required | 4.0 GB RAM | Power (4 vCPU, 16 GB memory) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/communication-optimization.html)  | Performance (2 vCPU, 8 GB memory) |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/communication-optimization.html)  | [System requirements for Webex services](https://help.webex.com/en-us/article/fz1e4b/System-requirements-for-Webex-services) | 

It's important to note that video conferencing involves significant resource usage for video encoding and decoding. In physical machine scenarios, these tasks are offloaded to the GPU. In non-GPU WorkSpaces, these tasks are performed on the CPU in parallel with remote protocol encoding. Therefore, for users regularly engaged in video streaming or video calls, opting for the PowerPro or higher configuration is highly recommended.

Screen sharing also consumes notable resources, with resource consumption increasing with higher resolutions. As result, on non-GPU WorkSpaces, screen sharing is often limited to a lower frame rate.

#### Leverage the UDP-based QUIC transport with DCV
<a name="leaverage-udp-based-quic-transport"></a>

UDP transport is particularly well-suited for transmitting RTC applications. To maximize efficiency, ensure that your network is set up to utilize QUIC transport for DCV. Note that UDP-based transport is available with native clients only.

#### Configure UC application for WorkSpaces
<a name="configure-uc-application"></a>

For enhanced video processing capabilities, such as background blur, virtual backgrounds, reactions, or hosting live events, opting for a GPU-enabled WorkSpace is essential to achieve optimal performance.

Most of the UC applications provide guidance to disable advanced video processing to reduce CPU utilization on non-GPU WorkSpaces.

For more information, refer to the following resources.
+ Microsoft Teams: [Teams for Virtualized Desktop Infrastructure](https://https://learn.microsoft.com/en-us/microsoftteams/vdi-2)
+ Zoom Meetings: [Managing the user experience for incompatible VDI plugins](https://support.zoom.us/hc/en-us/articles/4411856902285-Managing-the-user-experience-for-incompatible-VDI-plugins-)
+ Webex: [Deployment guide for Webex App for Virtual Desktop Infrastructure (VDI) - Manage and troubleshoot Webex App for VDI [Webex App]](https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cloudCollaboration/wbxt/vdi/wbx-vdi-deployment-guide/manage-teams-vdi.html#id_138538)
+ Google Meet: [Using VDI](https://support.google.com/a/answer/1279090?hl=en#VDI)

#### Enable bi-directional audio and webcam redirection
<a name="enable-bi-directional-audio-webcam-redirection"></a>

Amazon WorkSpaces inherently support audio-in, audio-out, and camera redirection through video-in by default. However, if these features have been disabled for any specific reasons, you can follow the provided guidance to re-enable redirection. For more information, refer to [Enable or disable video-in redirection for DCV](https://docs.aws.amazon.com/workspaces/latest/adminguide/group_policy.html#gp_video_in_wsp) in the *Amazon WorkSpaces Administration Guide*. Users need to select the camera they want to use in session after connecting. For more information, users should refer to [Webcams and other video devices](https://docs.aws.amazon.com/workspaces/latest/userguide/peripheral_devices.html#devices-webcams) in the *Amazon WorkSpaces User Guide*.

#### Limit maximum webcam resolution
<a name="limit-maximum-webcam-resolution"></a>

For users employing Power, PowerPro, GeneralPurpose.4xlarge, or GeneralPurpose.8xlarge WorkSpaces for video conferencing, it is strongly recommended to restrict the maximum resolution of redirected webcams. In the case of PowerPro, GeneralPurpose.4xlarge, or GeneralPurpose.8xlarge, the recommended maximum resolution is 640 pixels in width by 480 pixels in height. For Power, the recommended maximum resolution is 320 pixels in width by 240 pixels in height.

Complete the following steps to configure the maximum webcam resolution.

1. Open the Windows Registry Editor.

1. Navigate to the following registry path:

   ```
   HKEY_USERS/S-1-5-18/Software/GSettings/com/nicesoftware/dcv/webcam
   ```

1. Create a string value named `max-resolution` and set it to the desired resolution in the `(X,Y)` format, where `X` represents the horizontal pixel count (width) and `Y` represents the vertical pixel count (height). For example, specify `(640,480)`) to represent a resolution that is 640 pixels in width and 480 pixel in height.

#### Enable voice-optimized audio configuration
<a name="enable-voice-optimized-audio-configuration"></a>

By default, WorkSpaces are set to deliver 7.1 high-fidelity audio from WorkSpaces to the client, ensuring superior music playback quality. However, if your primary use case involves audio or video conferencing, modifying the audio codec profile to a voice-optimized setting can conserve CPU and network resources.

Complete the following steps to set the audio profile to voice optimized.

1. Open the Windows Registry Editor.

1. Navigate to the following registry path:

   ```
   HKEY_USERS/S-1-5-18/Software/GSettings/com/nicesoftware/dcv/audio
   ```

1. Create a string value name `default-profile` and set it to `voice`.

#### Use good quality headsets for audio and video calls
<a name="use-good-quality-headsets"></a>

To enhance the audio experience and prevent echo, it's crucial to utilize high-quality headsets. Utilizing desktop speakers can lead to echo issues on the remote end of the call.

### Configure Direct RTC
<a name="configure-direct-rtc"></a>

The configuration of Direct RTC mode depends on the specific Unified Communication (UC) application and does not necessitate any changes in the WorkSpaces configuration. The following list offers a non-exhaustive compilation of optimizations for various UC applications.

![\[Diagram showing the Direct RTC configuration.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/direct-rtc.png)

+ Microsoft Teams:
  + [Plan for SIP Gateway](https://learn.microsoft.com/en-us/microsoftteams/sip-gateway-plan)
  + [Audio Conferencing in Microsoft 365](https://learn.microsoft.com/en-us/microsoftteams/audio-conferencing-in-office-365)
  + [Plan your Teams voice solution](https://learn.microsoft.com/en-us/microsoftteams/cloud-voice-landing-page)
+ Zoom Meetings:
  + [Enabling or disabling toll call dial-in numbers](https://support.zoom.us/hc/en-us/articles/360060920371-Enabling-or-disabling-toll-call-dial-in-numbers)
  + [Using desk phone call control](https://support.zoom.us/hc/en-us/articles/4912628206477-Using-desk-phone-call-control)
  + [Desk phone companion mode](https://support.zoom.us/hc/en-us/articles/360049007912-Desk-phone-companion-mode)
+ Webex:
  + [Webex App \$1 Make calls with your desk phone](https://help.webex.com/en-us/article/5mgmmb/Webex-App-%7C-Make-calls-with-your-desk-phone)
  + [Webex App \$1 Supported calling options](https://help.webex.com/en-us/article/xga73p/Webex-App-%7C-Supported-calling-options)
+ BlueJeans:
  + [Dialing into a Meeting from a Desk Telephone](https://support.bluejeans.com/s/article/Dialing-into-a-meeting-from-a-Desk-Telephone)
+ Genesys:
  + [Genesys Cloud WebRTC media helper](https://help.mypurecloud.com/articles/about-webrtc-media-helper/)
+ Amazon Connect:
  + [Amazon Connect Optimization for Amazon WorkSpaces](https://docs.aws.amazon.com/whitepapers/latest/best-practices-deploying-amazon-workspaces/connect-optimization.html)
+ Google Meet:
  + [Use a phone for audio in a video meeting](https://support.google.com/meet/answer/9518557?hl=en)

# Manage the running mode in WorkSpaces Personal
<a name="running-mode"></a>

The *running mode* of a WorkSpace determines its immediate availability and how you pay for it (monthly or hourly). You can choose between the following running modes when you create the WorkSpace:
+ **AlwaysOn** — Use when paying a fixed monthly fee for unlimited usage of your WorkSpaces. This mode is best for users who use their WorkSpace full time as their primary desktop.
+ **AutoStop** — Use when paying for your WorkSpaces by the hour. With this mode, your WorkSpaces stop after a specified period of disconnection, and the state of apps and data is saved.

For more information, see [WorkSpaces Pricing](https://aws.amazon.com/workspaces/pricing/).

## AutoStop WorkSpaces
<a name="autostop-workspaces"></a>

To set the automatic stop time, select the WorkSpace in the Amazon WorkSpaces console, choose **Actions**, **Modify Running Mode Properties**, and then set **AutoStop Time (hours)**. By default, **AutoStop Time (hours)** is set to 1 hour, which means that the WorkSpace stops automatically an hour after the WorkSpace is disconnected.

After a WorkSpace is disconnected and the AutoStop Time period has expired, it might take several additional minutes for the WorkSpace to automatically stop. However, billing stops as soon as the AutoStop Time period expires, and you aren't charged for that additional time.

When the WorkSpaces support hibernation, the state of the desktop is saved to the root volume of the WorkSpace. The WorkSpace resumes when a user logs in. All open documents and running programs return to their saved state with all WorkSpaces operating systems supporting hibernation.

AutoStop GPU-enabled WorkSpaces and GeneralPurpose.4xlarge or GeneralPurpose.8xlarge do not support hibernation. The state of of applications/data is not preserved. We recommend saving your work when you're done using your WorkSpaces each time to avoid data loss. 

For Bring Your Own License (BYOL) AutoStop WorkSpaces, a large number of concurrent logins could result in significantly increased time for WorkSpaces to be available. If you expect many users to log into your BYOL AutoStop WorkSpaces at the same time, please consult your account manager for advice.

**Important**  
AutoStop WorkSpaces stop automatically only if the WorkSpaces are disconnected.

A WorkSpace is disconnected only in the following circumstances:
+ If the user manually disconnects from the WorkSpace or quits the Amazon WorkSpaces client application.
+ If the client device is shut down.
+ If there's no connection between the client device and the WorkSpace for more than 20 minutes.

As a best practice, AutoStop WorkSpace users should manually disconnect from their WorkSpaces when they're done using them each day. To manually disconnect, choose **Disconnect WorkSpace** or **Quit Amazon WorkSpaces** from the **Amazon WorkSpaces** menu in the WorkSpaces client applications for Linux, macOS, or Windows. For Android or iPad, choose **Disconnect** from the sidebar menu.

**AutoStop WorkSpaces may not stop automatically in the following situations:**
+ If the client device is only locked, sleeping, or otherwise inactive (for example, the laptop lid is closed) instead of shut down, the WorkSpaces application might still be running in the background. As long as the WorkSpaces application is still running, the WorkSpace might not be disconnected, and therefore the WorkSpace might not automatically stop.
+ WorkSpaces can detect disconnection only when users are using WorkSpaces clients. If users are using third-party clients, WorkSpaces might not be able to detect disconnection, and therefore the WorkSpaces might not automatically stop and billing might not be suspended.

## Modify the running mode
<a name="modify-running-mode"></a>

You can switch between running modes at any time.

**To modify the running mode of a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace to modify and choose **Actions**, **Modify running mode**.

1. Select the new running mode, **AlwaysOn** or **AutoStop**, and then choose **Save**.

**To modify the running mode of a WorkSpace using the AWS CLI**  
Use the [modify-workspace-properties](https://docs.aws.amazon.com/cli/latest/reference/workspaces/modify-workspace-properties.html) command.

## Stop and start an AutoStop WorkSpace
<a name="stop-start-workspace"></a>

When your AutoStop WorkSpaces are disconnected, they stop automatically after a specified period of disconnection, and hourly billing is suspended. To further optimize costs, you can manually suspend the hourly charges associated with AutoStop WorkSpaces. The WorkSpace stops and all apps and data are saved for the next time a user logs in to the WorkSpace.

When a user reconnects to a stopped WorkSpace, it resumes from where it left off, typically in under 90 seconds.

You can reboot (restart) AutoStop WorkSpaces that are available or in an error state.

**To stop an AutoStop WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace to stop and choose **Actions**, **Stop WorkSpaces**.

1. When prompted for confirmation, choose **Stop WorkSpace**.

**To start an AutoStop WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpaces to start and choose **Actions**, **Start WorkSpaces**.

1. When prompted for confirmation, choose **Start WorkSpace**.

To remove the fixed infrastructure costs that are associated with AutoStop WorkSpaces, remove the WorkSpace from your account. For more information, see [Delete a WorkSpace in WorkSpaces Personal](delete-workspaces.md).

**To stop and start an AutoStop WorkSpace using the AWS CLI**  
Use the [stop-WorkSpaces](https://docs.aws.amazon.com/cli/latest/reference/workspaces/stop-workspaces.html) and [start-WorkSpaces](https://docs.aws.amazon.com/cli/latest/reference/workspaces/start-workspaces.html) commands.

# Manage applications in WorkSpaces Personal
<a name="manage-applications"></a>

After you launch a WorkSpace, you can see the list of all of the application bundles that are associated with your WorkSpace on the WorkSpaces console.

**To see the list of all the application bundles associated to your WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. From the left navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace and choose **View Details**.

1. Under **Applications**, find the list of applications that are associated with this WorkSpace, along with their installation status.

**You can update the application bundles on your WorkSpace in the following ways:**
+ Install application bundles on your WorkSpace
+ Uninstall application bundles from your WorkSpace
+ Install application bundles and uninstall a different set of application bundles on your WorkSpace

**Note**  
To update application bundles, the WorkSpace must have a status of `AVAILABLE` or `STOPPED`.
Manage applications is only available for Windows WorkSpaces.
Manage applications is only available for application bundles that are subscribed through AWS.

## Supported bundles for Manage applications
<a name="w2aac11c31c25c11"></a>

Manage applications allows you install and uninstall the following applications on your WorkSpaces. For Microsoft Office 2016 bundle and Microsoft Office 2019, you can only uninstall.

**End of Support Notice**  
Microsoft Office, Visio, and Project 2021 (Standard and Professional editions) will reach end of support on **October 13, 2026**. After this date, these applications will no longer receive security updates or technical support from Microsoft.  
**Recommended action**: Migrate to the 2024 LTSC Professional/Standard versions of Office, Visio, and Project.
+ Microsoft Office LTSC Professional Plus 2024
+ Microsoft Visio LTSC Professional 2024
+ Microsoft Project Professional 2024
+ Microsoft Office LTSC Standard 2024
+ Microsoft Visio LTSC Standard 2024
+ Microsoft Project Standard 2024
+ Microsoft Office LTSC Professional Plus 2021
+ Microsoft Visio LTSC Professional 2021
+ Microsoft Project Professional 2021
+ Microsoft Office LTSC Standard 2021
+ Microsoft Visio LTSC Standard 2021
+ Microsoft Project Standard 2021
+ Microsoft Visual Studio Professional 2022
+ Microsoft Visual Studio Enterprise 2022

The following table shows the list of supported and unsupported application and operating system combinations:


|  | Microsoft Office Professional Plus 2016 (32-bit) | Microsoft Office Professional Plus 2019 (64-bit) | Microsoft LTSC Office Professional Plus / Standard 2024 (64-bit) | Microsoft Project Professional / Standard 2024 (64-bit) | Microsoft Visio Professional / Standard 2024 (64-bit) | Microsoft LTSC Office Professional Plus / Standard 2021 (64-bit) | Microsoft Project Professional / Standard 2021 (64-bit) | Microsoft LTSC Visio Professional / Standard 2021 (64-bit) | Microsoft Visual Studio Professional / Enterprise 2022 | 
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | 
| Windows Server 2016 | Uninstall | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | Not supported | 
| Windows Server 2019 | Not supported | Uninstall | Not supported | Not supported | Not supported | Install/uninstall | Install/uninstall | Install/uninstall | Not supported | 
| Windows Server 2022 | Not supported | Uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | 
| Windows Server 2025 | Not supported | Uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Not supported | Not supported | Not supported | Install/uninstall | 
| Windows 10 | Uninstall | Uninstall | Not supported | Not supported | Not supported | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | 
| Windows 11 | Uninstall | Uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | Install/uninstall | 

**Important**  
Microsoft Office/Visio/Project must follow the same editions. For example, you cannot mix Standard applications with Professional applications.
Microsoft Office/Visio/Project must follow the same versions. For example, you cannot mix 2019 applications with 2021 applications.
Microsoft Office/Visio/Project 2021 Standard/Professional are not supported for Value, Graphics, and GraphicsPro WorkSpaces bundles.
Microsoft Office/Visio/Project versions 2010 and 2013 (Standard or Professional editions) are no longer supported.
Microsoft Office/Visio/Project 2024 (Standard or Professional editions) is not supported for Value bundles.
Plus applications bundles with Office 2016 or Office 2019 will no longer be supported after October 14, 2025. We recommend migrating your WorkSpaces bundles with those Office version to use Office 2021 or Office 2024. For more information, see [Manage applications in WorkSpaces Personal](manage-applications).
Microsoft Office, Project and Visio require up to 25 GB of free space for the 2024 versions and up to 20 GB for the 2021 versions.
Value, Standard, Graphics, and GraphicsPro WorkSpaces bundles are not supported for Microsoft Visual Studio 2022 Enterprise/Professional. Performance bundles can be used for Visual Studio workloads that are less resource intensive. However, for best results, we recommended using Visual Studio with quad-core or higher bundle types. The bundle types Power, PowerPro, General Purpose.4xlarge, General Purpose.8xlarge, Graphics.g6, Graphics.g4dn, and GraphicsPro.g4dn meet this requirement. For more information, see [Visual Studio 2022 Product Family System Requirements](https://learn.microsoft.com/en-us/visualstudio/releases/2022/system-requirements).
When you uninstall **Plus applications bundle for Microsoft Office 2016** from your WorkSpaces, you will lose access to any Trend Micro solutions that were included as part of that Amazon WorkSpaces bundle. If you want to continue using Trend Micro solutions with your Amazon WorkSpaces, you can purchase them separately on the [AWS marketplace](https://aws.amazon.com/marketplace/pp/prodview-u2in6sa3igl7c). 
In order to install/uninstall Microsoft 365 apps, you need to bring in your own tools and installers, Manage application workflow cannot install/uninstall Microsoft 365 apps.
You can create a custom image of WorkSpaces with applications installed/uninstalled through Manage applications.
For opt-in Regions, such as Africa (Cape Town), WorkSpaces internet connection must be enabled at the directory level.

## Update application bundles on a WorkSpace
<a name="w2aac11c31c25c13"></a>

1. 

   Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace and choose **Actions**, **Manage applications**.

1. Under **Current applications** you will see a list of application bundles that are already installed on this WorkSpace and under **Choose applications** you have a list of application bundles that are available to install on this WorkSpace.

1. To install application bundles on this WorkSpace:

   1. Select an application bundle that you want to install on this WorkSpace, and choose **Associate**.

   1. Repeat the previous step to install other application bundles.

   1. While the application bundles are installing, you will see them under **Current applications** with the `Pending install deployment` status.

1. To uninstall application bundles from this WorkSpace:

   1. Under **Choose applications**, select an application bundle that you want to uninstall and choose **Disassociate**.

   1. Repeat the previous step to uninstall other application bundles.

   1. While the application bundles are uninstalling, you will see them under **Current applications** with the `Pending uninstall deployment` status.

1. To revert the bundles installation or installation state, do one of the following.
   + If you want to revert the bundles from the `Pending uninstall deployment` state, select the application you want to revert, then choose **Associate**.
   + If you want to revert the bundles from the `Pending install deployment` state, select the application you want to revert, then choose **Disassociate**.

1. After the application bundles you chose to install or uninstall are in pending states, choose **Deploy applications**.
**Important**  
After you select **Deploy applications**, the end user session will terminate and WorkSpaces will not be accessible while the applications are being installed or uninstalled.

1. To confirm your actions, type **confirm**. Choose **force** to install or uninstall applications bundles that are in an **Error** state.

1. To monitor the progress of your application bundles:

   1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

   1. In the navigation pane, choose **WorkSpaces**. You can see the status under **Status** including the following.
      + **UPDATING** - The application bundle update is still ongoing.
      + **AVAILABLE / STOPPED** - The application bundle update is complete and the WorkSpace is back to its original state.

   1. To monitor the installation or uninstallation status of your application bundles, select the WorkSpace and choose **View Details**. Under **Applications**, you can see the status under **Status**, including `Pending install`, `Pending uninstall`, and `Installed`.
**Note**  
If your users observe that their newly installed application bundles through Managed Applications are not license activated, you can perform a manual WorkSpace reboot. Your users can begin using those applications following a reboot. For additional support, contact [AWS Support](https://console.aws.amazon.com/support/home#/).

## Update Microsoft Visual Studio 2022 workloads on a WorkSpace
<a name="w2aac11c31c25c15"></a>

By default Microsoft Visual Studio 2022 is installed with the following workloads and requires 18 GB of hard disk space:
+ Visual Studio core editor
+ Azure development
+ Data storage and processing
+ .NET desktop development
+ NET Multi-platform App UI development
+ ASP.NET and web development
+ Node.js development

Users have the flexibility to add or remove workloads and individual components, allowing them to tailor the application to their specific requirements. It's important to note that installing additional workloads requires more disk space. To learn more about workload configurations, see [Modify Visual Studio workloads, components, and language packs](https://learn.microsoft.com/en-us/visualstudio/install/modify-visual-studio?view=vs-2022).

## Managing WorkSpaces modified using Manage applications
<a name="w2aac11c31c25c17"></a>

After installing or uninstalling application bundles on your WorkSpaces, the following actions can impact existing configurations.
+ **Restore a WorkSpace** - Restoring a WorkSpace recreates both the root volume and user volume, based on the most recent snapshots of these volumes that were created when the WorkSpace was healthy. Full WorkSpace snapshots are taken every 12 hours. For more information, see [ Restore a WorkSpace](https://docs.aws.amazon.com/workspaces/latest/adminguide/restore-workspace.html). Ensure you wait for at least 12 hours before restoring your WorkSpaces that were modified using Manage applications. Restoring your WorkSpaces before the next full snapshot, which were modified using Manage applications, will result in the following:
  +  The application bundles that were installed on your WorkSpaces using the Manage applications workflow will be removed from your WorkSpaces but the license will still be activated and your WorkSpaces will be billed for those applications. To get those application bundles back on your WorkSpaces you need to run the Manage application workflow again, uninstall the application to start fresh, and then install again. 
  +  The application bundles that were removed from your WorkSpaces using the Manage applications workflow will be back on your WorkSpaces. However, those application bundles won’t work properly because the license activation will be missing. In order to get rid of those application bundles, run a manual uninstall of those application bundles from your WorkSpaces. 
+ **Rebuild a WorkSpace** - Rebuilding a WorkSpace recreates the root volume. For more information, see [Rebuild a WorkSpace](https://docs.aws.amazon.com/workspaces/latest/adminguide/rebuild-workspace.html). Rebuilding your WorkSpaces that were modified using Manage applications will result in the following:
  +  The application bundles that were installed on your WorkSpaces using the Manage applications workflow will be removed and deactivated from your WorkSpaces. In order to get those applications back on your WorkSpaces you need to run the Manage applications workflow again. 
  +  The application bundles that were removed from your WorkSpaces via Manage applications workflow will be installed and activated on your WorkSpaces. In order to remove those application bundles from your WorkSpaces, you need to run the Manage applications workflow again. 
+ **Migrate a WorkSpace** - The migration process recreates the WorkSpace by using a new root volume from the target bundle image and the user volume from the last available snapshot of the original WorkSpace. A new WorkSpace with a new WorkSpace ID is created. For more information, see [Migrate a WorkSpace](https://docs.aws.amazon.com/workspaces/latest/adminguide/migrate-workspaces.html) Migrating your WorkSpaces that were modified using Manage applications will result in the following:
  +  All the application bundle from the source WorkSpaces will be removed and deactivated. The new destination WorkSpaces will inherit applications from the destination WorkSpaces bundle. Source WorkSpaces application bundles will be billed for the full month but application bundles on destination bundle will have a pro-rated bill. 

# Modify a WorkSpace in WorkSpaces Personal
<a name="modify-workspaces"></a>

After you launch a WorkSpace, you can modify its configuration in three ways: 
+ You can change the size of its root volume (for Windows, drive C; for Linux, /) and its user volume (for Windows, drive D; for Linux /home).
+ You can change its compute type to select a new bundle.
+ You can modify the streaming protocol using the AWS CLI or Amazon WorkSpaces API if your WorkSpace was created with PCoIP bundles.

To see the current modification state of a WorkSpace, select the arrow to show more details about that WorkSpace. The possible values for **State** are **Modifying Compute**, **Modifying Storage,** and **None**.

If you want to modify a WorkSpace, it must have a status of `AVAILABLE` or `STOPPED`. You can't change the volume size and the compute type at the same time.

Changing the volume size or compute type of a WorkSpace will change the billing rate for the WorkSpace.

To allow your users to modify their volumes and compute types themselves, see [Enable self-service WorkSpaces management capabilities for your users in WorkSpaces Personal](enable-user-self-service-workspace-management.md).

## Modify volume sizes
<a name="modify_volume_sizes"></a>

You can increase the size of the root and user volumes for a WorkSpace, up to 2000 GB each. WorkSpace root and user volumes come in set groups that can't be changed. The available groups are:


| [Root (GB), User (GB)] | 
| --- | 
| [80, 10] | 
| [80, 50] | 
| [80, 100] | 
| [175 to 2000, 100 to 2000] | 

You can expand the root and user volumes whether they are encrypted or unencrypted, and you can expand both volumes once in a 6-hour period. However, you can't increase the size of the root and user volumes at the same time. For more information, see [Limitations for Increasing Volumes](#limitations_increasing_volumes).

**Note**  
When you expand a volume for a WorkSpace, WorkSpaces automatically extends the volume's partition within Windows or Linux. When the process is finished, you must reboot the WorkSpace for the changes to take effect. 

To ensure that your data is preserved, you cannot decrease the size of the root or user volumes after you launch a WorkSpace. Instead, make sure that you specify the minimum sizes for these volumes when launching a WorkSpace.
+ You can launch a Value, Standard, Performance, Power, or PowerPro WorkSpace with a minimum of 80 GB for the root volume and 10 GB for the user volume.
+ You can launch a GeneralPurpose.4xlarge or GeneralPurpose.8xlarge WorkSpace with a minimum of 175GB for the root volume and 100 GB for the user volume.
+ You can launch a Graphics.g6, Graphics.g4dn, GraphicsPro.g4dn, or GraphicsPro WorkSpace with a minimum of 100 GB for the root volume and 100 GB for the user volume. Volume sizing requirements vary based on larger graphics instance types.

While a WorkSpace disk size increase is in progress, users can perform most tasks on their WorkSpace. However, they can't change their WorkSpace compute type, switch the WorkSpace running mode, rebuild their WorkSpace, or reboot (restart) their WorkSpace.

**Note**  
If you want your users to be able to use their WorkSpaces while the disk size increase is in progress, make sure the WorkSpaces have a status of `AVAILABLE` instead of `STOPPED` before you resize the volumes of the WorkSpaces. If the WorkSpaces are `STOPPED`, they can't be started while the disk size increase is in progress.

In most cases, the disk size increase process might take up to two hours. However, if you're modifying the volume sizes for a large number of WorkSpaces, the process can take significantly longer. If you have a large number of WorkSpaces to modify, we recommend contacting AWS Support for assistance.

**Limitations for increasing volumes**
+ You can resize only SSD volumes.
+ When you launch a WorkSpace, you must wait 6 hours before you can modify the sizes of its volumes.
+ You cannot increase the size of the root and user volumes at the same time. To increase the root volume, you must first change the user volume to 100 GB. After that change is made, you can then update the root volume to any value between 175 and 2000 GB. After the root volume has been changed to any value between 175 and 2000 GB, you can then update the user volume further, to any value between 100 and 2000 GB.
**Note**  
If you want to increase both volumes, you must wait 20-30 minutes for the first operation to finish before you can start the second operation.
+ Non-GPU-enabled WorkSpaces’ root volume cannot be less than 175 GB when the user volume is 100 GB. Storage requirements for GPU-enabled WorkSpaces scale proportionally with instance sizing. As you select larger GPU-enabled WorkSpaces configurations, you must allocate correspondingly larger storage volumes to maintain optimal performance and accommodate increased workload demands. For the smallest instance size, begin with the following storage allocation: Root: 100 GB, User: 100 GB. GPU-enabled WorkSpaces support a minimum of 100 GB for the root volume and 100 GB for the user volume.
+ If the user volume is 50 GB, you cannot update the root volume to anything other than 80 GB. If the root volume is 80 GB, the user volume can only be 10, 50, or 100 GB.

**To modify the root volume of a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace and choose **Actions**, **Modify root volume.**.

1. Under **Root volume sizes**, choose a volume size or choose **Custom** to enter a custom volume size.

1. Choose **Save changes**.

1. When the disk size increase is finished, you must [ reboot the WorkSpace](reboot-workspaces.md) for the changes to take effect. To avoid data loss, make sure the user saves any open files before you reboot the WorkSpace.

**To modify the user volume of a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace and choose **Actions**, **Modify user volume.**.

1. Under **User volume sizes**, choose a volume size or choose **Custom** to enter a custom volume size.

1. Choose **Save changes**.

1. When the disk size increase is finished, you must [ reboot the WorkSpace](reboot-workspaces.md) for the changes to take effect. To avoid data loss, make sure the user saves any open files before you reboot the WorkSpace.

**To change the volume sizes of a WorkSpace**  
Use the [modify-workspace-properties](https://docs.aws.amazon.com/cli/latest/reference/workspaces/modify-workspace-properties.html) command with the `RootVolumeSizeGib` or `UserVolumeSizeGib` property.

## Modify compute type
<a name="modify_compute"></a>

You can switch a WorkSpace between the Standard, Power, Performance, PowerPro GeneralPurpose.4xlarge, and GeneralPurpose.8xlarge compute types. For more information about these compute types, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/features/#Amazon_WorkSpaces_Bundles).

**Note**  
If your source operating system is anything other than Windows Server 2022 or Windows 11, you cannot change your compute type from PowerPro to GeneralPurpose.
If you are modifying the compute type from a non-GPU-enabled bundles to GeneralPurpose.4xlarge or GeneralPurpose.8xlarge, your WorkSpaces must meet the minimum root volume size of 175 GB and user volume size of 100 GB. To increase the volume size of your WorkSpaces, see [Modify volume sizes](#modify_volume_sizes).
GPU-enabled WorkSpaces support compute type modifications within the same instance family but do not support cross-family modifications. For example, you can modify the compute type between G4dn instances or between G6 instances, but you cannot change from a G4dn instance to a G6 instance family. To move between GPU-enabled WorkSpace bundles powered by different instance families, use Migrate a WorkSpace feature. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md)
GraphicsPro bundle reaches end-of-life on October 31, 2025. We recommend migrating your GraphicsPro WorkSpaces to supported bundles before October 31, 2025. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md).
You cannot change the compute type of Graphics and GraphicsPro to any other value.

When you request a compute change, WorkSpaces reboots the WorkSpace using the new compute type. WorkSpaces preserves the operating system, applications, data, and storage settings for the WorkSpace.

You can request a larger compute type once in a 6-hour period or a smaller compute type once every 30 days. For a newly launched WorkSpace, you must wait 6 hours before requesting a larger compute type.

When a WorkSpace compute type change is in progress, users are disconnected from their WorkSpace, and they can't use or change the WorkSpace. The WorkSpace is automatically rebooted during the compute type change process.

**Important**  
To avoid data loss, make sure users save any open documents and other application files before you change the WorkSpace compute type.

The compute type change process might take up to an hour.

**To change the compute type of a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace and choose **Actions**, **Modify compute type**.

1. Under **Compute type**, choose a compute type.

1. Choose **Save changes**.

**To change the compute type of a WorkSpace**  
Use the [modify-workspace-properties](https://docs.aws.amazon.com/cli/latest/reference/workspaces/modify-workspace-properties.html) command with the `ComputeTypeName` property.

## Modify protocols
<a name="modify_protocols"></a>

 If your WorkSpace is created with PCoIP bundles, you can modify their streaming protocol using the AWS CLI or the Amazon WorkSpaces API. This allows you to migrate the protocol using your existing WorkSpace without using the WorkSpace migration feature. This also allows you to use DCV and maintain your root volume without re-creating existing PCoIP WorkSpaces during the migration process. 
+ You can only modify your protocol if your WorkSpace was created with PCoIP bundles and is not a GPU-enabled WorkSpace.
+ Before you modify the protocol to DCV, ensure that your WorkSpace meets the following requirements for a DCV WorkSpace.
  + Your WorkSpaces client supports DCV
  + The region where your WorkSpace is deployed supports DCV
  + The IP address and port requirements for DCV are open. For more information, see [IP address and port requirements for WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-port-requirements.html).
  + Ensure your current bundle is available with DCV.
  + For the best experience with video conferencing we recommend using Power, PowerPro, GeneralPurpose.4xlarge, or GeneralPurpose.8xlarge only.

**Note**  
We highly recommend testing with your non-production WorkSpaces before you start changing the protocol.
If you modify the protocol from PCoIP to DCV, and then modify the protocol back to PCoIP, you won't be able to connect to WorkSpaces through Web Access.

**To change the protocol of a WorkSpace**

1. [Optional] Reboot your WorkSpace and wait until it’s in the `AVAILABLE` state before modifying the protocol.

1. [Optional] Use the `describe-workspaces` command to list the WorkSpace properties. Ensure that it’s in the `AVAILABLE` state and its current `Protocol` is accurate. 

1. Use the `modify-workspace-properties` command and modify the `Protocols` property from `PCOIP` to `DCV`, or the other way around.

   ```
   aws workspaces modify-workspace-properties
   --workspace-id <value>
   --workspace-properties "Protocols=[WSP]"
   ```
**Important**  
The `Protocols` property is case-sensitive. Ensure that you use `PCOIP` or `DCV`.

1. After you run the command, it can take up to 20 minutes for the WorkSpace to reboot and complete the necessary configurations.

1. Use the `describe-workspaces` command again to list the WorkSpace properties and verify that it’s in an `AVAILABLE` state and the current `Protocols` property has been changed to the correct protocol.
**Note**  
Modifying the WorkSpace's protocol will not update the bundle description in the console. The **Launch Bundle** description will not change.
If the WorkSpace remains in an `UNHEALTHY` state after 20 min, reboot the WorkSpace in the console.

1. You can now connect to your WorkSpace.

# Customize branding in WorkSpaces Personal
<a name="customize-branding"></a>

Amazon WorkSpaces allows you to create a familiar WorkSpaces experience for your users by using APIs to customize the appearance of your WorkSpace's login page with your own branding logo, IT support information, forgot password link, and login message. Your branding will be displayed to your users in their WorkSpace login page rather than the default WorkSpaces branding. 

The following clients are supported:
+ Windows
+ Linux
+ Android
+ MacOS
+ iOS
+ Web Access

## Import custom branding
<a name="import-custom-branding"></a>

To import your client branding customization, use the action `ImportClientBranding`, which includes the following elements. See [ ImportClientBranding API reference](https://docs.aws.amazon.com/workspaces/latest/api/API_ImportClientBranding.html) for more information.

**Important**  
Client branding attributes are public facing. Ensure that you don't include sensitive information.

Depending on whether your directories are using the legacy or new user login flow, your users will see your custom client branding attributes as shown in the below screenshots.


|  |  | 
| --- |--- |
|  ![\[WorkSpaces client sign in screen - Legacy login flow\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/client-cobranding-legacy.png)  |  ![\[WorkSpaces client sign in screen - New login flow\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/client-cobranding-new.png)  | 

1. Support link

1. Logo

1. Forgot password link

1. Login message


**Custom branding elements**  

| Branding element | Description | Requirements and recommendations | 
| --- | --- | --- | 
| Support link | Allows you to specify a support email link for users to contact for help with their WorkSpaces. You can use the SupportEmail attribute or provide a link to your support page using the SupportLink attribute. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/customize-branding.html) | 
| Logo | Allows you to customize your organization's logo using the Logo attribute. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/customize-branding.html) | 
| Forgot password link | Allows you to add a web address using the ForgotPasswordLink attribute that users can go to if they forget their password to their WorkSpace. | Length Constraints: Minimum length of 1. Maximum length of 200. | 
| Login message | Allows you to customize a message using the LoginMessage attribute on the sign in screen. |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/customize-branding.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/customize-branding.html)  | 

The following are sample code snippets for using ImportClientBranding.

### AWS CLI Version 2
<a name="import-client-branding-cli"></a>

**Warning**  
Importing custom branding overwrites the attributes, within that platform, that you specify with your custom data. It also overwrites the attributes that you don't specify with default custom branding attribute values. You must include the data for any attribute that you don't want to overwrite.

```
aws workspaces import-client-branding \
--cli-input-json file://~/Downloads/import-input.json \
--region us-west-2
```

The import JSON file should look like the following sample code:

```
{
    "ResourceId": "<directory-id>",
    "DeviceTypeOsx": {
        "Logo": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAC0lEQVR42mNgQAcAABIAAeRVjecAAAAASUVORK5CYII=",
        "ForgotPasswordLink": "https://amazon.com/",
        "SupportLink": "https://amazon.com/",
        "LoginMessage": {
            "en_US": "Hello!!"
        }
    }
}
```

The following sample Java code snippet converts the logo image into a base64-encoded string:

```
// Read image as BufferImage
BufferedImage bi = ImageIO.read(new File("~/Downloads/logo.png"));
   
// convert BufferedImage to byte[]
ByteArrayOutputStream baos = new ByteArrayOutputStream();
ImageIO.write(bi, "png", baos);
byte[] bytes = baos.toByteArray();
       
//convert byte[] to base64 format and print it
String bytesBase64 = Base64.encodeBase64String(bytes);
System.out.println(bytesBase64);
```

The following sample Python code snippet converts the logo image into a base64-encoded string:

```
# Read logo into base64-encoded string
with open("~/Downloads/logo.png", "rb") as image_file:
    f = image_file.read()
    base64_string = base64.b64encode(f)
    print(base64_string)
```

### Java
<a name="import-client-branding-java"></a>

**Warning**  
Importing custom branding overwrites the attributes, within that platform, that you specify with your custom data. It also overwrites the attributes that you don't specify with default custom branding attribute values. You must include the data for any attribute that you don't want to overwrite.

```
// Create WS Client
WorkSpacesClient client = WorkSpacesClient.builder().build();

// Read image as BufferImage
BufferedImage bi = ImageIO.read(new File("~/Downloads/logo.png"));

// convert BufferedImage to byte[]
ByteArrayOutputStream baos = new ByteArrayOutputStream();
ImageIO.write(bi, "png", baos);
byte[] bytes = baos.toByteArray();
    
// Create import attributes for the plateform 
DefaultImportClientBrandingAttributes attributes =
        DefaultImportClientBrandingAttributes.builder()
                .logo(SdkBytes.fromByteArray(bytes))
                .forgotPasswordLink("https://aws.amazon.com/")
                .supportLink("https://aws.amazon.com/")
                .build();
                    
// Create import request
ImportClientBrandingRequest request = 
        ImportClientBrandingRequest.builder()
                .resourceId("<directory-id>")
                .deviceTypeOsx(attributes)
                .build();
                    
// Call ImportClientBranding API
ImportClientBrandingResponse response = client.importClientBranding(request);
```

### Python
<a name="import-client-branding-python"></a>

**Warning**  
Importing custom branding overwrites the attributes, within that platform, that you specify with your custom data. It also overwrites the attributes that you don't specify with default custom branding attribute values. You must include the data for any attribute that you don't want to overwrite.

```
import boto3

# Read logo into bytearray
with open("~/Downloads/logo.png", "rb") as image_file:
    f = image_file.read()
    bytes = bytearray(f)

# Create WorkSpaces client
client = boto3.client('workspaces')

# Call import API
response = client.import_client_branding(
    ResourceId='<directory-id>',
    DeviceTypeOsx={
        'Logo': bytes,
        'SupportLink': 'https://aws.amazon.com/',
        'ForgotPasswordLink': 'https://aws.amazon.com/',
        'LoginMessage': {
            'en_US': 'Hello!!'
        }
    }
)
```

### PowerShell
<a name="import-client-branding-powershell"></a>

```
#Requires -Modules @{ ModuleName="AWS.Tools.WorkSpaces"; ModuleVersion="4.1.56"}

# Specify Image Path
$imagePath = "~/Downloads/logo.png"

# Create Byte Array from image file
$imageByte = ([System.IO.File]::ReadAllBytes($imagePath))

# Call import API
Import-WKSClientBranding -ResourceId <directory-id> `
    -DeviceTypeLinux_LoginMessage @{en_US="Hello!!"} `
    -DeviceTypeLinux_Logo $imageByte `
    -DeviceTypeLinux_ForgotPasswordLink "https://aws.amazon.com/" `
    -DeviceTypeLinux_SupportLink "https://aws.amazon.com/"
```

To preview the login page, launch the WorkSpaces application or web login page.

**Note**  
Changes may take up to 1 minute to appear.

## Describe custom branding
<a name="describe-custom-branding"></a>

To see the details of the client branding customization you currently have, use the action `DescribeCustomBranding`. The following is the sample script for using DescribeClientBranding. See [ DescribeClientBranding API reference](https://docs.aws.amazon.com/workspaces/latest/api/API_DescribeClientBranding.html) for more information.

```
aws workspaces describe-client-branding \
--resource-id <directory-id> \
--region us-west-2
```

## Delete custom branding
<a name="delete-custom-branding"></a>

To delete your client branding customization, use the action `DeleteCustomBranding`. The following is the sample script for using DeleteClientBranding. See [ DeleteClientBranding API reference](https://docs.aws.amazon.com/workspaces/latest/api/API_DeleteClientBranding.html) for more information.

```
aws workspaces delete-client-branding \ 
--resource-id <directory-id> \
--platforms DeviceTypeAndroid DeviceTypeIos \  
--region us-west-2
```

**Note**  
Changes may take up to 1 minute to appear.

# Tag resources in WorkSpaces Personal
<a name="tag-workspaces-resources"></a>

You can organize and manage the resources for your WorkSpaces by assigning your own metadata to each resource in the form of *tags*. You specify a *key* and a *value* for each tag. A key can be a general category, such as "project," "owner," or "environment," with specific associated values. Using tags is a simple yet powerful way to manage AWS resources and to organize data, including billing data.

When you add tags to an existing resource, those tags don't appear in your cost allocation report until the first day of the following month. For example, if you add tags to an existing WorkSpace on July 15, the tags won't appear in your cost allocation report until August 1. For more information, see [Using Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the *AWS Billing User Guide*.

**Note**  
To view your WorkSpaces resource tags in the Cost Explorer, you must activate the tags that you have applied to your WorkSpaces resources by following the instructions in [Activating User-Defined Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) in the *AWS Billing User Guide*.  
Although tags appear 24 hours after activation, it can take 4 to 5 days for values associated with those tags to appear in the Cost Explorer. Additionally, to appear and provide cost data in Cost Explorer, WorkSpaces resources that have been tagged must incur charges during that time. Cost Explorer only shows cost data from the time when the tags were activated and onward. No historical data is available at this time.

**Resources that you can tag**
+ You can add tags to the following resources when you create them—WorkSpaces, imported images, and IP access control groups.
+ You can add tags to existing resources of the following types—WorkSpaces, registered directories, custom bundles, images, and IP access control groups.

**Tag restrictions**
+ Maximum number of tags per resource—50
+ Maximum key length—127 Unicode characters
+ Maximum value length—255 Unicode characters
+ Tag keys and values are case-sensitive. Allowed characters are letters, spaces, and numbers representable in UTF-8, plus the following special characters: \$1 - = . \$1 : / @. Do not use leading or trailing spaces.
+ Do not use the `aws:` or `aws:workspaces:` prefixes in your tag names or values because they are reserved for AWS use. You can't edit or delete tag names or values with these prefixes.

**To update the tags for an existing resource using the console (directories, WorkSpaces, or IP access control groups)**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose one of the following resource types: **Directories**, **WorkSpaces**, or **IP Access Controls**.

1. Select the resource to open its details page.

1. Do one or more of the following:
   + To update a tag, edit the values of **Key** and **Value**.
   + To add a tag, choose **Add Tag** and then edit the values of **Key** and **Value**.
   + To delete a tag, choose the delete icon (X) next to the tag.

1. When you are finished updating tags, choose **Save**.

**To update the tags for an existing resource using the console (images or bundles)**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose one of the following resource types: **Bundles** or **Images**.

1. Choose the resource to open its details page.

1. Under **Tags**, choose **Manage tags**.

1. Do one or more of the following:
   + To update a tag, edit the values of **Key** and **Value**.
   + To add a tag, choose **Add new tag** and then edit the values of **Key** and **Value**.
   + To delete a tag, choose **Remove** next to the tag.

1. When you are finished updating tags, choose **Save changes**.

**To update the tags for an existing resource using the AWS CLI**  
Use the [create-tags](https://docs.aws.amazon.com/cli/latest/reference/workspaces/create-tags.html) and [delete-tags](https://docs.aws.amazon.com/cli/latest/reference/workspaces/delete-tags.html) commands.

# Maintenance in WorkSpaces Personal
<a name="workspace-maintenance"></a>

We recommend that you maintain your WorkSpaces on a regular basis. WorkSpaces schedules default maintenance windows for your WorkSpaces. During the maintenance window, the WorkSpace installs important updates from Amazon WorkSpaces and reboots as necessary. If available, operating system updates are also installed from the OS update server that the WorkSpace is configured to use. During maintenance, your WorkSpaces might be unavailable.

By default, your Windows WorkSpaces are configured to receive updates from Windows Update. To configure your own automatic update mechanisms for Windows, see the documentation for [ Windows Server Update Services (WSUS)](https://docs.microsoft.com/windows-server/administration/windows-server-update-services/deploy/deploy-windows-server-update-services) and [Configuration Manager](https://docs.microsoft.com/configmgr/sum/deploy-use/deploy-software-updates).

**Requirement**  
Your WorkSpaces must have access to the internet so that you can install updates to the operating system and deploy applications. For more information, see [Provide internet access for WorkSpaces Personal](amazon-workspaces-internet-access.md).

## Maintenance windows for AlwaysOn WorkSpaces
<a name="alwayson-maintenance"></a>

For AlwaysOn WorkSpaces, the maintenance window is determined by operating system settings. The default is a four-hour period from 00h00 to 04h00, in the time zone of the WorkSpace, each Sunday morning. By default, the time zone of an AlwaysOn WorkSpace is the time zone of the AWS Region for the WorkSpace. However, if you connect from another Region and time zone redirection is enabled, and then you disconnect, the time zone of the WorkSpace is updated to the time zone of the Region that you connected from.

You can [disable time zone redirection for Windows WorkSpaces](group_policy.md#gp_time_zone) using Group Policy. You can [disable time zone redirection for Linux WorkSpaces](manage_linux_workspace.md#linux_time_zone) by using the PCoIP Agent conf.

For Windows WorkSpaces, you can configure the maintenance window using Group Policy; see [Configure Group Policy Settings for Automatic Updates](https://docs.microsoft.com/windows-server/administration/windows-server-update-services/deploy/4-configure-group-policy-settings-for-automatic-updates). You cannot configure the maintenance window for Linux WorkSpaces.

## Maintenance windows for AutoStop WorkSpaces
<a name="autostop-maintenance"></a>

AutoStop WorkSpaces are started automatically once a month in order to install important updates. Beginning on the third Monday of the month, and for up to two weeks, the maintenance window is open each day from about 00h00 to 05h00, in the time zone of the AWS Region for the WorkSpace. The WorkSpace can be maintained on any one day in the maintenance window. During this window, only WorkSpaces older than 7 days are maintained.

During the time period when the WorkSpace is undergoing maintenance, the state of the WorkSpace is set to `MAINTENANCE`.

Although you cannot modify the time zone that is used for maintaining AutoStop WorkSpaces, you can disable the maintenance window for your AutoStop WorkSpaces as follows. If you disable maintenance mode, your WorkSpaces are not rebooted and do not enter the `MAINTENANCE` state.

**To disable maintenance mode**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Directories**.

1. Select your directory, and choose **Actions**, **Update Details**.

1. Expand **Maintenance Mode**.

1. To enable automatic updates, choose **Enabled**. If you prefer to manage updates manually, choose **Disabled**.

1. Choose **Update and Exit**.

## Manual maintenance
<a name="admin-maintenance"></a>

If you prefer, you can maintain your WorkSpaces on your own schedule. When you perform maintenance tasks, we recommend that you change the state of the WorkSpace to **Maintenance**. When you are finished, change the state of the WorkSpace to **Available**.

When a WorkSpace is in **Maintenance** state, the following behaviors occur:
+ The WorkSpace does not respond to requests to reboot, stop, start, or rebuild.
+ Users cannot log in to the WorkSpace.
+ An AutoStop WorkSpace is not hibernated.

**To change the state of the WorkSpace using the console**
**Note**  
To change the state of a WorkSpace, the WorkSpace must be in the **Available** state. The **Modify state** setting is not available when a WorkSpace is not in the **Available** state.

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select your WorkSpace, and choose **Actions**, **Modify state**.

1. Under **Modify state**, choose **Available** or **Maintenance**.

1. Choose **Save**.

**To change the state of the WorkSpace using the AWS CLI**  
Use the [modify-workspace-state](https://docs.aws.amazon.com/cli/latest/reference/workspaces/modify-workspace-state.html) command.

# Encrypted WorkSpaces in WorkSpaces Personal
<a name="encrypt-workspaces"></a>

WorkSpaces is integrated with the AWS Key Management Service (AWS KMS). This enables you to encrypt storage volumes of WorkSpaces using AWS KMS Key. When you launch a WorkSpace, you can encrypt the root volume (for Microsoft Windows, the C drive; for Linux, /) and the user volume (for Windows, the D drive; for Linux, /home). Doing so ensures that the data stored at rest, disk I/O to the volume, and snapshots created from the volumes are all encrypted.

**Note**  
In addition to encrypting your WorkSpaces, you can also use FIPS endpoint encryption in certain AWS US Regions. For more information, see [Configure FedRAMP authorization or DoD SRG compliance for WorkSpaces Personal](fips-encryption.md).
Windows BitLocker encryption is not supported for Amazon WorkSpaces.  Amazon WorkSpaces will attempt to decrypt any volumes detected during boot on all Windows Operating Systems where applicable.  Volumes can become unresponsive during boot process if any combination of passwords, pins, or startup keys are enabled for any volumes on the WorkSpace it can become unhealthy and unable to boot properly.

**Topics**
+ [Prerequisites](#encryption_prerequisites)
+ [Limits](#encryption_limits)
+ [Overview of WorkSpaces encryption using AWS KMS](#kms-workspaces-overview)
+ [WorkSpaces encryption context](#kms-workspaces-encryption-context)
+ [Grant WorkSpaces permission to use a KMS Key on your behalf](#kms-workspaces-permissions)
+ [Encrypt a WorkSpace](#encrypt_workspace)
+ [View encrypted WorkSpaces](#maintain_encryption)

## Prerequisites
<a name="encryption_prerequisites"></a>

You need an AWS KMS Key before you can begin the encryption process. This KMS Key can be either the [AWS managed KMS Key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) for Amazon WorkSpaces (**aws/workspaces**) or a symmetric [ customer managed KMS Key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk).
+ **AWS managed KMS Keys** – The first time that you launch an unencrypted WorkSpace from the WorkSpaces console in a Region, Amazon WorkSpaces automatically creates an AWS managed KMS Key (**aws/workspaces**) in your account. You can select this AWS managed KMS Key to encrypt the user and root volumes of your WorkSpace. For details, see [Overview of WorkSpaces encryption using AWS KMS](#kms-workspaces-overview).

  You can view this AWS managed KMS Key, including its policies and grants, and can track its use in AWS CloudTrail logs, but you cannot use or manage this KMS Key. Amazon WorkSpaces creates and manages this KMS Key. Only Amazon WorkSpaces can use this KMS Key, and WorkSpaces can use it only to encrypt WorkSpaces resources in your account. 

  AWS managed KMS Key, including the one that Amazon WorkSpaces supports, are rotated every year. For details, see [Rotating AWS KMS Key](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) in the *AWS Key Management Service Developer Guide*.
+ **Customer managed KMS Key** – Alternatively, you can select a symmetric customer managed KMS Key that you created using AWS KMS. You can view, use, and manage this KMS Key, including setting its policies. For more information about creating KMS Keys, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*. For more information about creating KMS Keys using the AWS KMS API, see [Working with Keys](https://docs.aws.amazon.com/kms/latest/developerguide/programming-keys.html) in the *AWS Key Management Service Developer Guide*.

  Customer managed KMS Keys are not automatically rotated unless you decide to enable automatic key rotation. For details, see [Rotating AWS KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) in the *AWS Key Management Service Developer Guide*.

**Important**  
When you manually rotate KMS Keys, you must keep both the original KMS Key and the new KMS Key enabled so that AWS KMS can decrypt the WorkSpaces that the original KMS Key encrypted. If you don't want to keep the original KMS Key enabled, you must recreate your WorkSpaces and encrypt them using the new KMS Key.

You must meet the following requirements to use an AWS KMS Key to encrypt your WorkSpaces:
+ **The KMS Key must be symmetric.** Amazon WorkSpaces does not support asymmetric KMS Keys. For information about distinguishing between symmetric and asymmetric KMS Keys, see [ Identifying Symmetric and Asymmetric KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/find-symm-asymm.html) in the *AWS Key Management Service Developer Guide*.
+ **The KMS Key must be enabled.** To determine whether a KMS Key is enabled, see [ Displaying KMS Key Details](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys-console.html#viewing-console-details) in the *AWS Key Management Service Developer Guide*.
+ **You must have the correct permissions and policies associated with the KMS Key.** For more information, see [Part 2: Grant WorkSpaces administrators additional permissions using an IAM policy](#kms-permissions-iam-policy).

## Limits
<a name="encryption_limits"></a>
+ You can't encrypt an existing WorkSpace. You must encrypt a WorkSpace when you launch it.
+ Creating a custom image from an encrypted WorkSpace is not supported.
+ Disabling encryption for an encrypted WorkSpace is not currently supported.
+ WorkSpaces launched with root volume encryption enabled might take up to an hour to provision.
+ To reboot or rebuild an encrypted WorkSpace, first make sure that the AWS KMS Key is enabled; otherwise, the WorkSpace becomes unusable. To determine whether a KMS Key is enabled, see [ Displaying KMS Key Details](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys-console.html#viewing-console-details) in the *AWS Key Management Service Developer Guide*.

## Overview of WorkSpaces encryption using AWS KMS
<a name="kms-workspaces-overview"></a>

When you create WorkSpaces with encrypted volumes, WorkSpaces uses Amazon Elastic Block Store (Amazon EBS) to create and manage those volumes. Amazon EBS encrypts your volumes with a data key using the industry-standard AES-256 algorithm. Both Amazon EBS and Amazon WorkSpaces use your KMS Key to work with the encrypted volumes. For more information about EBS volume encryption, see [Amazon EBS Encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html) in the *Amazon EC2 User Guide*.

When you launch WorkSpaces with encrypted volumes, the end-to-end process works like this:

1. You specify the KMS Key to use for encryption as well as the user and directory for the WorkSpace. This action creates a [grant](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) that allows WorkSpaces to use your KMS Key only for this WorkSpace—that is, only for the WorkSpace associated with the specified user and directory.

1. WorkSpaces creates an encrypted EBS volume for the WorkSpace and specifies the KMS Key to use as well as the volume's user and directory. This action creates a grant that allows Amazon EBS to use your KMS Key only for this WorkSpace and volume—that is, only for the WorkSpace associated with the specified user and directory, and only for the specified volume.

1. <a name="WSP-EBS-requests-encrypted-volume-data-key"></a>Amazon EBS requests a volume data key that is encrypted under your KMS Key and specifies the WorkSpace user's Active Directory security identifier (SID) and AWS Directory Service directory ID as well as the Amazon EBS volume ID as the [encryption context](#kms-workspaces-encryption-context).

1. <a name="WSP-KMS-creates-data-key"></a>AWS KMS creates a new data key, encrypts it under your KMS Key, and then sends the encrypted data key to Amazon EBS.

1. <a name="WSP-uses-EBS-to-attach-encrypted-volume"></a>WorkSpaces uses Amazon EBS to attach the encrypted volume to your WorkSpace. Amazon EBS sends the encrypted data key to AWS KMS with a [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) request and specifies the WorkSpace user's SID, the directory ID, and the volume ID, which is used as the encryption context.

1. AWS KMS uses your KMS Key to decrypt the data key, and then sends the plain text data key to Amazon EBS.

1. Amazon EBS uses the plain text data key to encrypt all data going to and from the encrypted volume. Amazon EBS keeps the plain text data key in memory for as long as the volume is attached to the WorkSpace.

1. Amazon EBS stores the encrypted data key (received at [Step 4](#WSP-KMS-creates-data-key)) with the volume metadata for future use in case you reboot or rebuild the WorkSpace.

1. When you use the AWS Management Console to remove a WorkSpace (or use the [https://docs.aws.amazon.com/workspaces/latest/devguide/API_TerminateWorkspaces.html](https://docs.aws.amazon.com/workspaces/latest/devguide/API_TerminateWorkspaces.html) action in the WorkSpaces API), WorkSpaces and Amazon EBS retire the grants that allowed them to use your KMS Key for that WorkSpace.

## WorkSpaces encryption context
<a name="kms-workspaces-encryption-context"></a>

WorkSpaces doesn't use your KMS Key directly for cryptographic operations (such as [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html), [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html), [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), etc.), which means WorkSpaces doesn't send requests to AWS KMS that include an [ encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context). However, when Amazon EBS requests an encrypted data key for the encrypted volumes of your WorkSpaces ([Step 3](#WSP-EBS-requests-encrypted-volume-data-key) in the [Overview of WorkSpaces encryption using AWS KMS](#kms-workspaces-overview)) and when it requests a plain text copy of that data key ([Step 5](#WSP-uses-EBS-to-attach-encrypted-volume)), it includes encryption context in the request.

 The encryption context provides [additional authenticated data](https://docs.aws.amazon.com/crypto/latest/userguide/cryptography-concepts.html#term-aad) (AAD) that AWS KMS uses to ensure data integrity. The encryption context is also written to your AWS CloudTrail log files, which can help you understand why a given KMS Key was used. Amazon EBS uses the following for the encryption context:
+ The security identifier (SID) of the Active Directory user that is associated with the WorkSpace
+ The directory ID of the AWS Directory Service directory that is associated with the WorkSpace
+ The Amazon EBS volume ID of the encrypted volume

The following example shows a JSON representation of the encryption context that Amazon EBS uses:

```
{
  "aws:workspaces:sid-directoryid": "[S-1-5-21-277731876-1789304096-451871588-1107]@[d-1234abcd01]",
  "aws:ebs:id": "vol-1234abcd"
}
```

## Grant WorkSpaces permission to use a KMS Key on your behalf
<a name="kms-workspaces-permissions"></a>

You can protect your WorkSpace data under the AWS managed KMS Key for WorkSpaces (**aws/workspaces**) or a customer managed KMS Key. If you use a customer managed KMS Key, you need to grant WorkSpaces permission to use the KMS Key on behalf of the WorkSpaces administrators in your account. The AWS managed KMS Key for WorkSpaces has the required permissions by default.

To prepare your customer managed KMS Key for use with WorkSpaces, use the following procedure.

1. [Add your WorkSpaces administrators to the list of key users in the KMS Key's key policy](#kms-permissions-key-users)

1. [Give your WorkSpaces administrators additional permissions with an IAM policy](#kms-permissions-iam-policy)

Your WorkSpaces administrators also need permission to use WorkSpaces. For more information about these permissions, go to [Identity and access management for WorkSpaces](workspaces-access-control.md).

### Part 1: Add WorkSpaces administrators to as key users
<a name="kms-permissions-key-users"></a>

To give WorkSpaces administrators the permissions that they require, you can use the AWS Management Console or the AWS KMS API.

#### To add WorkSpaces administrators as key users for a KMS Key (console)
<a name="kms-permissions-users-consoleAPI"></a>

1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).

1. To change the AWS Region, use the Region selector in the upper-right corner of the page.

1. In the navigation pane, choose **Customer managed keys**.

1. Choose the key ID or alias of your preferred customer managed KMS Key.

1. Choose the **Key policy** tab. Under **Key users**, choose **Add**.

1. In the list of IAM users and roles, select the users and roles that correspond to your WorkSpaces administrators, and then choose **Add**.

#### To add WorkSpaces administrators as key users for a KMS Key (API)
<a name="kms-permissions-users-api"></a>

1. Use the [GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) operation to get the existing key policy, and then save the policy document to a file.

1. Open the policy document in your preferred text editor. Add the IAM users and roles that correspond to your WorkSpaces administrators to the policy statements that [ give permission to key users](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-users). Then save the file.

1. Use the [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) operation to apply the key policy to the KMS Key.

### Part 2: Grant WorkSpaces administrators additional permissions using an IAM policy
<a name="kms-permissions-iam-policy"></a>

If you select a customer managed KMS Key to use for encryption, you must establish IAM policies that allow Amazon WorkSpaces to use the KMS Key on behalf of an IAM user in your account who launches encrypted WorkSpaces. That user also needs permission to use Amazon WorkSpaces. For more information about creating and editing IAM user policies, see [ Managing IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html) in the *IAM User Guide* and [Identity and access management for WorkSpaces](workspaces-access-control.md).

WorkSpaces encryption requires limited access to the KMS Key. The following is a sample key policy that you can use. This policy separates the principals who can manage the AWS KMS Key from those who can use it. Before you use this sample key policy, replace the example account ID and IAM user name with actual values from your account.

The first statement matches the default AWS KMS key policy. It gives your account permission to use IAM policies to control access to the KMS Key. The second and third statements define which AWS principals can manage and use the key, respectively. The fourth statement enables AWS services that are integrated with AWS KMS to use the key on behalf of the specified principal. This statement enables AWS services to create and manage grants. The statement uses a condition element that limits grants on the KMS Key to those made by AWS services on behalf of users in your account.

**Note**  
If your WorkSpaces administrators use the AWS Management Console to create WorkSpaces with encrypted volumes, the administrators need permission to list aliases and list keys (the `"kms:ListAliases"` and `"kms:ListKeys"` permissions). If your WorkSpaces administrators use only the Amazon WorkSpaces API (not the console), you can omit the `"kms:ListAliases"` and `"kms:ListKeys"` permissions.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::123456789012:root"},
      "Action": "kms:*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::123456789012:user/Alice"},
      "Action": [
        "kms:Create*",
        "kms:Describe*",
        "kms:Enable*",
        "kms:List*",
        "kms:Put*",
        "kms:Update*",
        "kms:Revoke*",
        "kms:Disable*",
        "kms:Get*",
        "kms:Delete*"
       ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::123456789012:user/Alice"},
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncryptFrom",
        "kms:ReEncryptTo",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::123456789012:user/Alice"},
      "Action": [
        "kms:CreateGrant",
        "kms:ListGrants",
        "kms:RevokeGrant"
      ],
      "Resource": "*",
      "Condition": {"Bool": {"kms:GrantIsForAWSResource": "true"}}
    }
  ]
}
```

------

The IAM policy for a user or role that is encrypting a WorkSpace must include usage permissions on the customer managed KMS Key, as well as access to WorkSpaces. To give an IAM user or role WorkSpaces permissions, you can attach the following sample policy to the IAM user or role.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ds:*",
                "ds:DescribeDirectories",
                "workspaces:*",
                "workspaces:DescribeWorkspaceBundles",
                "workspaces:CreateWorkspaces",
                "workspaces:DescribeWorkspaceBundles",
                "workspaces:DescribeWorkspaceDirectories",
                "workspaces:DescribeWorkspaces",
                "workspaces:RebootWorkspaces",
                "workspaces:RebuildWorkspaces"
            ],
            "Resource": "*"
        }
    ]
}
```

------

The following IAM policy is required by the user for using AWS KMS. It gives the user read-only access to the KMS Key along with the ability to create grants.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:CreateGrant",
                "kms:Describe*",
                "kms:List*"
            ],
            "Resource": "*"
        }
    ]
}
```

------

If you want to specify the KMS Key in your policy, use an IAM policy similar to the following. Replace the example KMS Key ARN with a valid one.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "kms:CreateGrant",
      "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:ListAliases",
        "kms:ListKeys"
      ],
      "Resource": "*"
    }
  ]
}
```

------

## Encrypt a WorkSpace
<a name="encrypt_workspace"></a>

**To encrypt a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. Choose **Launch WorkSpaces** and complete the first three steps.

1. For the **WorkSpaces Configuration** step, do the following:

   1. Select the volumes to encrypt: **Root Volume**, **User Volume**, or both volumes.

   1. For **Encryption Key**, select an AWS KMS Key, either the AWS managed KMS Key created by Amazon WorkSpaces or a KMS Key that you created. The KMS Key that you select must be symmetric. Amazon WorkSpaces does not support asymmetric KMS Keys.

   1. Choose **Next Step**.

1. Choose **Launch WorkSpaces**.

## View encrypted WorkSpaces
<a name="maintain_encryption"></a>

To see which WorkSpaces and volumes have been encrypted from the WorkSpaces console, choose **WorkSpaces** from the navigation bar on the left. The **Volume Encryption** column shows whether each WorkSpace has encryption enabled or disabled. To see which specific volumes have been encrypted, expand the WorkSpace entry to see the **Encrypted Volumes** field.

# Reboot a WorkSpace in WorkSpaces Personal
<a name="reboot-workspaces"></a>

Occasionally, you might need to reboot (restart) a WorkSpace manually. Rebooting a WorkSpace disconnects the user and then performs a shutdown and reboot of the WorkSpace. To avoid data loss, make sure the user saves any open documents and other application files before you reboot the WorkSpace. The user data, operating system, and system settings are not affected.

**Warning**  
To reboot an encrypted WorkSpace, first make sure that the AWS KMS Key is enabled; otherwise, the WorkSpace becomes unusable. To determine whether a KMS Key is enabled, see [ Displaying KMS Key Details](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys-console.html#viewing-console-details) in the *AWS Key Management Service Developer Guide*.

**To reboot a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpaces to reboot and choose **Actions**, **Reboot WorkSpaces**.

1. When prompted for confirmation, choose **Reboot WorkSpaces**.

**To reboot a WorkSpace using the AWS CLI**  
Use the [reboot-workspaces](https://docs.aws.amazon.com/cli/latest/reference/workspaces/reboot-workspaces.html) command.

**To bulk reboot WorkSpaces**  
Use the [amazon-workspaces-admin-module](https://github.com/aws-samples/amazon-workspaces-admin-module/tree/main).

# Rebuild a WorkSpace in WorkSpaces Personal
<a name="rebuild-workspace"></a>

Rebuilding a WorkSpace recreates the root volume of the most recent image of the bundle that the WorkSpace was launched from, its user volume, and its primary elastic network interface. Rebuilding a WorkSpace deletes more data than restoring a WorkSpace, but it only requires you to have a snapshot of the user volume. To restore a WorkSpace, see [Restore a WorkSpace in WorkSpaces Personal](restore-workspace.md).

Rebuilding a WorkSpace causes the following to occur:
+ The root volume (for Microsoft Windows, drive C; for Linux, /) is refreshed with the most recent image of the bundle that the WorkSpace was created from. Any applications that were installed, or system settings that were changed after the WorkSpace was created, are lost.
+ The user volume (for Microsoft Windows, the D drive; for Linux, /home) is recreated from the most recent snapshot. The current contents of the user volume are overwritten.

  Automatic snapshots for use when rebuilding a WorkSpace are scheduled every 12 hours. These snapshots of the user volume are taken regardless of the health of the WorkSpace. When you choose **Actions**, **Rebuild / Restore WorkSpace**, the date and time of the most recent snapshot is shown.

  When you rebuild a WorkSpace, new snapshots are also taken soon after the rebuild is finished (often within 30 minutes).
+ The primary elastic network interface is recreated. The WorkSpace receives a new private IP address.

**Important**  
After January 14, 2020, WorkSpaces created from a public Windows 7 bundle can no longer be rebuilt. You might want to consider migrating your Windows 7 WorkSpaces to Windows 10. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md).

You can rebuild a WorkSpace only if the following conditions are met:
+ The WorkSpace must have a state of `AVAILABLE`, `ERROR`, `UNHEALTHY`, `STOPPED`, or `REBOOTING`. To rebuild a WorkSpace in the `REBOOTING` state, you must use the [ RebuildWorkspaces](https://docs.aws.amazon.com/workspaces/latest/api/API_RebuildWorkspaces.html) API operation or the [ rebuild-workspaces](https://docs.aws.amazon.com/cli/latest/reference/workspaces/rebuild-workspaces.html) AWS CLI command.
+ A snapshot of the user volume must exist.

**To rebuild a WorkSpace**
**Warning**  
To rebuild an encrypted WorkSpace, first make sure that the AWS KMS Key is enabled; otherwise, the WorkSpace becomes unusable. To determine whether a KMS Key is enabled, see [ Displaying KMS Key Details](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys-console.html#viewing-console-details) in the *AWS Key Management Service Developer Guide*.

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace to rebuild and choose **Actions**, **Rebuild / Restore WorkSpace**.

1. Under **Snapshot**, select the snapshot's time stamp.

1. Choose **Rebuild**.

**To rebuild a WorkSpace using the AWS CLI**  
Use the [rebuild-workspaces](https://docs.aws.amazon.com/cli/latest/reference/workspaces/rebuild-workspaces.html) command.

**Troubleshooting**  
If you rebuild a WorkSpace after changing the user's **sAMAccountName** user naming attribute in Active Directory, you might receive the following error message:

```
"ErrorCode": "InvalidUserConfiguration.Workspace"
"ErrorMessage": "The user was either not found or is misconfigured."
```

To work around this issue, either revert to the original user naming attribute and then re-initiate the rebuild, or create a new WorkSpace for that user.

**Rebuild Microsoft Entra ID-joined WorkSpaces**  
When a user logs in to their WorkSpace for the first time after rebuilding, they need to go through the out-of-box experience (OOBE) again, similar to when they were assigned a new WorkSpace. As a result, a new user profile folder is created on the WorkSpace, overriding the original user profile folder. Hence, during the rebuild of an Entra joined WorkSpace, the content from the original user profile folder is saved under `D:\Users\<USERNAME%MMddyyTHHmmss%.NotMigrated>` on the rebuilt WorkSpace. The user needs to copy the original profile content from `D:\Users\<USERNAME%MMddyyTHHmmss%.NotMigrated>` to the user's profile folder at D:\$1Users\$1<USERNAME> to restore all user profile data including desktop icons, shortcuts, and data files.

**Note**  
For Microsoft Entra ID-joined WorkSpaces, we recommend to always use Restore WorkSpaces, when possible, instead of Rebuild WorkSpaces.

# Restore a WorkSpace in WorkSpaces Personal
<a name="restore-workspace"></a>

Restoring a WorkSpace recreates both the root volume and user volume using a snapshot of each volume that was taken when the WorkSpace was health. Restoring a WorkSpace rolls back the data on both the root and user volumes to the point in time when the snapshots were created. Rebuilding a WorkSpace only rolls back the data on the user volume. This means that restoring requires you to have snapshots of both the root volume and user volume, while rebuilding a WorkSpace only requires a snapshot of the user volume. To rebuild a WorkSpace, see [Rebuild a WorkSpace in WorkSpaces Personal](rebuild-workspace.md).

Restoring a WorkSpace causes the following to occur:
+ The root volume (for Microsoft Windows, drive C; for Linux, /) is restored to the date and time specified using a snapshot. Any applications that were installed, or system settings that were changed after the snapshot was created, are lost.
+ The user volume (for Microsoft Windows, the D drive; for Linux, /home) is recreated to the date and time specified using a snapshot. The current contents of the user volume are overwritten.

**The restore point**  
When you choose **Actions** and **Rebuild / Restore WorkSpace**, the date and time of the snapshots used for the operation are shown. To verify the date and time of the snapshots used for the operation using the AWS CLI, use the [describe-workspace-snapshots](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspace-snapshots.html) command. 

**When snapshots are taken**  
Snapshots of the root and user volume are taken on the following basis. 
+ **After a WorkSpace is first created** — Typically, the initial snapshots of the root and user volumes are taken soon after a WorkSpace is created (often within 30 minutes). In some AWS Regions, it might take several hours to take the initial snapshots after a WorkSpace is created.

  If a WorkSpace becomes unhealthy before the initial snapshots are taken, the WorkSpace can't be restored. In that case, you can try [ rebuilding the WorkSpace](rebuild-workspace.md) or contact AWS Support for assistance.
+ **During regular use** — Automatic snapshots for use when restoring a WorkSpace are scheduled every 12 hours. If the WorkSpace is healthy, snapshots of both the root volume and user volume are created around the same time. If the WorkSpace is unhealthy, snapshots are created only for the user volume.
+ **After a WorkSpace has been restored** — When you restore a WorkSpace, new snapshots are taken soon after the restore is finished (often within 30 minutes). In some AWS Regions, it might take several hours to take these snapshots after a WorkSpace is restored.

  After a WorkSpace has been restored, if the WorkSpace becomes unhealthy before new snapshots can be taken, the WorkSpace can't be restored again. In that case, you can try [rebuilding the WorkSpace](rebuild-workspace.md) or contact AWS Support for assistance.

You can restore a WorkSpace only if the following conditions are met:
+ The WorkSpace must have a state of `AVAILABLE`, `ERROR`, `UNHEALTHY`, or `STOPPED`.
+ Snapshots of the root and user volumes must exist.

**To restore a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace to restore and choose **Actions**, **Rebuild / Restore WorkSpace**.

1. Under **Snapshot**, select the snapshot's time stamp.

1. Choose **Restore**.

**To restore a WorkSpace using the AWS CLI**  
Use the [restore-workspace](https://docs.aws.amazon.com/cli/latest/reference/workspaces/restore-workspace.html) command.

# Microsoft 365 Bring Your Own License (BYOL) in WorkSpaces Personal
<a name="byol-microsoft365-licenses"></a>

Amazon WorkSpaces allows you to bring your own Microsoft 365 licenses if they meet Microsoft's licensing requirements. These licenses allow you to install and activate Microsoft 365 Apps for enterprise software on WorkSpaces that are powered by the following operating systems:
+ Windows 10 (Bring Your Own License)
+ Windows 11 (Bring Your Own License)
+ Windows Server 2016
+ Windows Server 2019
+ Windows Server 2022
+ Windows Server 2025

To use Microsoft 365 Apps for enterprise on WorkSpaces, you must have subscription to Microsoft 365 E3/E5, Microsoft 365 A3/A5, Microsoft 365 G3/G5, or Microsoft 365 Business Premium.

On your Amazon WorkSpaces you can use your Microsoft 365 licenses to install and activate Microsoft 365 Apps for enterprise, including the following:
+ Microsoft Word
+ Microsoft Excel
+ Microsoft PowerPoint
+ Microsoft Outlook
+ Microsoft OneDrive

For more information, see the [full list of Microsoft 365 Apps for enterprise](https://www.microsoft.com/en/microsoft-365/enterprise/microsoft-365-apps-for-enterprise-product?activetab=pivot%3Aoverviewtab&market=af&ranMID=24542&ranEAID=QKfOgZNb5HA&ranSiteID=QKfOgZNb5HA-uvIr8evP5gLQf8n3Z0NLJA&epi=QKfOgZNb5HA-uvIr8evP5gLQf8n3Z0NLJA&irgwc=1&OCID=AIDcmm549zy227_aff_7593_1243925&tduid=%28ir__caugvllhggkfbgesuvvv2g21je2xb3afmz3ilkpl00%29%287593%29%281243925%29%28QKfOgZNb5HA-uvIr8evP5gLQf8n3Z0NLJA%29%28%29&irclickid=_caugvllhggkfbgesuvvv2g21je2xb3afmz3ilkpl00).

You can also install Microsoft applications not included with Microsoft 365, such as Microsoft Project, Microsoft Visio, and Microsoft Power Automate on WorkSpaces but you need to bring in your own additional licenses. 

You can install and use Microsoft 365 and other Microsoft applications on primary WorkSpaces and failover WorkSpaces using [Multi-Region Resilience](https://docs.aws.amazon.com/workspaces/latest/adminguide/multi-region-resilience.html).

**Topics**
+ [Create WorkSpaces with Microsoft 365 Apps for enterprise](#create-workspaces-microsoft365)
+ [Migrate your existing WorkSpaces to use Microsoft 365 Apps for enterprise](#migrate-workspaces-microsoft365)
+ [Update your Microsoft 365 Apps for enterprise on WorkSpaces](#microsoft365-update)

## Create WorkSpaces with Microsoft 365 Apps for enterprise
<a name="create-workspaces-microsoft365"></a>

To create WorkSpaces with Microsoft 365 Apps for enterprise, you must create a custom image with the applications installed, and use it to create a custom bundle. You can use the bundle to launch new WorkSpaces that have the applications installed. WorkSpaces does not provide public bundles with Microsoft 365 Apps for enterprise.

**To create WorkSpaces with Microsoft 365 Apps for enterprise:**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. Launch a WorkSpace that you want to use as the image for other Microsoft application WorkSpaces. This is where you will install your Microsoft applications. For more information about launching a WorkSpace, see [Launch a virtual desktop using WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html). 

1. Start the client application at [https://clients.amazonworkspaces.com/](https://clients.amazonworkspaces.com/), enter the registration code from your invitation email, and choose **Register**.

1. When prompted to sign in, enter the user's sign-in credentials, and then choose **Sign In**.

1. Install and configure your Microsoft 365 Apps for enterprise.

1. Create a custom image from the WorkSpace, and use it to create a custom bundle. For more information about creating custom images and bundles, see [Create a custom WorkSpaces image and bundle](https://docs.aws.amazon.com/workspaces/latest/adminguide/create-custom-bundle.html).

1. Launch WorkSpaces using the custom bundle that you created. These WorkSpaces have Microsoft 365 Apps for enterprise installed.

## Migrate your existing WorkSpaces to use Microsoft 365 Apps for enterprise
<a name="migrate-workspaces-microsoft365"></a>

If your WorkSpaces don't have a Microsoft Office license through AWS, you can install and configure Microsoft 365 Apps for enterprise on your WorkSpaces. 

 If your WorkSpaces do have a Microsoft Office license through AWS, you must first deregister your Microsoft Office license before installing Microsoft 365 Apps for enterprise. 

**Important**  
Uninstalling Microsoft Office applications from your WorkSpaces doesn't deregister the licenses. To avoid being charged for Microsoft Office licenses, deregister your WorkSpaces from Microsoft Office applications through AWS by doing either of the following:  
 **Manage applications** (recommended) – You can uninstall Microsoft Office version licenses from your WorkSpaces. For more information, see [Manage applications](manage-applications). After you uninstall, you can install Microsoft 365 Apps for enterprise on your WorkSpaces. 
 **Migrate a WorkSpace** – You can migrate a WorkSpace from one bundle to another while retaining the data on the user volume.   
Migrate your WorkSpaces to a bundle with an image that doesn’t have a Microsoft Office subscription. After the migration is complete, you can install Microsoft 365 Apps for enterprise on your WorkSpaces.
Or, create a custom WorkSpaces image and bundle that already has Microsoft 365 Apps for enterprise installed on the image, and then migrate your WorkSpaces to this new custom bundle. After migration is complete, your WorkSpaces users can start using Microsoft 365 Apps for enterprise.
For more information on how to migrate WorkSpaces, see [Migrate a WorkSpace](migrate-workspaces).

## Update your Microsoft 365 Apps for enterprise on WorkSpaces
<a name="microsoft365-update"></a>

By default, your WorkSpaces running on the Microsoft Windows Operating System are configured to receive updates from Windows Update. However, updates for Microsoft 365 Apps for enterprise aren't available using Windows Update. Set up updates to run automatically from the Office CDN, or use Windows Server Update Services (WSUS) in conjunction with Microsoft Configuration Manager to update Microsoft 365 Apps for enterprise. For more information, see [ Manage updates to Microsoft 365 Apps with Microsoft Configuration Manager](https://learn.microsoft.com/en-us/deployoffice/updates/manage-microsoft-365-apps-updates-configuration-manager). To set the frequency of Microsoft 365 application updates, specify an update channel and set it to Current or Monthly Enterprise to comply with the Microsoft 365 on WorkSpaces licensing policy.

# Upgrade Windows BYOL WorkSpaces in WorkSpaces Personal
<a name="upgrade-windows-10-byol-workspaces"></a>

On your Windows Bring Your Own License (BYOL) WorkSpaces, you can upgrade to a newer version of Windows using the in-place upgrade process. Follow the instructions in this topic to do so.

The in-place upgrade process applies only to Windows 10 and 11 BYOL WorkSpaces.

**Important**  
Do not run Sysprep on an upgraded WorkSpace. If you do so, an error that prevents Sysprep from finishing might occur. If you plan to run Sysprep, do so only on a WorkSpace that hasn't been upgraded.

**Note**  
You can use this process to upgrade your Windows 10 and 11 WorkSpaces to a newer version. However, this process cannot be used to upgrade your Windows 10 WorkSpaces to Windows 11.

**Topics**
+ [Prerequisites](#upgrade_byol_prerequisites)
+ [Considerations](#upgrade_byol_important_considerations)
+ [Known limitations](#byol-known-limitations)
+ [Summary of registry key settings](#upgrade_byol_registry_summary)
+ [Perform an in-place upgrade](#upgrade_byol_procedure)
+ [Troubleshooting](#byol-troubleshooting)
+ [Update your WorkSpace registry using a PowerShell script](#update-windows-10-byol-script)

## Prerequisites
<a name="upgrade_byol_prerequisites"></a>
+ If you have deferred or paused Windows 10 and 11 upgrades by using Group Policy or System Center Configuration Manager (SCCM), enable operating system upgrades for your Windows 10 and 11 WorkSpaces.
+ If the WorkSpace is an AutoStop WorkSpace, change it to an AlwaysOn WorkSpace before the in-place upgrade process so that it won't stop automatically while updates are being applied. For more information, see [Modify the running mode](running-mode.md#modify-running-mode). If you prefer to keep the WorkSpace set to AutoStop, change the AutoStop time to three hours or more while the upgrade takes place.
+ The in-place upgrade process recreates the user profile by making a copy of a special profile named Default User (`C:\Users\Default`). Do not use this default user profile to make customizations. We recommend making any customizations to the user profile through Group Policy Objects (GPOs) instead. Customizations made through GPOs can be easily modified or rolled back and are less prone to error.
+ The in-place upgrade process can back up and recreate only one user profile. If you have multiple user profiles on drive D, delete all the profiles except for the one that you need.

## Considerations
<a name="upgrade_byol_important_considerations"></a>

The in-place upgrade process uses two registry scripts (`enable-inplace-upgrade.ps1` and `update-pvdrivers.ps1`) to make the necessary changes to your WorkSpaces that enable the Windows Update process to run. These changes involve creating a (temporary) user profile on drive C instead of drive D. If a user profile already exists on drive D, the data in that original user profile remains on drive D.

By default, WorkSpaces creates the user profile in `D:\Users\%USERNAME%`. The `enable-inplace-upgrade.ps1` script configures Windows to create a new user profile in `C:\Users\%USERNAME%` and redirects the user shell folders to `D:\Users\%USERNAME%`. This new user profile is created when a user logs on the first time.

After the in-place upgrade, you have the choice of leaving your user profiles on drive C to allow your users to use the Windows Update process to upgrade their machines in the future. However, be aware that WorkSpaces with profiles stored on drive C can't be rebuilt or migrated without losing all of the data in the user's profile unless you back up and restore that data yourself. If you decide to leave the profiles on drive C, you can use the **UserShellFoldersRedirection** registry key to redirect the user shell folders to drive D, as explained later in this topic.

To ensure that you can rebuild or migrate your WorkSpaces and to avoid any potential problems with user shell folder redirection, we recommend that you choose to restore your user profiles to drive D after the in-place upgrade. You can do so by using the **PostUpgradeRestoreProfileOnD** registry key, as explained later in this topic. 

## Known limitations
<a name="byol-known-limitations"></a>
+ The user profile location change from drive D to drive C does not happen during WorkSpace rebuilds or migrations. If you perform an in-place upgrade on a Windows 10 or 11 BYOL WorkSpace and then rebuild or migrate it, the new WorkSpace will have the user profile on drive D.
**Warning**  
If you leave the user profile on drive C after the in-place upgrade, the user profile data stored on drive C will be lost during rebuilds or migrations unless you manually back up the user profile data prior to rebuilding or migrating, and then manually restore the user profile data after running the rebuild or migration process.
+ If your default BYOL bundle contains an image that is based on an earlier release of Windows 10 and 11, you must perform the in-place upgrade again after the WorkSpace is rebuilt or migrated.

## Summary of registry key settings
<a name="upgrade_byol_registry_summary"></a>

To enable the in-place upgrade process and to specify where you would like the user profile to be after the upgrade, you must set a number of registry keys.


**Registry path: **HKLM:\$1Software\$1Amazon\$1WorkSpacesConfig\$1enable-inplace-upgrade.ps1****  

| Registry key | Type | Values | 
| --- | --- | --- | 
| Enabled | DWORD |  **0** – (Default) Disables in-place upgrade **1** – Enables in-place upgrade  | 
| PostUpgradeRestoreProfileOnD | DWORD |  **0** – (Default) Does not attempt to restore the user profile path after the in-place upgrade **1** – Restores the user profile path (**ProfileImagePath**) after the in-place upgrade  | 
| UserShellFoldersRedirection | DWORD |  **0** – Does not enable redirection of user shell folders **1** – (Default) Enables redirection of user shell folders to `D:\Users\%USERNAME%` after the user profile is regenerated on `C:\Users\%USERNAME%`  | 
| NoReboot | DWORD |  **0** – (Default) Allows you to control when a reboot occurs after modifying the registry for the user profile **1** – Does not allow the script to reboot the WorkSpace after modifying the registry for the user profile  | 


**Registry path: **HKLM:\$1Software\$1Amazon\$1WorkSpacesConfig\$1update-pvdrivers.ps1****  

| Registry key | Type | Values | 
| --- | --- | --- | 
| Enabled | DWORD |  **0** – (Default) Disables AWS PV drivers update **1** – Enables AWS PV drivers update  | 

## Perform an in-place upgrade
<a name="upgrade_byol_procedure"></a>

To enable in-place Windows upgrades on your BYOL WorkSpaces, you must set certain registry keys, as described in the following procedure. You must also set certain registry keys to indicate the drive (C or D) where you want the user profiles to be after the in-place upgrades are finished.

You can make these registry changes manually. If you have multiple WorkSpaces to update, you can use Group Policy or SCCM to push a PowerShell script. For a sample PowerShell script, see [Update your WorkSpace registry using a PowerShell script](#update-windows-10-byol-script).

**To perform an in-place upgrade of Windows 10 and 11**

1. Make note of which version of Windows is currently running on the Windows 10 and 11 BYOL WorkSpaces that you are updating, and then reboot them.

1. Update the following Windows system registry keys to change the value data for **Enabled** from **0** to **1**. These registry changes enable in-place upgrades for the WorkSpace.
   + **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1WorkSpacesConfig\$1enable-inplace-upgrade.ps1**
   + **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1WorkSpacesConfig\$1update-pvdrivers.ps1**
**Note**  
If these keys do not exist, reboot the WorkSpace. The keys should be added when the system is rebooted.

   (Optional) If you are using a managed workflow such as SCCM Task Sequences to perform the upgrade, set the following key value to **1** to prevent the computer from rebooting:

   **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1WorkSpacesConfig\$1enable-inplace-upgrade.ps1\$1NoReboot**

1. Decide which drive you want user profiles to be on after the in-place upgrade process (for more information, see [Considerations](#upgrade_byol_important_considerations)), and set the registry keys as follows:
   + Settings if you want the user profile on drive C after the upgrade:

     **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1WorkSpacesConfig\$1enable-inplace-upgrade.ps1**

     Key name: **PostUpgradeRestoreProfileOnD**

     Key value: **0**

     Key name: **UserShellFoldersRedirection**

     Key value: **1**
   + Settings if you want the user profile on drive D after the upgrade:

     **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1WorkSpacesConfig\$1enable-inplace-upgrade.ps1**

     Key name: **PostUpgradeRestoreProfileOnD**

     Key value: **1**

     Key name: **UserShellFoldersRedirection**

     Key value: **0**

1. After saving the changes to the registry, reboot the WorkSpace again so that the changes are applied.
**Note**  
After the reboot, logging in to the WorkSpace creates a new user profile. You might see placeholder icons in the **Start** menu. This behavior is automatically resolved after the in-place upgrade is complete.
Allow 10 minutes to ensure that the WorkSpace is unblocked.

   (Optional) Confirm that the following key value is set to **1**, which unblocks the WorkSpace for updating:

   **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1WorkSpacesConfig\$1enable-inplace-upgrade.ps1\$1profileImagePathDeleted**

1. Perform the in-place upgrade. You can use whichever method you like, such as SCCM, ISO, or Windows Update (WU). Depending on your original Windows 10 and 11 version and how many apps were installed, this process can take from 40 to 120 minutes.
**Note**  
The in-place upgrade process may take at least an hour. The WorkSpace instance status may appear as `UNHEALTHY` during the upgrade.

1. After the update process is finished, confirm that the Windows version has been updated.
**Note**  
If the in-place upgrade fails, Windows automatically rolls back to use the Windows 10 and 11 version that was in place before you started the upgrade. For more information about troubleshooting, see the [Microsoft documentation](https://docs.microsoft.com/en-us/windows/deployment/upgrade/resolve-windows-10-upgrade-errors).

   (Optional) To confirm that the update scripts have been run successfully, verify that the following key value is set to **1**:

   **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1WorkSpacesConfig\$1enable-inplace-upgrade.ps1\$1scriptExecutionComplete**

1. If you modified the running mode of the WorkSpace by setting it to AlwaysOn or by changing the AutoStop time period so that the in-place upgrade process could run without interruption, set the running mode back to your original settings. For more information, see [Modify the running mode](running-mode.md#modify-running-mode).

If you haven't set the **PostUpgradeRestoreProfileOnD** registry key to **1**, the user profile is regenerated by Windows and placed in `C:\Users\%USERNAME%` after the in-place upgrade, so that you do not have to go through the above steps again for future Windows 10 and 11 in-place upgrades. By default, the `enable-inplace-upgrade.ps1` script redirects the following shell folders to drive D:
+ `D:\Users\%USERNAME%\Downloads`
+ `D:\Users\%USERNAME%\Desktop`
+ `D:\Users\%USERNAME%\Favorites`
+ `D:\Users\%USERNAME%\Music`
+ `D:\Users\%USERNAME%\Pictures`
+ `D:\Users\%USERNAME%\Videos`
+ `D:\Users\%USERNAME%\Documents`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Network Shortcuts`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Printer Shortcuts`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Start Menu\Programs`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Recent`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\SendTo`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Start Menu`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup`
+ `D:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Templates`

If you redirect the shell folders to other locations on your WorkSpaces, perform the necessary operations on the WorkSpaces after the in-place upgrades.

## Troubleshooting
<a name="byol-troubleshooting"></a>

If you encounter any issues with the update, you can check the following items to assist with troubleshooting:
+ Windows Logs, which are located, by default, in the following locations:

  `C:\Program Files\Amazon\WorkSpacesConfig\Logs\`

  `C:\Program Files\Amazon\WorkSpacesConfig\Logs\TRANSMITTED`
+ Windows Event Viewer

  Windows Logs > Application > Source: Amazon WorkSpaces

**Tip**  
During the in-place upgrade process, if you see that some icon shortcuts on the desktop no longer work, it's because WorkSpaces moves any user profiles located on drive D to drive C to prepare for the upgrade. After the upgrade is completed, the shortcuts will work as expected.

### Windows 11 24H2 Upgrade using ISO error resolution
<a name="upgrade-iso-resolution"></a>

The Windows 11 24H2 upgrade process may encounter a critical boot failure during the second boot phase, specifically presenting error code 0xC1900101 - 0x40017. This error typically occurs due to a missing or corrupted system driver file that prevents the installation from completing successfully during the boot operation phase.

*Error Code:*0xC1900101 - 0x40017

*Error Description:*Installation failure during SECOND\$1BOOT phase with BOOT operation error

1. Ensure you have the Windows 11 24H2 ISO file.

1. Open a command prompt as administrator.

1. Copy the required system file using this command:

   ```
   copy "ISO-Drive:\Sources\WinSetupMon.sys" "C:\Windows\System32\Drivers\"
   ```

   Replace **ISO-Drive** with your ISO drive information.

1. Verify the file copy by using:

   ```
   C:\Windows\System32\Drivers\
   ```

1. Initiate Windows 11 24H2 upgrade using the ISO file.

## Update your WorkSpace registry using a PowerShell script
<a name="update-windows-10-byol-script"></a>

You can use the following sample PowerShell script to update the registry on your WorkSpaces to enable in-place upgrades. Follow the [Perform an in-place upgrade](#upgrade_byol_procedure), but use this script to update the registry on each WorkSpace.

```
# AWS WorkSpaces 1.28.20
# Enable In-Place Update Sample Scripts
# These registry keys and values will enable scripts to run on the next reboot of the WorkSpace.
 
$scriptlist = ("update-pvdrivers.ps1","enable-inplace-upgrade.ps1")
$wsConfigRegistryRoot="HKLM:\Software\Amazon\WorkSpacesConfig"
$Enabled = 1
$script:ErrorActionPreference = "Stop"
 
foreach ($scriptName in $scriptlist)
{
    $scriptRegKey = "$wsConfigRegistryRoot\$scriptName"
    
    try
    {
        if (-not(Test-Path $scriptRegKey))
        {        
            Write-Host "Registry key not found. Creating registry key '$scriptRegKey' with 'Update' enabled."
            New-Item -Path $wsConfigRegistryRoot -Name $scriptName | Out-Null
            New-ItemProperty -Path $scriptRegKey -Name Enabled -PropertyType DWord -Value $Enabled | Out-Null
            Write-Host "Value created. '$scriptRegKey' Enabled='$((Get-ItemProperty -Path $scriptRegKey).Enabled)'"
        }
        else
        {
            Write-Host "Registry key is already present with value '$scriptRegKey' Enabled='$((Get-ItemProperty -Path $scriptRegKey).Enabled)'"
            if((Get-ItemProperty -Path $scriptRegKey).Enabled -ne $Enabled)
            {
                Set-ItemProperty -Path $scriptRegKey -Name Enabled -Value $Enabled
                Write-Host "Value updated. '$scriptRegKey' Enabled='$((Get-ItemProperty -Path $scriptRegKey).Enabled)'"
            }
        }
    }
    catch
    {
        write-host "Stopping script, the following error was encountered:" `r`n$_ -ForegroundColor Red
        break
    }
}
```

# Migrate a WorkSpace in WorkSpaces Personal
<a name="migrate-workspaces"></a>

**Note**  
If you want to unsubscribe from or uninstall Microsoft Office version licenses through AWS from your WorkSpace, we recommend using [Manage applications](manage-applications).

You can migrate a WorkSpace from one bundle to another, while retaining the data on the user volume. The following are example scenarios:
+ You can migrate WorkSpaces from the Windows 7 desktop experience to the Windows 10 desktop experience.
+ You can migrate WorkSpaces from the PCoIP protocol to DCV.
+ You can migrate WorkSpaces from the 32-bit Microsoft Office on Windows Server 2016-powered WorkSpaces bundle to the 64-bit Microsoft Office on Windows Server 2019 and Windows Server 2022-powered WorkSpaces bundles.
+ You can migrate WorkSpaces from one public or custom bundle to another. For example, you can migrate from GPU-enabled (Graphics.g6, Graphics.g4dn. GraphicsPro.g4dn, Graphics, and GraphicsPro) bundles to non-GPU-enabled bundles, as well as in the other direction.
+ You can migrate WorkSpaces from the Windows 10 BYOL to the Windows 11 BYOL but migration from Windows 11 to Windows 10 is not supported.
+ Value bundles are not supported on Windows 11. To migrate your Windows 7 or 10 value bundle WorkSpaces to Windows 11, you need to switch your Value WorkSpaces to a bigger bundle offering first. 
+ Before migrating WorkSpaces from Windows 7 to Windows 11, you need to migrate it to Windows 10. Log in to Windows 10 WorkSpace at least once before migrating it to Windows 11. Migrating from Windows 7 WorkSpaces directly to Windows 11 is not supported.
+ You can migrate Windows WorkSpaces that use Microsoft Office through AWS to a custom WorkSpaces bundle with Microsoft 365 applications. After the migration, your WorkSpaces are unsubscribed from Microsoft Office.
+ You can migrate Windows WorkSpaces that use Microsoft Office through AWS to a WorkSpaces bundle with no Office 2016/2019 subscription. After the migration, your WorkSpaces are unsubscribed from Microsoft Office.
+ You can migrate BYOL BYOP WorkSpaces from Windows 10 to Windows 11, and license-included BYOP WorkSpaces from Windows Server 2019 to Windows Server 2022.
+ You can migrate any Windows Server powered WorkSpace bundle to Windows Server 2025. Once migrated, you will be using DCV streaming protocol to enable high-performance remote desktop streaming, even with graphics-intensive applications, over varying network conditions, even with less powerful client devices.
+ You can migrate any Windows Server license-included BYOP WorkSpace bundle to BYOP Windows Server 2025. 

For more information about Amazon WorkSpaces bundles, see [Bundles and images for WorkSpaces Personal](amazon-workspaces-bundles.md).

The migration process recreates the WorkSpace by using a new root volume from the target bundle image and the user volume from the last available snapshot of the original WorkSpace. A new user profile is generated during migration for better compatibility. The old user profile is renamed, and then certain files in the old user profile are moved to the new user profile. (For details about what gets moved, see [What happens during migration](#during-migration).)

The migration process takes up to one hour per WorkSpace. When you initiate the migration process, a new WorkSpace is created. If an error occurs that prevents successful migration, the original WorkSpace is recovered and returned to its original state, and the new WorkSpace is terminated.

**Contents**
+ [Migration limits](#migration-limits)
+ [Migration scenarios](#migration-scenarios)
+ [What happens during migration](#during-migration)
+ [Best practices](#migration-best-practices)
+ [Troubleshooting](#migration_troubleshooting)
+ [How billing is affected](#migration-billing)
+ [Migrating a WorkSpace](#migration-workspaces)

## Migration limits
<a name="migration-limits"></a>
+ You cannot migrate to a public or custom Windows 7 desktop experience bundle. You also cannot migrate to Bring Your Own License (BYOL) Windows 7 bundles.
+ You can migrate BYOL WorkSpaces only to other BYOL bundles. To migrate a BYOL WorkSpace from PCoIP to DCV, you must first create a BYOL bundle with the DCV protocol. You can then migrate your PCoIP BYOL WorkSpaces to that DCV BYOL bundle. 
+ You cannot migrate a WorkSpace created from public or custom bundles to a BYOL bundle.
+ DCV Protocol supports Graphics G6 bundles, Graphics.g4dn, and GraphicsPro.g4dn on Windows. On Ubuntu, only Graphics.g4dn and GraphicsPro.g4dn are available.
+ PCoIP Protocol supports Graphics.g4dn and GraphicsPro.g4dn bundles on Windows only.
+ Migrating Linux WorkSpaces is not currently supported.
+ In AWS Regions that support more than one language, you can migrate WorkSpaces between language bundles.
+ The source and target bundles must be different. (However, in Regions that support more than one language, you can migrate to the same Windows 10 bundle as long as the languages differ.) If you want to refresh your WorkSpace using the same bundle, [rebuild the WorkSpace](rebuild-workspace.md) instead.
+ You cannot migrate WorkSpaces across Regions.
+ In some cases, if migration is unable to finish successfully, you might not receive an error message, and it might appear that the migration process did not start. If the WorkSpace bundle remains the same one hour after attempting migration, the migration is unsuccessful. Contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) for assistance.
+ You cannot migrate BYOP WorkSpaces to PCoIP or DCV WorkSpaces.
+ You cannot migrate Active Directory domain-joined WorkSpaces to Microsoft Entra-joined WorkSpaces.

## Migration scenarios
<a name="migration-scenarios"></a>

The following table shows which migration scenarios are available:


| Source OS | Target OS | Available? | 
| --- | --- | --- | 
|  Public or custom bundle Windows 7  |  Public or custom bundle Windows 10  |  Yes  | 
|  Custom bundle Windows 7  |  Public bundle Windows 7  |  No  | 
|  Custom bundle Windows 7  |  Custom bundle Windows 7  |  No  | 
|  Public bundle Windows 7  |  Custom bundle Windows 7  |  No  | 
|  Public or custom bundle Windows 10  |  Public or custom bundle Windows 7  |  No  | 
|  Public or custom bundle Windows 10  |  Custom bundle Windows 10  |  Yes  | 
|  Windows 7 BYOL bundle  |  Windows 7 BYOL bundle  | No | 
| Windows 7 BYOL bundle |  Windows 10 BYOL bundle  |  Yes  | 
|  Windows 10 BYOL bundle  |  Windows 7 BYOL bundle  |  No  | 
|  Windows 10 BYOL bundle  |  Windows 10 BYOL bundle  |  Yes  | 
|  Windows Server 2016-powered Public Windows 10 bundle  |  Windows Server 2019-powered Public Windows 10 bundle  |  Yes  | 
|  Windows Server 2019-powered Public Windows 10 bundle  |  Windows Server 2016-powered Public Windows 10 bundle  |  Yes  | 
|  Windows 10 BYOL bundle  |  Windows 11 BYOL bundle  |  Yes  | 
|  Windows 11 BYOL bundle  |  Windows 10 BYOL bundle  |  No  | 
|  Windows Server 2016-powered custom Windows 10 bundle  |  Windows Server 2019-powered Public Windows 10 bundle  |  Yes  | 
|  Windows Server 2016-powered custom Windows 10 bundle  |  Windows Server 2022-powered Public Windows 10 bundle  |  Yes  | 
|  Windows Server 2019-powered custom Windows 10 bundle  |  Windows Server 2022-powered Public Windows 10 bundle  |  Yes  | 
| Windows 10 BYOP BYOL | Windows 11 BYOP BYOL | Yes | 
| Windows 11 BYOP BYOL | Windows 10 BYOP BYOL | No | 
| Windows Server 2019-powered Public BYOP  | Windows Server 2022-powered Public BYOP  | Yes | 
| Windows Server 2022-powered Public BYOP  | Windows Server 2019-powered Public BYOP  | No | 
| Windows Server 2019-powered Public BYOP  | Windows Server 2025-powered Public BYOP  | Yes | 
| Windows Server 2025-powered Public BYOP  | Windows Server 2019-powered Public BYOP  | No | 
| Windows Server 2022-powered Public BYOP  | Windows Server 2025-powered Public BYOP  | Yes | 
| Windows Server 2025-powered Public BYOP  | Windows Server 2022-powered Public BYOP  | No | 
| Windows Server 2019-powered Public Windows 10 bundle  | Windows Server 2025-powered Public BYOP  | Yes | 
| Windows Server 2019-powered Custom Windows 10 bundle  | Windows Server 2025-powered Public BYOP  | Yes | 
| Windows Server 2022-powered Public Windows 10 bundle  | Windows Server 2025-powered Public BYOP  | Yes | 
| Windows Server 2022-powered Custom Windows 10 bundle  | Windows Server 2025-powered Public BYOP  | Yes | 

**Note**  
Web access is not available for the Windows Server 2019-powered Public Windows 10 bundle PCoIP branch.

## What happens during migration
<a name="during-migration"></a>

During migration, the data on the user volume (drive D) is preserved, but all of the data on the root volume (drive C) is lost. This means that none of the installed applications, settings, and changes to the registry are preserved. The old user profile folder is renamed with the `.NotMigrated` suffix, and a new user profile is created.

The migration process recreates drive D based on the last snapshot of the original user volume. During the first boot of the new WorkSpace, the migration process moves the original `D:\Users\%USERNAME%` folder to a folder named `D:\Users\%USERNAME%MMddyyTHHmmss%.NotMigrated`. A new `D:\Users\%USERNAME%\` folder is generated by the new OS.

After the new user profile is created, the files in the following user shell folders are moved from the old `.NotMigrated` profile to the new profile:
+ `D:\Users\%USERNAME%\Desktop`
+ `D:\Users\%USERNAME%\Documents`
+ `D:\Users\%USERNAME%\Downloads`
+ `D:\Users\%USERNAME%\Favorites`
+ `D:\Users\%USERNAME%\Music`
+ `D:\Users\%USERNAME%\Pictures`
+ `D:\Users\%USERNAME%\Videos`

**Important**  
The migration process attempts to move the files from the old user profile to the new profile. Any files that weren't moved during migration remain in the `D:\Users\%USERNAME%MMddyyTHHmmss%.NotMigrated` folder. If the migration is successful, you can see which files got moved in `C:\Program Files\Amazon\WorkspacesConfig\Logs\MigrationLogs`. You can manually move any files that didn't get moved automatically.  
By default, the public bundles have local search indexing disabled. If you were to enable it, the default is to search `C:\Users` and not `D:\Users`, so you need to adjust that as well. If you've set local search indexing specifically to `D:\Users\username` and not to `D:\Users`, then local search indexing might not work post-migration for any user files that are in the `D:\Users\%USERNAME%MMddyyTHHmmss%.NotMigrated` folder.

Any tags assigned to the original WorkSpace are carried over during migration, and the running mode of the WorkSpace is preserved. However, the new WorkSpace gets a new WorkSpace ID, computer name, and IP address.

## Best practices
<a name="migration-best-practices"></a>

Before you migrate a WorkSpace, do the following:
+ Back up any important data on drive C to another location. All data on drive C is erased during migration.
+ Make sure that the WorkSpace being migrated is at least 12 hours old, to ensure that a snapshot of the user volume has been created. On the **Migrate WorkSpaces** page in the Amazon WorkSpaces console, you can see the time of the last snapshot. Any data created after the last snapshot is lost during migration.
+ To avoid potential data loss, make sure that your users log out of their WorkSpaces and don't log back in until after the migration process is finished. Note that WorkSpaces cannot be migrated when they are in `ADMIN_MAINTENANCE` mode.
+ Make sure that the WorkSpaces you want to migrate have a status of `AVAILABLE`, `STOPPED`, or `ERROR`.
+ Make sure that you have enough IP addresses for the WorkSpaces you are migrating. During migration, new IP addresses will be allocated for the WorkSpaces.
+ If you are using scripts to migrate WorkSpaces, migrate them in batches of no more than 25 WorkSpaces at a time.

## Troubleshooting
<a name="migration_troubleshooting"></a>
+ If your users report missing files after migration, check to see if their user profile files did not get moved during the migration process. You can see which files got moved in `C:\Program Files\Amazon\WorkspacesConfig\Logs\MigrationLogs`. The files that didn't get moved will be located in the `D:\Users\%USERNAME%MMddyyTHHmmss%.NotMigrated` folder. You can manually move any files that didn't get moved automatically. 
+ If you are using the API to migrate WorkSpaces and the migration does not succeed, the target WorkSpace ID returned by the API will not be used, and the WorkSpace will still have the original WorkSpace ID.
+ If a migration does not successfully finish, check the Active Directory to see if it was cleaned up accordingly. You might need to manually remove WorkSpaces that you no longer need.

## How billing is affected
<a name="migration-billing"></a>

During the month in which migration occurs, you are charged prorated amounts for both the new and the original WorkSpaces. For example, if you migrate WorkSpace A to WorkSpace B on May 10, you will be charged for WorkSpace A from May 1 to May 10, and you will be charged for WorkSpace B from May 11 to May 30.

**Note**  
If you are migrating a WorkSpace to a different bundle type (for example, from Performance to Power, or Value to Standard), the size of the root volume (drive C) and the user volume (drive D) might increase during the migration process. If necessary, the root volume increases to match the default root volume size for the new bundle. However, if you had already specified a different size (higher or lower) for the user volume than the default for the original bundle, that same user volume size is retained during the migration process. Otherwise, the migration process uses the larger of the source WorkSpace user volume size and the default user volume size for the new bundle.

## Migrating a WorkSpace
<a name="migration-workspaces"></a>

You can migrate WorkSpaces through the Amazon WorkSpaces console, the AWS CLI or the Amazon WorkSpaces API.

**To migrate a WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select your WorkSpace and choose **Actions**, **Migrate WorkSpaces**.

1. Under **Bundles**, select the bundle that you'd like to migrate your WorkSpace to.
**Note**  
To migrate a BYOL WorkSpace from PCoIP to DCV, you must first create a BYOL bundle with the DCV protocol. You can then migrate your PCoIP BYOL WorkSpaces to that DCV BYOL bundle. 

1. Choose **Migrate WorkSpaces**.

   A new WorkSpace with a status of `PENDING` appears in the Amazon WorkSpaces console. When the migration is finished, the original WorkSpace is terminated, and the status of the new WorkSpace is set to `AVAILABLE`.

1. (Optional) To delete any custom bundles and images that you no longer need, see [Delete a custom bundle or image in WorkSpaces Personal](delete_bundle.md).

To migrate WorkSpaces through the AWS CLI, use the [migrate-workspace](https://docs.aws.amazon.com/cli/latest/reference/workspaces/migrate-workspace.html) command. To migrate WorkSpaces through the Amazon WorkSpaces API, see [MigrateWorkSpace](https://docs.aws.amazon.com/workspaces/latest/api/API_MigrateWorkspace.html) in the *Amazon WorkSpaces API Reference*.

# Delete a WorkSpace in WorkSpaces Personal
<a name="delete-workspaces"></a>

When you are finished with a WorkSpace, you can delete it. You can also delete related resources.

**Warning**  
Deleting a WorkSpace is a permanent action and cannot be undone. The WorkSpace user's data does not persist and is destroyed. For help with backing up user data, contact AWS Support.

**Note**  
Simple AD and AD Connector are available to you free of charge to use with WorkSpaces. If there are no WorkSpaces being used with your Simple AD or AD Connector directory for 30 consecutive days, this directory will be automatically deregistered for use with Amazon WorkSpaces, and you will be charged for this directory as per the [AWS Directory Service pricing terms](https://aws.amazon.com/directoryservice/pricing/).  
To delete empty directories, see [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md). If you delete your Simple AD or AD Connector directory, you can always create a new one when you want to start using WorkSpaces again.

**To delete a WorkSpace**

You can delete a WorkSpace that is in any state except **Suspended**.

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select your WorkSpace and choose **Delete**.

1. When prompted for confirmation, choose **Delete WorkSpace**. It takes approximately 5 minutes to delete a WorkSpace. During deletion, the status of the WorkSpace is set to **Terminating**. When the deletion is complete, the WorkSpace disappears from the console.

1. (Optional) To delete any custom bundles and images that you are finished with, see [Delete a custom bundle or image in WorkSpaces Personal](delete_bundle.md).

1. (Optional) After you delete all WorkSpaces in a directory, you can delete the directory. For more information, see [Delete a directory for WorkSpaces Personal](delete-workspaces-directory.md).

1. (Optional) After you delete all resources in the virtual private cloud (VPC) for your directory, you can delete the VPC and release the Elastic IP address used for the NAT gateway. For more information, see [ Deleting your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#VPC_Deleting) and [ Working with Elastic IP addresses](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-eips.html#WorkWithEIPs) in the *Amazon VPC User Guide*.

**To delete a WorkSpace using the AWS CLI**  
Use the [terminate-workspaces](https://docs.aws.amazon.com/cli/latest/reference/workspaces/terminate-workspaces.html) command.

# Bundles and images for WorkSpaces Personal
<a name="amazon-workspaces-bundles"></a>

A *WorkSpace bundle* is a combination of an operating system, and storage, compute, and software resources. When you launch a WorkSpace, you select the bundle that meets your needs. The default bundles available for WorkSpaces are called *public bundles*. For more information about the various public bundles available for WorkSpaces, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles).

If you've launched a Windows or Linux WorkSpace and have customized it, you can create a custom image from that WorkSpace. 

A *custom image* contains only the OS, software, and settings for the WorkSpace. A *custom bundle* is a combination of both that custom image and the hardware from which a WorkSpace can be launched.

After you create a custom image, you can build a custom bundle that combines the custom WorkSpace image and the underlying compute and storage configuration that you select. You can then specify this custom bundle when you launch new WorkSpaces to ensure that the new WorkSpaces have the same consistent configuration (hardware and software). 

If you need to perform software updates or to install additional software on your WorkSpaces, you can update your custom bundle and use it to rebuild your WorkSpaces.

WorkSpaces supports several different operating systems (OS), streaming protocols, and bundles. The following table provides information about the licensing, streaming protocols, and bundles that are supported by each OS.


| Operating System | Licenses | Streaming protocols | Supported bundles | Lifecycle policy / retirement date | 
| --- | --- | --- | --- | --- | 
| Windows Server 2016 | Included | DCV, PCoIP | Value, Standard, Performance, Power, PowerPro, GraphicsPro, Graphics G4dn | [January 12, 2027](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2016) | 
| Windows Server 2019 | Included | DCV, PCoIP | Value, Standard, Performance, Power, PowerPro, GraphicsPro, Graphics G4dn | [January 9, 2029](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2019) | 
| Windows Server 2022 | Included | DCV, PCoIP | Standard, Performance, Power, PowerPro, GeneralPurpose, Graphics G4dn, Graphics G6 | [October 14, 2031](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2022) | 
| Windows Server 2025 | Included | DCV | Standard, Performance, Power, PowerPro, GeneralPurpose, Graphics G4dn, Graphics G6 | [November 14, 2034](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2025) | 
| Windows 10 | Bring Your Own License (BYOL) | DCV, PCoIP | Value, Standard, Performance, Power, PowerPro, GraphicsPro, Graphics G4dn | [In support](https://learn.microsoft.com/en-us/windows/release-health/release-information) | 
| Windows 11 | Bring Your Own License (BYOL) | DCV | Standard, Performance, Power, PowerPro, GeneralPurpose, Graphics G4dn, Graphics G6 | [In support](https://learn.microsoft.com/en-us/windows/release-health/windows11-release-information) | 
| Amazon Linux 2 | Included | DCV, PCoIP | Value, Standard, Performance, Power, PowerPro | [In support](https://aws.amazon.com/amazon-linux-2/faqs/) | 
| Ubuntu 22.04 LTS | Included | DCV | Value, Standard, Performance, Power, PowerPro, Graphics G4dn | [June, 2032](https://ubuntu.com/about/release-cycle) | 
| Rocky Linux 8 | Included | DCV | Value, Standard, Performance, Power, PowerPro | [May 31, 2029](https://ciq.com/services/long-term-support/) | 
| Red Hat Enterprise Linux 8 | Included | DCV | Value, Standard, Performance, Power, PowerPro | [May 31, 2029](https://access.redhat.com/support/policy/updates/errata) | 

**Note**  
Operating system versions that are no longer supported by the vender are not guaranteed to work and are not supported by AWS support.
For WorkSpaces running on Windows operating system, Graphics bundles only supports PCoIP streaming protocol.

**Topics**
+ [Bundle options for WorkSpaces Personal](bundle-options.md)
+ [Create a custom WorkSpaces image and bundle for WorkSpaces Personal](create-custom-bundle.md)
+ [Update a custom bundle for WorkSpaces Personal](update-custom-bundle.md)
+ [Copy a custom image in WorkSpaces Personal](copy-custom-image.md)
+ [Share or unshare a custom image in WorkSpaces Personal](share-custom-image.md)
+ [Delete a custom bundle or image in WorkSpaces Personal](delete_bundle.md)

# Bundle options for WorkSpaces Personal
<a name="bundle-options"></a>

Before selecting a bundle, ensure the bundle you want to select is compatible with your WorkSpaces' protocol, operating system, network, and compute type. For more information about protocols, see [Protocols for Amazon WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/amazon-workspaces-protocols.html). For more information about networks, see [Amazon WorkSpaces client network requirements](https://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-network-requirements.html). 

**Note**  
We recommend not exceeding a 250 ms maximum network latency for PCoIP WorkSpaces. To get the best PCoIP WorkSpaces user experience, we recommend keeping the network latency under 100 ms. When the round-trip time (RTT) exceeds 375 ms, the WorkSpaces client connection will shut down. For the best DCV user experience, we recommend keeping the RTT under 250 ms. If the RTT is between 250 ms and 400 ms, the user can access the WorkSpace, but performance will decrease significantly.
We recommend testing the performance of bundles you want to choose in a test environment by running and using applications that replicate your users' daily tasks.
BYOP (Bring Your Own Protocol) bundles are for WorkSpaces Core. The BYOP bundles provided by Amazon WorkSpaces don't have a WorkSpaces provided streaming protocol installed. You won't be able to connect using WorkSpaces clients or gateways. To understand the shared responsibility model for Amazon WorkSpaces Core, see the [ Technology Partner Integration Guide for Amazon WorkSpaces Core](chrome-extension://efaidnbmnnnibpcajpcglclefindmkaj/https://docs.aws.amazon.com/pdfs/workspaces-core/latest/pg/workspacescore-pg.pdf). For more information, see [ Amazon WorkSpaces Core](https://aws.amazon.com/workspaces-family/core/).

**Important**  
GraphicsPro bundle reaches end-of-life on October 31, 2025. We recommend migrating your GraphicsPro WorkSpaces to supported bundles before October 31, 2025. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md).
The Graphics bundle will no longer be supported after November 30, 2023. We recommend switching to a supported GPU enabled bundle for WorkSpaces using the Graphics bundle.
Graphics and GraphicsPro bundles aren't currently available in the Asia Pacific (Mumbai) Region.
Plus applications bundles with Office 2016 or Office 2019 will no longer be supported after October 14, 2025. We recommend migrating your WorkSpaces bundles with those Office version to use Office 2021 or Office 2024. For more information, see, [Manage applications in WorkSpaces Personal](manage-applications).

The following are the bundles that WorkSpaces offers. For information about bundles in WorkSpaces, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles).

## Value bundle
<a name="value"></a>

This bundle is well-suited for the following:
+ Basic text editing and data entry
+ Web browsing with light usage
+ Instant messaging

This bundle is not recommended for word processing, audio and video conferencing, screen sharing, software development tool, business intelligence applications, and graphics applications.

## Standard bundle
<a name="standard"></a>

This bundle is well-suited for the following:
+ Basic text editing and data entry
+ Web browsing
+ Instant messaging
+ Email

This bundle is not recommended for audio and video conferencing, screen sharing, word processing, software development tool, business intelligence applications, and graphics applications.

## Performance bundle
<a name="performance"></a>

This bundle is well-suited for the following:
+ Web browsing
+ Word processing
+ Instant messaging
+ Email
+ Spreadsheets
+ Audio processing
+ Courseware

This bundle is not recommended for video conferencing, screen sharing, software development tool, business intelligence applications, and graphics applications.

## Power bundle
<a name="power"></a>

This bundle is well-suited for the following:
+ Web browsing
+ Word processing
+ Email
+ Instant messaging
+ Spreadsheets
+ Audio processing
+ Software development (Integrated Development Environment (IDE))
+ Entry to mid-level data processing
+ Audio and video conferencing

This bundle is not recommended for screen sharing, software development tool, business intelligence applications, and graphics applications.

## PowerPro bundle
<a name="powerpro"></a>

This bundle is well-suited for the following:
+ Web browsing
+ Word processing
+ Email
+ Instant messaging
+ Spreadsheets
+ Audio processing
+ Software development (Integrated Development Environment (IDE))
+ Data warehousing
+ Business intelligence applications
+ Audio and video conferencing

This bundle is not recommended for machine learning model training, and graphics applications.

## General purpose bundles
<a name="generalpurpose"></a>

These bundles, including GeneralPurpose.4xlarge and GeneralPurpose.8xlarge, are well-suited for the following:
+ Web browsing
+ Word processing
+ Email
+ Instant messaging
+ Spreadsheets
+ Audio processing
+ Software development (Integrated Development Environment (IDE))
+ Data warehousing
+ Business intelligence applications
+ Audio and video conferencing
+ Batch processing
+ CPU-based ML (machine learning) model training

This bundle is not recommended for 3D rendering, photo-realistic design, game streaming, or ML model training for complex models.

## Graphics G6 bundles
<a name="graphicsg6"></a>

The G6 WorkSpace bundles utilize NVIDIA L4 GPUs with 3rd generation AMD EPYC (Milan) processors and are available in three variants: G6, Gr6, and G6f. The G6 WorkSpaces feature a standard 1:4 vCPU-to-memory ratio, providing balanced compute and memory resources for general graphics workloads. The Gr6 WorkSpaces offer a 1:8 vCPU-to-memory ratio, delivering double the memory per vCPU for graphics applications with higher memory requirements. The G6f WorkSpaces provide fractional GPU allocation, making them suitable for workloads that do not require full GPU processing capacity for computationally intensive operations. Refer to [Amazon EC2 G6 Instances page](https://aws.amazon.com/ec2/instance-types/g6/) for more information. The G6 WorkSpace bundles support all use cases that existing bundles support, such as daily tasks, data processing and analysis, audio conferencing and software development. Additionally, they enable the followiing use cases:
+ Graphic design
+ CAD/CAM (computer-aided design/computer-aided manufacturing)
+ Video transcoding
+ 3D rendering
+ Game streaming
+ ML (machine learning) model training and ML inference

## Graphics.g4dn bundle
<a name="graphicsg4dn"></a>

This bundle offers a high level of graphics performance, and moderate level of CPU performance and memory for your WorkSpaces and is well-suited for the following:
+ Web browsing
+ Word processing
+ Email
+ Spreadsheets
+ Instant messaging
+ Audio conferencing
+ Software development (Integrated Development Environment (IDE))
+ Entry to mid-level data processing
+ Data warehousing
+ Business intelligence applications
+ Graphic design
+ CAD/CAM (computer-aided design/computer-aided manufacturing)

This bundle is not recommended for audio and video conferencing, 3D rendering, photo-realistic design, and machine learning model training.

## GraphicsPro.g4dn bundle
<a name="graphicsprog4dn"></a>

This bundle offers a high level of graphics performance, CPU performance, and memory for your WorkSpaces and is well-suited for the following:
+ Web browsing
+ Word processing
+ Email
+ Spreadsheets
+ Instant messaging
+ Audio conferencing
+ Software development (Integrated Development Environment (IDE))
+ Entry to mid-level data processing
+ Data warehousing
+ Business intelligence applications
+ Graphic design
+ CAD/CAM (computer-aided design/computer-aided manufacturing)
+ Video transcoding
+ 3D rendering
+ Photo-realistic design
+ Game streaming
+ ML (machine learning) model training and ML inference

This bundle is not recommended for audio and video conferencing.

# Create a custom WorkSpaces image and bundle for WorkSpaces Personal
<a name="create-custom-bundle"></a>

If you've launched a Windows or Linux WorkSpace and have customized it, you can create a custom image and custom bundles from that WorkSpace.

A *custom image* contains only the OS, software, and settings for the WorkSpace. A *custom bundle* is a combination of both that custom image and the hardware from which a WorkSpace can be launched.

**Note**  
Ensure you wait at least 2 hours after deleting a bundle before creating a new bundle with the same name.

After you create a custom image, you can build a custom bundle that combines the custom image and the underlying compute and storage configuration that you select. You can then specify this custom bundle when you launch new WorkSpaces to ensure that the new WorkSpaces have the same consistent configuration (hardware and software).

You can use the same custom image to create various custom bundles by selecting different compute and storage options for each bundle. <a name="important_note"></a>

**Important**  
If you plan to create an image from a Windows 10 WorkSpace, note that image creation is not supported on Windows 10 systems that have been upgraded from one version of Windows 10 to a newer version of Windows 10 (a Windows feature/version upgrade). However, Windows cumulative or security updates are supported by the WorkSpaces image-creation process.
After January 14, 2020, images cannot be created from public Windows 7 bundles. You might want to consider migrating your Windows 7 WorkSpaces to Windows 10. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md).
The Graphics bundle is no longer supported as of November 30, 2023, and the GraphicsPro bundle reaches end-of-life on October 31, 2025. We recommend migrating your WorkSpaces to a supported GPU bundle. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md).
GraphicsPro bundle reaches end-of-life on October 31, 2025. We recommend migrating your GraphicsPro WorkSpaces to supported GPU bundle before October 31, 2025. For more information, see [Migrate a WorkSpace in WorkSpaces Personal](migrate-workspaces.md).
Custom bundle storage volumes can't be smaller than image storage volumes.
Plus applications bundles with Office 2016 or Office 2019 will no longer be supported after October 14, 2025. We recommend migrating your WorkSpaces bundles with those Office version to use Office 2021. For more information, see, [Manage applications in WorkSpaces Personal](manage-applications).

Custom bundles cost the same as the public bundles they are created from. For more information about pricing, see [Amazon WorkSpaces Pricing](https://aws.amazon.com/workspaces/pricing/).

**Topics**
+ [Requirements to create Windows custom images](#windows_custom_image_requirements)
+ [Requirements to create Linux custom images](#linux_custom_image_requirements)
+ [Best practices](#custom_image_best_practices)
+ [(Optional) Step 1: Specify a custom computer name format for your image](#custom_computer_name)
+ [Step 2: Run the Image Checker](#run_image_checker)
+ [Step 3: Create a custom image and custom bundle](#create_custom_image_bundle)
+ [What's included with Windows WorkSpaces custom images](#image_creation_windows)
+ [What's included with Linux WorkSpace custom images](#image_creation_linux)

## Requirements to create Windows custom images
<a name="windows_custom_image_requirements"></a>

**Note**  
Windows currently defines 1 GB as 1,073,741,824 bytes. Customers will need to ensure they have greater than 12,884,901,888 bytes (or 12 GiB) free on C drive and the user profile is less than 10,737,418,240 bytes (or 10 GiB) to create an image of a WorkSpace.
+ The status of the WorkSpace must be **Available** and its modification state must be **None**.
+ All applications and user profiles on WorkSpaces images must be compatible with Microsoft Sysprep.
+ All applications to include in the image must be installed on the `C` drive.
+ For Windows 7 WorkSpaces, and its total size (files and data) must be less than 10 GB.
+ For Windows 7 WorkSpaces, the `C` drive must have at least 12 GB of available space.
+ All application services running on the WorkSpace must use a local system account instead of domain user credentials. For example, you cannot have a Microsoft SQL Server Express installation running with a domain user's credentials.
+ The WorkSpace must not be encrypted. Image creation from an encrypted WorkSpace is not currently supported.
+ The following components are required in an image. Without these components, the WorkSpaces that you launch from the image will not function correctly. For more information, see [Required configuration and service components for WorkSpaces Personal](required-service-components.md).
  + Windows PowerShell version 3.0 or later
  + Remote Desktop Services
  + AWS PV drivers
  + Windows Remote Management (WinRM)
  + Teradici PCoIP agents and drivers
  + STXHD agents and drivers
  + AWS and WorkSpaces certificates
  + Skylight agent

## Requirements to create Linux custom images
<a name="linux_custom_image_requirements"></a>
+ The status of the WorkSpace must be **Available** and its modification state must be **None**.
+ All applications to include in the image must be installed outside of the user volume (the `/home` directory).
+ The root volume (/) should be less than 97% full.
+ The WorkSpace must not be encrypted. Image creation from an encrypted WorkSpace is not currently supported.
+ The following components are required in an image. Without these components, the WorkSpaces that you launch from the image will not function correctly:
  + Cloud-init
  + Teradici PCoIP or DCV agents and drivers
  + Skylight agent

## Best practices
<a name="custom_image_best_practices"></a>

Before you create an image from a WorkSpace, do the following:
+ Use a separate VPC that is not connected to your production environment.
+ Deploy the WorkSpace in a private subnet and use a NAT instance for outbound traffic.
+ Use a small Simple AD directory.
+ Use the smallest volume size for the source WorkSpace, and then adjust the volume size as needed when creating the custom bundle.
+ Install all operating system updates (except Windows feature/version updates) and all application updates on the WorkSpace. For more information, see the [Important note](#important_note) at the start of this topic.
+ Delete cached data from the WorkSpace that shouldn't be included in the bundle (for example, browser history, cached files, and browser cookies).
+ Delete configuration settings from the WorkSpace that shouldn't be included in the bundle (for example, email profiles).
+ Switch to dynamic IP address settings using DHCP.
+ Make sure that you haven't exceeded your quota for WorkSpace images allowed in a Region. By default, you're allowed 40 WorkSpace images per Region. If you've reached this quota, new attempts to create an image will fail. To request a quota increase, use the [WorkSpaces Limits form](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase&limitType=workspaces).
+ Make sure that you aren't trying to create an image from an encrypted WorkSpace. Image creation from an encrypted WorkSpace is not currently supported.
+ If you're running any antivirus software on the WorkSpace, disable it while you're attempting to create an image.
+ If you have a firewall enabled on your WorkSpace, make sure that it isn't blocking any necessary ports. For more information, see [IP address and port requirements for WorkSpaces Personal](workspaces-port-requirements.md).
+ For Windows WorkSpaces, don't configure any Group Policy Objects (GPOs) before image creation.
+ For Windows WorkSpaces, do not customize the default user profile (`C:\Users\Default`) before creating an image. We recommend making any customizations to the user profile through GPOs, and applying them after image creation. GPOs can be easily modified or rolled back, and are therefore less prone to error than customizations made to the default user profile.
+ For Linux WorkSpaces, see also the [ "Best Practices to Prepare Your Amazon WorkSpaces for Linux Images"](https://docs.aws.amazon.com/whitepapers/latest/workspaces-linux-best-practices/welcome.html) whitepaper.
+ If you want to use smart cards on Linux WorkSpaces with DCV enabled, see [Use smart cards for authentication in WorkSpaces Personal](smart-cards.md) for the customizations that you must make to your Linux WorkSpace before creating your image. 
+ Ensure you update networking dependency drivers like ENA, NVMe, and PV drivers on your WorkSpaces. You should do this at least once every 6 months. For more information, see [ Install or upgrade Elastic Network Adapter (ENA) driver ](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/enhanced-networking-ena.html#ena-adapter-driver-install-upgrade-win), [AWS NVMe drivers for Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/aws-nvme-drivers.html), and [Upgrade PV drivers on Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Upgrading_PV_drivers.html).
+ Ensure you update the EC2Config, EC2Launch, and EC2Launch V2 agents to the latest versions periodically. You should do this at least once every 6 months. For more information, see [Update EC2Config and EC2Launch](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/migrating-latest-types.html#upgdate-ec2config-ec2launch).

## (Optional) Step 1: Specify a custom computer name format for your image
<a name="custom_computer_name"></a>

For the WorkSpaces launched from your custom or Bring Your Own License (BYOL) images, you can specify a custom prefix for the computer name format instead of using the [default computer name format](launch-workspaces-tutorials.md). To specify a custom prefix, follow the appropriate procedure for your image type. 

### To specify a custom computer name format for custom images
<a name="custom_computer_name_custom_image"></a>

**Note**  
By default, the format of the computer name for Windows 10 WorkSpaces is `DESKTOP-XXXXX` and for Windows 11 WorkSpaces, `WORKSPA-XXXXX`.

1. On the WorkSpace that you're using to create your custom image, open `C:\ProgramData\Amazon\EC2-Windows\Launch\Sysprep\Unattend.xml` in Notepad or another text editor. For more information about working with the `Unattend.xml` file, see [ Answer files (unattend.xml)](https://docs.microsoft.com/windows-hardware/manufacture/desktop/update-windows-settings-and-scripts-create-your-own-answer-file-sxs) in the Microsoft documentation.
**Note**  
To access the C: drive from the Windows File Explorer on your WorkSpace, enter **C:\$1** in the address bar.

1. In the `<settings pass="specialize">` section, make sure that `<ComputerName>` is set to an asterisk (`*`). If `<ComputerName>` is set to any other value, your custom computer name settings will be ignored. For more information about the `<ComputerName>` setting, see [ ComputerName](https://docs.microsoft.com/windows-hardware/customize/desktop/unattend/microsoft-windows-shell-setup-computername) in the Microsoft documentation.

1. In the `<settings pass="specialize">` section, set `<RegisteredOrganization>` and `<RegisteredOwner>` to your preferred values.

   During Sysprep, the values that you specify for `<RegisteredOwner>` and `<RegisteredOrganization>` are concatenated together, and the first 7 characters of the combined string are used to create the computer name. For example, if you specify **Amazon.com** for `<RegisteredOrganization>` and **EC2** for `<RegisteredOwner>`. For Windows 10-based images, the computer names for the WorkSpaces using custom bundles will start with EC2AMAZ-*xxxxxxx*. For Windows 11 based images, the computer names for the WorkSpaces using custom bundles will start with WORKSPA-*xxxxxxx*.
**Note**  
The `<RegisteredOrganization>` and `<RegisteredOwner>` values in the `<settings pass="oobeSystem">` section are ignored by Sysprep.
Both <RegisteredOrganization> and <RegisteredOwner> are required values.

1. Save your changes to the `Unattend.xml` file.

### To specify a custom computer name format for BYOL images
<a name="custom_computer_name_byol"></a>

1. If you are using Windows 10, open `C:\Program Files\Amazon\Ec2ConfigService\Sysprep2008.xml` in Notepad or another text editor. If you are using Windows 11, open `C:\ProgramData\Amazon\EC2Launch\sysprep\OOBE_unattend.xml`.

1. In the `<settings pass="specialize">` section, if you're using Windows 10, uncomment `<ComputerName>*</ComputerName>`. If you're using Windows 11, you won't need to uncomment this section. Make sure that `<ComputerName>` is set to an asterisk (`*`). If `<ComputerName>` is set to any other value, your custom computer name settings will be ignored. For more information about the `<ComputerName>` setting, see [ ComputerName](https://docs.microsoft.com/windows-hardware/customize/desktop/unattend/microsoft-windows-shell-setup-computername) in the Microsoft documentation.

1. In the `<settings pass="specialize">` section, the `<RegisteredOrganization>` field will be present for Windows 10 and Windows 11. The `<RegisteredOwner>` tag will only be present in Windows 10 by default. If you're using Windows 11, you will need to add this tag. Set `<RegisteredOrganization>` and `<RegisteredOwner>` to your preferred values.

   During Sysprep, the values that you specify for `<RegisteredOwner>` and `<RegisteredOrganization>` are concatenated together, and the first 7 characters of the combined string are used to create the computer name. For example, if you specify **Amazon.com** for `<RegisteredOrganization>` and **EC2** for `<RegisteredOwner>`, the computer names for the WorkSpaces created from your custom bundle will start with EC2AMAZ-*xxxxxxx*.
**Note**  
The `<RegisteredOrganization>` and `<RegisteredOwner>` values in the `<settings pass="oobeSystem">` section are ignored by Sysprep.
Both <RegisteredOrganization> and <RegisteredOwner> are required values.

1. If you are using Windows 10, save your changes to the `Sysprep2008.xml` file. If you are using Windows 11, save your changes to `OOBE_unattend.xml`

## Step 2: Run the Image Checker
<a name="run_image_checker"></a>

**Note**  
The Image Checker is available only for Windows WorkSpaces. If you are creating an image from a Linux WorkSpace, skip to [Step 3: Create a custom image and custom bundle](#create_custom_image_bundle).

To confirm that your Windows WorkSpace meets the requirements for image creation, we recommend running the Image Checker. The Image Checker performs a series of tests on the WorkSpace that you want to use to create your image, and provides guidance on how to resolve any issues it finds.

**Important**  
The WorkSpace must pass all of the tests run by the Image Checker before you can use it for image creation. 
Before you run the Image Checker, verify that the latest Windows security and cumulative updates are installed on your WorkSpace.

To get the Image Checker, do one of the following:
+ [Reboot your WorkSpace](reboot-workspaces.md). The Image Checker is downloaded automatically during the reboot and installed at `C:\Program Files\Amazon\ImageChecker.exe`.
+ Download the Amazon WorkSpaces Image Checker from [https://tools.amazonworkspaces.com/ImageChecker.zip](https://tools.amazonworkspaces.com/ImageChecker.zip) and extract the `ImageChecker.exe` file. Copy this file to `C:\Program Files\Amazon\`.

**To run the Image Checker**

1. Open the `C:\Program Files\Amazon\ImageChecker.exe` file.

1. In the **Amazon WorkSpaces Image Checker** dialog box, choose **Run**.

1. After each test is completed, you can view the status of the test.

   For any test with a status of **FAILED**, choose **Info** to display information about how to resolve the issue that caused the failure. For more information about how to resolve these issues, see [Tips for resolving issues detected by the Image Checker](#image_checker_tips).

   If any tests display a status of **WARNING**, choose the **Fix All Warnings** button.

   The tool generates an output log file in the same directory where the Image Checker is located. By default, this file is located at `C:\Program Files\Amazon\ImageChecker_yyyyMMddhhmmss.log`.
**Tip**  
Do not delete this log file. If an issue occurs, this log file might be helpful in troubleshooting.

1. If applicable, resolve any issues that cause test failures and warnings, and repeat the process of running the Image Checker until the WorkSpace passes all tests. All failures and warnings must be resolved before you can create an image.

1. After your WorkSpace passes all tests, you see a **Validation Successful** message. You are now ready to create a custom bundle.

### Tips for resolving issues detected by the Image Checker
<a name="image_checker_tips"></a>

In addition to consulting the following tips for resolving issues that are detected by the Image Checker, be sure to review the Image Checker log file at `C:\Program Files\Amazon\ImageChecker_yyyyMMddhhmmss.log`.<a name="tips_powershell"></a>

#### PowerShell version 3.0 or later must be installed
<a name="tips_powershell"></a>

Install the latest version of [ Microsoft Windows PowerShell](https://docs.microsoft.com/powershell).

**Important**  
The PowerShell execution policy for a WorkSpace must be set to allow **RemoteSigned** scripts. To check the execution policy, run the **Get-ExecutionPolicy** PowerShell command. If the execution policy is not set to **Unrestricted** or **RemoteSigned**, run the **Set-ExecutionPolicy –ExecutionPolicy RemoteSigned** command to change the value of the execution policy. The **RemoteSigned** setting allows the execution of scripts on Amazon WorkSpaces, which is required to create an image.<a name="tips_local_drives"></a>

#### Only the C and D drives can be present
<a name="tips_local_drives"></a>

Only the `C` and `D` drives can be present on a WorkSpace that's used for imaging. Remove all other drives, including virtual drives.<a name="tips_pending_updates"></a>

#### No pending reboot due to Windows Updates can be detected
<a name="tips_pending_updates"></a>
+ The Create Image process can't run until Windows is rebooted to finish installing security or cumulative updates. Reboot Windows to apply these updates, and make sure that no other pending Windows security or cumulative updates need to be installed.
+ Image creation is not supported on Windows 10 systems that have been upgraded from one version of Windows 10 to a newer version of Windows 10 (a Windows feature/version upgrade). However, Windows cumulative or security updates are supported by the WorkSpaces image-creation process.<a name="tips_blank_sysprep"></a>

#### The Sysprep file must exist and can't be blank
<a name="tips_blank_sysprep"></a>

If there are problems with your Sysprep file, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) to get your EC2Config or EC2Launch repaired.<a name="tips_profile_missing"></a>

#### The user profile size must be less than 10 GB
<a name="tips_profile_missing"></a>

For Windows 7 WorkSpaces, the user profile (`D:\Users\username`) must be less than 10 GB total. Remove files as needed to reduce the size of the user profile.<a name="tips_drive_c_full"></a>

#### Drive C must have enough free space
<a name="tips_drive_c_full"></a>

For Windows 7 WorkSpaces, you must have at least 12 GB of free space on drive `C`. Remove files as needed to free up space on drive `C`. For Windows 10 WorkSpaces, ignore if you receive a `FAILED` message and the disk space is above 2GB.<a name="tips_services_domain_accounts"></a>

#### No services can be running under a domain account
<a name="tips_services_domain_accounts"></a>

To run the Create Image process, no services on the WorkSpace can be running under a domain account. All services must be running under a local account.

**To run services under a local account**

1. Open `C:\Program Files\Amazon\ImageChecker_yyyyMMddhhmmss.log` and find the list of services that are running under a domain account.

1. In the Windows search box, enter **services.msc** to open the Windows Services Manager.

1. Under **Log On As**, look for the services that are running under domain accounts. (Services running as **Local System**, **Local Service**, or **Network Service** do not interfere with image creation.)

1. Select a service that is running under a domain account, and then choose **Action**, **Properties**.

1. Open the **Log On** tab. Under **Log on as**, choose **Local System account**. 

1. Choose **OK**.<a name="tips_static_ip"></a>

#### The WorkSpace must be configured to use DHCP
<a name="tips_static_ip"></a>

You must configure all network adapters on the WorkSpace to use DHCP instead of static IP addresses.

**To set all network adapters to use DHCP**

1. In the Windows search box, enter **control panel** to open the Control Panel.

1. Choose **Network and Internet**.

1. Choose **Network and Sharing Center**.

1. Choose **Change adapter settings**, and select an adapter.

1. Choose **Change settings of this connection**.

1. On the **Networking** tab, select **Internet Protocol Version 4 (TCP/IPv4)**, and then choose **Properties**.

1. In the **Internet Protocol Version 4 (TCP/IPv4) Properties** dialog box, select **Obtain an IP address automatically**.

1. Choose **OK**.

1. Repeat this process for all network adapters on the WorkSpace.<a name="tips_enable_rds"></a>

#### Remote Desktop Services must be enabled
<a name="tips_enable_rds"></a>

The Create Image process requires Remote Desktop Services to be enabled.

**To enable Remote Desktop Services**

1. In the Windows search box, enter **services.msc** to open the Windows Services Manager.

1. In the **Name** column, find **Remote Desktop Services**.

1. Select **Remote Desktop Services**, and then choose **Action**, **Properties**.

1. On the **General** tab, for **Startup type**, choose **Manual** or **Automatic**.

1. Choose **OK**.<a name="tips_user_profile_missing"></a>

#### A user profile must exist
<a name="tips_user_profile_missing"></a>

The WorkSpace that you're using to create images must have a user profile (`D:\Users\username`). If this test fails, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) for assistance. <a name="tips_environment_variables"></a>

#### The environment variable path must be properly configured
<a name="tips_environment_variables"></a>

The environment variable path for the local machine is missing entries for System32 and for Windows PowerShell. These entries are required for Create Image to run.

**To configure your environment variable path**

1. In the Windows search box, enter **environment variables** and then choose **Edit the system environment variables**.

1. In the **System Properties** dialog box, open the **Advanced** tab, and choose **Environment Variables**.

1. In the **Environment Variables** dialog box, under **System variables**, select the **Path** entry and then choose **Edit**.

1. Choose **New**, and add the following path:

   `C:\Windows\System32`

1. Choose **New** again, and add the following path:

   `C:\Windows\System32\WindowsPowerShell\v1.0\`

1. Choose **OK**.

1. Restart the WorkSpace.
**Tip**  
The order in which items appear in the environment variable path matters. To determine the correct order, you might want to compare the environment variable path of your WorkSpace with one from a newly created WorkSpace or a new Windows instance.<a name="tips_enable_wmi"></a>

#### Windows Modules Installer must be enabled
<a name="tips_enable_wmi"></a>

The Create Image process requires the Windows Modules Installer service to be enabled.

**To enable the Windows Modules Installer service**

1. In the Windows search box, enter **services.msc** to open the Windows Services Manager.

1. In the **Name** column, find **Windows Modules Installer**.

1. Select **Windows Modules Installer**, and then choose **Action**, **Properties**.

1. On the **General** tab, for **Startup type**, choose **Manual** or **Automatic**.

1. Choose **OK**.<a name="tips_disable_ssm"></a>

#### Amazon SSM Agent must be disabled
<a name="tips_disable_ssm"></a>

The Create Image process requires the Amazon SSM Agent service to be disabled.

**To disable the Amazon SSM Agent service**

1. In the Windows search box, enter **services.msc** to open the Windows Services Manager.

1. In the **Name** column, find **Amazon SSM Agent**.

1. Select **Amazon SSM Agent**, and then choose **Action**, **Properties**.

1. On the **General** tab, for **Startup type**, choose **Disabled**.

1. Choose **OK**.<a name="tips_enable_ssl_tls"></a>

#### SSL and TLS version 1.2 must be enabled
<a name="tips_enable_ssl_tls"></a>

To configure SSL/TLS for Windows, see [ How to Enable TLS 1.2](https://docs.microsoft.com/configmgr/core/plan-design/security/enable-tls-1-2) in the Microsoft Windows documentation. <a name="tips_remove_extra_profiles"></a>

#### Only one user profile can exist on the WorkSpace
<a name="tips_remove_extra_profiles"></a>

There can be only one WorkSpaces user profile (`D:\Users\username`) on the WorkSpace that you're using to create images. Delete any user profiles that don't belong to the intended user of the WorkSpace.

For image creation to work, your WorkSpace can have only three user profiles on it:
+ The user profile of the intended user of the WorkSpace (`D:\Users\username`)
+ The default user profile (also known as Default Profile)
+ The Administrator user profile

If there are additional user profiles, you can delete them through the advanced system properties in the Windows Control Panel.

**To delete a user profile**

1. To access the advanced system properties, do one of the following:
   + Press the **Windows key\$1Pause Break**, and then choose **Advanced system settings** in the left pane of the **Control Panel** > **System and Security** > **System** dialog box.
   + In the Windows search box, enter **control panel**. In the Control Panel, choose **System and Security**, then choose System, and then choose **Advanced system settings** in the left pane of the **Control Panel** > **System and Security** > **System** dialog box.

1. In the **System Properties** dialog box, on the **Advanced** tab, choose **Settings** under **User Profiles**.

1. If any profile is listed other than the Administrator profile, the Default Profile, and the profile of the intended WorkSpaces user, select that additional profile and choose **Delete**.

1. When asked if you want to delete the profile, choose **Yes**.

1. If necessary, repeat Steps 3 and 4 to remove any other profiles that don't belong on the WorkSpace.

1. Choose **OK** twice and close the Control Panel.

1. Restart the WorkSpace.<a name="tips_unstage_appx"></a>

#### No AppX packages can be in a staged state
<a name="tips_unstage_appx"></a>

One or more AppX packages are in a staged state. This might cause a Sysprep error during image creation.

**To remove all staged AppX packages**

1. In the Windows search box, enter **powershell**. Choose **Run as Administrator**.

1. When asked "Do you want to allow this app to make changes to your device?", choose **Yes**.

1. In the Windows PowerShell window, enter the following commands to list all staged AppX packages, and press Enter after each one.

   ```
   $workSpaceUserName = $env:username
   ```

   ```
   $allAppxPackages = Get-AppxPackage -AllUsers
   ```

   ```
   $packages = $allAppxPackages |    Where-Object { `
                                   (($_.PackageUserInformation -like "*S-1-5-18*" -and !($_.PackageUserInformation -like "*$workSpaceUserName*")) -and `
                                   ($_.PackageUserInformation -like "*Staged*" -or $_.PackageUserInformation -like "*Installed*")) -or `
                                   ((!($_.PackageUserInformation -like "*S-1-5-18*") -and $_.PackageUserInformation -like "*$workSpaceUserName*") -and `
                                   $_.PackageUserInformation -like "*Staged*")
                                   }
   ```

1. Execute the following command with elevated SYSTEM privileges to remove all staged AppX package provisioning entries, and press Enter.

   ```
   $packages | Remove-AppxPackage -ErrorAction SilentlyContinue
   ```

1. Run the Image Checker again. If this test still fails, enter the following commands to remove all AppX packages, and press Enter after each one.

   ```
   Get-AppxProvisionedPackage -Online | Remove-AppxProvisionedPackage -Online -ErrorAction SilentlyContinue
   ```

   ```
   Get-AppxPackage -AllUsers | Remove-AppxPackage -ErrorAction SilentlyContinue
   ```<a name="tips_version_upgrade"></a>

#### Windows must not have been upgraded from a previous version
<a name="tips_version_upgrade"></a>

Image creation is not supported on Windows systems that have been upgraded from one version of Windows 10 to a newer version of Windows 10 (a Windows feature/version upgrade).

To create images, use a WorkSpace that has not undergone a Windows feature/version upgrade.<a name="tips_reset_rearm_count"></a>

#### The Windows rearm count must not be 0
<a name="tips_reset_rearm_count"></a>

The rearm feature allows you to extend the activation period for the trial version of Windows. The Create Image process requires that the rearm count be a value other than 0.

**To check the Windows rearm count**

1. On the Windows **Start** menu, choose **Windows System**, then choose **Command Prompt**.

1. In the Command Prompt window, enter the following command, and then press Enter.

   `cscript C:\Windows\System32\slmgr.vbs /dlv`

To reset the rearm count to a value other than 0, see [ Sysprep (Generalize) a Windows installation](https://docs.microsoft.com/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation) in the Microsoft Windows documentation.

#### Other troubleshooting tips
<a name="images_troubleshooting_tips"></a>

If your WorkSpace passes all of the tests run by the Image Checker, but you are still unable to create an image from the WorkSpace, check for the following issues:
+ Make sure that the WorkSpace isn't assigned to a user within a **Domain Guests** group. To check if there are any domain accounts, run the following PowerShell command.

  ```
  Get-WmiObject -Class Win32_Service | Where-Object { $_.StartName -like "*$env:USERDOMAIN*" }
  ```
+ For Windows 7 WorkSpaces only: If problems occur while the user profile is being copied during image creation, check for the following issues:
  + Long profile paths can cause image creation errors. Make sure that the paths of all folders within the user profile are less than 261 characters.
  + Make sure to grant full permissions on the profile folder to the system and all application packages.
  + If any files in the user profile are locked by a process or are in use during image creation, copying the profile might fail.
+ Some Group Policy Objects (GPOs) restrict access to the RDP certificate thumbprint when it is requested by the EC2Config service or the EC2Launch scripts during Windows instance configuration. Before you try to create an image, move the WorkSpace to a new organizational unit (OU) with blocked inheritance and no GPOs applied.
+ Make sure that the Windows Remote Management (WinRM) service is configured to start automatically. Do the following:

  1. In the Windows search box, enter **services.msc** to open the Windows Services Manager.

  1. In the **Name** column, find **Windows Remote Management (WS-Management)**. 

  1. Select **Windows Remote Management (WS-Management)**, and then choose **Action**, **Properties**.

  1. On the **General** tab, for **Startup type**, choose **Automatic**.

  1. Choose **OK**.

## Step 3: Create a custom image and custom bundle
<a name="create_custom_image_bundle"></a>

After you have validated your WorkSpace image, you can proceed with creating your custom image and custom bundle.

**To create a custom image and custom bundle**

1. If you are still connected to the WorkSpace, disconnect by choosing **Amazon WorkSpaces** and **Disconnect** in the WorkSpaces client application.

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. <a name="step_create_image"></a>Select the WorkSpace to open its details page and choose **Create image**. If the status of the WorkSpace is **Stopped**, you must start it first (choose **Actions**, **Start WorkSpaces**) before you can choose **Actions**, **Create Image**.
**Note**  
To create an image programmatically, use the CreateWorkspaceImage API action. For more information, see [ CreateWorkspaceImage](https://docs.aws.amazon.com/workspaces/latest/api/API_CreateWorkspaceImage.html) in the *Amazon WorkSpaces API Reference*.

1. A message displays, prompting you to reboot (restart) your WorkSpace before continuing. Rebooting your WorkSpace updates your Amazon WorkSpaces software to the latest version.

   Reboot your WorkSpace by closing the message and following the steps in [Reboot a WorkSpace in WorkSpaces Personal](reboot-workspaces.md). When you're done, repeat [Step 4](#step_create_image) of this procedure, but this time choose **Next** when the reboot message appears. To create an image, the status of the WorkSpace must be **Available** and its modification state must be **None**.

1. Enter an image name and a description that will help you identify the image, and then choose **Create Image**. While the image is being created, the status of the WorkSpace is **Suspended** and the WorkSpace is unavailable.
**Note**  
When entering an image description, make sure you don't use the special character "-" or you will get an error.

1. In the navigation pane, choose **Images**. The image is complete when the status of the WorkSpace changes to **Available** (this can take up to 45 minutes).

1. Select the image and choose **Actions**, **Create bundle**.
**Note**  
To create a bundle programmatically, use the **CreateWorkspaceBundle** API action. For more information, see [ CreateWorkspaceBundle](https://docs.aws.amazon.com/workspaces/latest/api/API_CreateWorkspaceBundle.html) in the *Amazon WorkSpaces API Reference*.

1. Enter a bundle name and a description, and then do the following: 
   + For **Bundle hardware type**, choose the hardware to use when launching WorkSpaces from this custom bundle.
   + For **Storage settings**, select one of the default combinations for the root volume and user volume size, or select **Custom**, and then enter values (up to 2000 GB) for **Root volume size** and **User volume size**.

     The default available size combinations for the root volume (for Microsoft Windows, the `C` drive, for Linux, /) and the user volume (for Windows, the `D` drive; for Linux, /home) are as follows: 
     + Root: 80 GB, User: 10 GB, 50 GB, or 100 GB
     + Root: 175 GB, User: 100 GB
     + Storage requirements for GPU-enabled WorkSpaces scale proportionally with instance sizing. As you select larger GPU-enabled WorkSpaces configurations, you must allocate correspondingly larger storage volumes to maintain optimal performance and accommodate increased workload demands. For the smallest instance size, begin with the following storage allocation: Root: 100 GB, User: 100 GB

     Alternatively, you can expand the root and user volumes up to 2000 GB each.
**Note**  
To ensure that your data is preserved, you cannot decrease the size of the root or user volumes after you launch a WorkSpace. Instead, make sure that you specify the minimum sizes for these volumes when launching a WorkSpace.  
You can launch a Value, Standard, Performance, Power, or PowerPro WorkSpace with a minimum of 80 GB for the root volume and 10 GB for the user volume.
You can launch a GeneralPurpose.4xlarge or GeneralPurpose.8xlarge WorkSpace with a minimum of 175GB for the root volume and 100 GB for the user volume.

1. Choose **Create bundle**.

1. To confirm that your bundle has been created, choose **Bundles** and verify that the bundle is listed.

## What's included with Windows WorkSpaces custom images
<a name="image_creation_windows"></a>

When you create an image from a Windows 7, Windows 10, or Windows 11 WorkSpace, the entire contents of the `C` drive are included.

For Windows 10 or 11 WorkSpaces, the user profile in `D:\Users\username` is not included in the custom image.

For Windows 7 WorkSpaces, the entire contents of the user profile in `D:\Users\username` are included, except for the following:
+ Contacts
+ Downloads
+ Music
+ Pictures
+ Saved games
+ Videos
+ Podcasts
+ Virtual machines
+ .virtualbox
+ Tracing
+ appdata\$1local\$1temp
+ appdata\$1roaming\$1apple computer\$1mobilesync\$1
+ appdata\$1roaming\$1apple computer\$1logs\$1
+ appdata\$1roaming\$1apple computer\$1itunes\$1iphone software updates\$1
+ appdata\$1roaming\$1macromedia\$1flash player\$1macromedia.com\$1support\$1flashplayer\$1sys\$1
+ appdata\$1roaming\$1macromedia\$1flash player\$1\$1sharedobjects\$1
+ appdata\$1roaming\$1adobe\$1flash player\$1assetcache\$1
+ appdata\$1roaming\$1microsoft\$1windows\$1recent\$1
+ appdata\$1roaming\$1microsoft\$1office\$1recent\$1
+ appdata\$1roaming\$1microsoft office\$1live meeting
+ appdata\$1roaming\$1microsoft shared\$1livemeeting shared\$1
+ appdata\$1roaming\$1mozilla\$1firefox\$1crash reports\$1
+ appdata\$1roaming\$1mcafee\$1common framework\$1
+ appdata\$1local\$1microsoft\$1feeds cache
+ appdata\$1local\$1microsoft\$1windows\$1temporary internet files\$1
+ appdata\$1local\$1microsoft\$1windows\$1history\$1
+ appdata\$1local\$1microsoft\$1internet explorer\$1domstore\$1
+ appdata\$1local\$1microsoft\$1internet explorer\$1imagestore\$1
+ appdata\$1locallow\$1microsoft\$1internet explorer\$1iconcache\$1
+ appdata\$1locallow\$1microsoft\$1internet explorer\$1domstore\$1
+ appdata\$1locallow\$1microsoft\$1internet explorer\$1imagestore\$1
+ appdata\$1local\$1microsoft\$1internet explorer\$1recovery\$1
+ appdata\$1local\$1mozilla\$1firefox\$1profiles\$1

## What's included with Linux WorkSpace custom images
<a name="image_creation_linux"></a>

When you create an image from an Amazon Linux WorkSpace, the entire contents of the user volume (/home) are removed. The contents of the root volume (/) are included, except the following applicable folders and keys, which are removed:
+ /tmp
+ /var/spool/mail
+ /var/tmp
+ /var/lib/dhcp
+ /var/lib/cloud
+ /var/cache
+ /var/backups
+ /etc/sudoers.d
+ /etc/udev/rules.d/70-persistent-net.rules
+ /etc/network/interfaces.d/50-cloud-init.cfg
+ /var/log/amazon/ssm
+ /var/log/pcoip-agent
+ /var/log/skylight
+ /var/lock/.skylight.domain-join.lock
+ /var/lib/skylight/domain-join-status
+ /var/lib/skylight/configuration-data
+ /var/lib/skylight/config-data.json
+ /home
+ /etc/default/grub.d/zz-hibernation.cfg
+ /etc/netplan/zz-workspaces-domain.yaml
+ /etc/netplan/yy-workspaces-base.yaml
+ /var/lib/AccountsService/users

The following keys are shredded during custom image creation:
+ /etc/ssh/ssh\$1host\$1\$1\$1key
+ /etc/ssh/ssh\$1host\$1\$1\$1key.pub
+ /var/lib/skylight/tls.\$1
+ /var/lib/skylight/private.key
+ /var/lib/skylight/public.key

# Update a custom bundle for WorkSpaces Personal
<a name="update-custom-bundle"></a>

You can update an existing custom WorkSpaces bundle by modifying a WorkSpace that is based on the bundle, creating an image from the WorkSpace, and updating the bundle with the new image. You can then launch new WorkSpaces using the updated bundle.

**Important**  
Existing WorkSpaces aren't automatically updated when you update the bundle that they're based on. To update existing WorkSpaces that are based on a bundle that you've updated, you must either rebuild the WorkSpaces or delete and recreate them.

**To update a bundle using the console**

1. Connect to a WorkSpace that is based on the bundle and make the changes that you want. For example, you can apply the latest operating system and application patches and install additional applications.

   Alternatively, you can create a new WorkSpace with the same base software package (Plus or Standard) as the image used to create the bundle, and make changes.

1. If you are still connected to the WorkSpace, disconnect by choosing **Amazon WorkSpaces** and **Disconnect** in the WorkSpaces client application.

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select the WorkSpace and choose **Actions**, **Create Image**. If the status of the WorkSpace is `STOPPED`, you must start it first (choose **Actions**, **Start WorkSpaces**) before you can choose **Actions**, **Create Image**.

1. Enter an image name and a description, and then choose **Create Image**. The WorkSpace is unavailable while the image is being created. For detailed information about the image creation process, see [Create a custom WorkSpaces image and bundle for WorkSpaces Personal](create-custom-bundle.md).

1. In the navigation pane, choose **Bundles**.

1. Choose the bundle to open its details page, and then under **Source image**, choose **Edit**.

1. On the **Update source image** page, select the image that you created and choose **Update bundle**.

1. As needed, update any existing WorkSpaces that are based on the bundle by rebuilding the WorkSpaces or deleting and recreating them. For more information, see [Rebuild a WorkSpace in WorkSpaces Personal](rebuild-workspace.md).

**To update a bundle programmatically**  
To update a bundle programmatically, use the **UpdateWorkspaceBundle** API action. For more information, see [ UpdateWorkspaceBundle](https://docs.aws.amazon.com/workspaces/latest/api/API_UpdateWorkspaceBundle.html) in the *Amazon WorkSpaces API Reference*.

# Copy a custom image in WorkSpaces Personal
<a name="copy-custom-image"></a>

You can copy a custom WorkSpaces image within or across AWS Regions. Copying an image results in the creation of an identical image with its own unique identifier.

You can copy a Bring Your Own License (BYOL) image to another Region as long as the destination Region is enabled for BYOL. Ensure that BYOL is enabled for all accounts and Regions involved.

**Note**  
In the China (Ningxia) Region, you can copy images only within the same Region.  
In the AWS GovCloud (US) Regions, to copy images to and from other AWS Regions, contact AWS Support.  
In Opt-in Regions, to copy images to other Regions, contact AWS Support. For more information about Opt-in Regions, see [ Available Regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions).

You can also copy an image that has been shared with you by another AWS account. For more information about shared images, see [Share or unshare a custom image in WorkSpaces Personal](share-custom-image.md).

There are no additional charges for copying an image within or across Regions. However, the quota for the number of images in the destination Region applies. For more information about Amazon WorkSpaces quotas, see [Amazon WorkSpaces quotas](workspaces-limits.md).

**IAM Permissions to copy an image**  
If you use an IAM user to copy an image, the user must have permissions for `workspaces:DescribeWorkspaceImages` and `workspaces:CopyWorkspaceImage`.

The following example policy allows the user to copy the specified image to the specified account in the specified Region.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "workspaces:DescribeWorkspaceImages",
        "workspaces:CopyWorkspaceImage"
      ],
      "Resource": [
          "arn:aws:workspaces:us-east-1:123456789012:workspaceimage/wsi-a1bcd2efg"
      ]
    }
  ]
}
```

------

**Important**  
If you are creating an IAM policy for copying shared images for accounts that don't own the images, you cannot specify an account ID in the ARN. Instead, you must use `*` for the account ID, as shown in the following example policy.  

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "workspaces:DescribeWorkspaceImages",
        "workspaces:CopyWorkspaceImage"
      ],
      "Resource": [
          "arn:aws:workspaces:us-east-1:*:workspaceimage/wsi-a1bcd2efg"
      ]
    }
  ]
}
```
You can specify an account ID in the ARN only when that account owns the images to be copied.

For more information about working with IAM, see [Identity and access management for WorkSpaces](workspaces-access-control.md).

**Bulk copy images**  
You can copy images one by one using the console. To bulk copy images, use the **CopyWorkspaceImage** API operation or the **copy-workspace-image** command in the AWS Command Line Interface (AWS CLI). For more information, see [ CopyWorkspaceImage](https://docs.aws.amazon.com/workspaces/latest/api/API_CopyWorkspaceImage.html) in the *Amazon WorkSpaces API Reference* or see [ copy-workspace-image](https://docs.aws.amazon.com/cli/latest/reference/workspaces/copy-workspace-image.html) in the *AWS CLI Command Reference*.

**Important**  
Before copying a shared image, be sure to verify that it has been shared from the correct AWS account. To determine if an image has been shared and to see the AWS account ID that owns an image, use the [DescribeWorkSpaceImages](https://docs.aws.amazon.com/workspaces/latest/api/API_DescribeWorkspaceImages.html) and [DescribeWorkspaceImagePermissions](https://docs.aws.amazon.com/workspaces/latest/api/API_DescribeWorkspaceImagePermissions.html) API operations or the [describe-workspace-images](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspace-images.html) and [describe-workspace-image-permissions](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspace-image-permissions.html) commands in the AWS CLI.

**To copy an image using the console**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Images**.

1. Select the image and choose **Actions**, **Copy image**.

1. For **Select destination**, select the AWS Region that you want to copy the image to.

1. For **Name of the copy**, enter the new name for the copied image, and for **Description**, enter a description for the copied image.

1. (Optional) Under **Tags**, enter tags for the copied image. For more information, see [Tag resources in WorkSpaces Personal](tag-workspaces-resources.md).

1. Choose **Copy image**.

# Share or unshare a custom image in WorkSpaces Personal
<a name="share-custom-image"></a>

You can share custom WorkSpaces images across AWS accounts within the same AWS Region. After an image has been shared, the recipient account can copy the image to other AWS Regions as needed. For more information about copying images, see [Copy a custom image in WorkSpaces Personal](copy-custom-image.md).

**Note**  
In the China (Ningxia) Region, you can copy images only within the same Region.  
In the AWS GovCloud (US) Regions, to copy images to and from other AWS Regions, contact AWS Support.

There are no additional charges for sharing an image. However, the quota for the number of images in the AWS Region applies. A shared image doesn't count against the recipient account's quota until the recipient copies the image. For more information about Amazon WorkSpaces quotas, see [Amazon WorkSpaces quotas](workspaces-limits.md).

To delete a shared image, you must unshare the image before you can delete it.

**Share Bring Your Own License images**  
You can share Bring Your Own License (BYOL) images only with AWS accounts that are enabled for BYOL. The AWS account that you want to share BYOL images with must also be part of your organization (under the same payer account).

**Note**  
Sharing BYOL images across AWS accounts isn't supported at this time in the AWS GovCloud (US-West) and AWS GovCloud (US-East) Regions. To share BYOL images across accounts in the AWS GovCloud (US-West) and AWS GovCloud (US-East) Regions, contact AWS Support. 

**Images shared with you**  
If images are shared with you, you can copy them. You can then use your copies of the shared images to create bundles for launching new WorkSpaces.

**Important**  
Before copying a shared image, be sure to verify that it has been shared from the correct AWS account. To programmatically determine if an image has been shared, use the [DescribeWorkSpaceImages](https://docs.aws.amazon.com/workspaces/latest/api/API_DescribeWorkspaceImages.html) and [DescribeWorkspaceImagePermissions](https://docs.aws.amazon.com/workspaces/latest/api/API_DescribeWorkspaceImagePermissions.html) API operations or the [describe-workspace-images](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspace-images.html) and [describe-workspace-image-permissions](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspace-image-permissions.html) commands in the AWS command line interface (CLI). 

The creation date shown for an image that has been shared with you is the date that the image was originally created, not the date that the image was shared with you.

If an image has been shared with you, you can't further share that image with other accounts.

**To share an image**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Images**.

1. Choose the image to open its details page.

1. On the image detail page, in the **Shared accounts** section, choose **Add account**.

1. On the **Add account** page, under **Add account to share with**, enter the account ID of the account that you want to share the image with.
**Important**  
Before sharing the image, confirm that you are sharing to the correct AWS account ID.

1. Choose **Share image**.
**Note**  
To use the shared image, the recipient account must first [ copy the image](copy-custom-image.md). The recipient account can then use its copy of the shared image to create bundles for launching new WorkSpaces.

**To stop sharing an image**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Images**.

1. Choose the image to open its details page.

1. On the image detail page, in the **Shared accounts** section, select the AWS account that you want to stop sharing with, and then choose **Unshare**.

1. When prompted to confirm unsharing the image, choose **Unshare**.
**Note**  
If you want to delete the image after unsharing it, you must first unshare it from all of the accounts that it has been shared with.

After you stop sharing an image, the recipient account can no longer make copies of the image. However, any copies of shared images that are already in the recipient account remain in that account, and new WorkSpaces can be launched from those copies.

**To share or unshare images programmatically**  
To share or unshare images programmatically, use the [UpdateWorkspaceImagePermission](https://docs.aws.amazon.com/workspaces/latest/api/API_UpdateWorkspaceImagePermission.html) API operation or the [update-workspace-image-permission](https://docs.aws.amazon.com/cli/latest/reference/workspaces/update-workspace-image-permission.html) AWS Command Line Interface (AWS CLI) command. To determine if an image has been shared, use the [DescribeWorkspaceImagePermissions](https://docs.aws.amazon.com/workspaces/latest/api/API_DescribeWorkspaceImagePermissions.html) API operation or the [describe-workspace-image-permissions](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspace-image-permissions.html) CLI command. 

# Delete a custom bundle or image in WorkSpaces Personal
<a name="delete_bundle"></a>

You can delete unused custom bundles or custom images as needed.

## Delete a bundle
<a name="delete_bundle_console"></a>

To delete a bundle, you must first delete all of the WorkSpaces that are based on the bundle.

**To delete a bundle using the console**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Bundles**.

1. Select the bundle and choose **Delete**.

1. When prompted for confirmation, choose **Delete**.

**To delete a bundle programmatically**  
To delete a bundle programmatically, use the **DeleteWorkspaceBundle** API action. For more information, see [ DeleteWorkspaceBundle](https://docs.aws.amazon.com/workspaces/latest/api/API_DeleteWorkspaceBundle.html) in the *Amazon WorkSpaces API Reference*.

**Note**  
Ensure you wait at least 2 hours after deleting a bundle before creating a new bundle with the same name.

## Delete an image
<a name="delete_images"></a>

After you delete a custom bundle, you can delete the image that you used to create or update the bundle.

To delete an image, you must first either delete any bundles that are associated with the image, or you must update those bundles to use another source image. You must also unshare the image if it is shared with other accounts. The image also can't be in the **Pending** or **Validating** state.

**To delete an image using the console**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **Images**.

1. Select the image and choose **Delete**.

1. When prompted for confirmation, choose **Delete**.

**To delete an image programmatically**  
To delete an image programmatically, use the **DeleteWorkspaceImage** API action. For more information, see [ DeleteWorkspaceImage](https://docs.aws.amazon.com/workspaces/latest/api/API_DeleteWorkspaceImage.html) in the *Amazon WorkSpaces API Reference*.

# Monitor WorkSpaces Personal
<a name="amazon-workspaces-monitoring"></a>

You can use the following features to monitor your WorkSpaces.

**CloudWatch metrics**  
Amazon WorkSpaces publishes data points to Amazon CloudWatch about your WorkSpaces. CloudWatch enables you to retrieve statistics about those data points as an ordered set of time-series data, known as *metrics*. You can use these metrics to verify that your WorkSpaces are performing as expected. For more information, see [Monitor your WorkSpaces using CloudWatch metrics](cloudwatch-metrics.md).

**CloudWatch Events**  
Amazon WorkSpaces can submit events to Amazon CloudWatch Events when users log in to your WorkSpace. This enables you to respond when the event occurs. For more information, see [Monitor your WorkSpaces using Amazon EventBridge](cloudwatch-events.md).

**CloudTrail logs**  
AWS CloudTrail provides a record of actions taken by a user, role, or an AWS service in WorkSpaces. Using the information collected by CloudTrail, you can determine the request that was made to WorkSpaces, the IP address from which the request was made, who made the request, when it was made, and additional details. For more information, see [Logging WorkSpaces API Calls by Using CloudTrail](https://docs.aws.amazon.com/workspaces/latest/api/cloudtrail_logging.html). AWS CloudTrail logs successful and unsuccessful sign-in events for smart card users. For more information, see [Understanding AWS sign-in events for smart card users](signin-events.md).

**CloudWatch Internet Monitor**  
Amazon CloudWatch Internet Monitor provides visibility into how internet issues impact the performance and availability between your applications hosted on AWS and your end users. You can also use CloudWatch Internet Monitor to:  
+ Create monitors for one or more WorkSpace directories.
+ Monitor internet performance.
+ Get alarms for issues between your end users’ city-network, including its location and ASN, which is typically the Internet Service Provider (ISP), and their WorkSpace Regions.
Internet Monitor uses the connectivity data that AWS captures from its global networking footprint to calculate a baseline of performance and availability for internet-facing traffic. Internet Monitor currently can't provide internet performance for individual end user but it can at city and ISP level.

**Amazon S3 Access Logs**  
If your users have application settings data or home folders data stored in Amazon S3 buckets, consider viewing Amazon S3 server access logs to monitor access. These logs provide detailed records about requests that are made to a bucket. Server access logs are useful for many applications. For example, access log information can be useful in security and access audits. For more information, see [Amazon S3 Server Access Logging](https://docs.aws.amazon.com/AmazonS3/latest/dev/ServerLogs.html) in the *Amazon Simple Storage Service User Guide*.

# Monitor your WorkSpaces health using the CloudWatch automatic dashboard
<a name="cloudwatch-dashboard"></a>

You can monitor WorkSpaces using CloudWatch automatic dashboard, which collects raw data and processes it into readable, near real-time metrics. The metrics are kept for 15 months to access historical information and to monitor the performance of your web application or service. You can also set alarms that watch for certain thresholds, and send notifications or take actions when those thresholds are met. For more information, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/).

The CloudWatch dashboard is automatically created when you use your AWS account to configure your WorkSpaces. The dashboard allows you to monitor your WorkSpaces metrics, such as their health and performance, across Regions. You can also use the dashboard for the following purposes:
+ Identify unhealthy WorkSpace instances.
+ Identify running modes, protocols, and operating systems that have unhealthy WorkSpace instances.
+ View critical resource utilization over time.
+ Identify anomalies to help with troubleshooting.

WorkSpaces CloudWatch automatic dashboards are available in all AWS commercial Regions.

**To use the WorkSpaces CloudWatch automatic dashboard**

1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. In the navigation pane, choose **Dashboards**.

1. Choose the **Automatic dashboards** tab.

1. Choose **WorkSpaces**.

## Understanding your WorkSpaces CloudWatch automatic dashboard
<a name="understanding-cloudwatch-dashboard"></a>

The CloudWatch automatic dashboard allows you to gain insight into the performance of your WorkSpaces resources and helps you identify performance issues.

![\[WorkSpaces client sign in screen\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/cw_dashboard_withcallouts.png)


**The dashboard consists of the following features:**

1. View historical data using time and date range controls.

1. Add customized dashboard view to the CloudWatch custom dashboards.

1. Monitor the overall health and utilization status of your WorkSpaces by doing the following:

   1. View the total number of provisioned WorkSpaces, number of users connected, number of unhealthy and healthy WorkSpace instances.

   1. View unhealthy WorkSpaces and their different variables, such as protocol and compute mode.

   1. Hover over the line chart to view the number of healthy or unhealthy WorkSpace instances for a specific protocol and running mode over a period of time.

   1. Choose the ellipsis menu, then choose **View in metrics** to view the metrics on a time scale chart.

1. View your connection metrics and their different variables, such as number of connection attempts, successful connections, and failed connections in your WorkSpaces environment at any given time.

1. View InSession latencies that impact your user's experience, such as round trip time (RTT), to determine connection health and packet loss to monitor network health.

1. View host performance and resource utilization to identify and troubleshoot potential performance issues.

# Monitor your WorkSpaces using CloudWatch metrics
<a name="cloudwatch-metrics"></a>

WorkSpaces and Amazon CloudWatch are integrated, so you can gather and analyze performance metrics. You can monitor these metrics using the CloudWatch console, the CloudWatch command line interface, or programmatically using the CloudWatch API. CloudWatch also allows you to set alarms when you reach a specified threshold for a metric.

For more information about using CloudWatch and alarms, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/).

**Prerequisites**  
To get CloudWatch metrics, enable access on port 443 on the `AMAZON` subset in the `us-east-1` Region. For more information, see [IP address and port requirements for WorkSpaces Personal](workspaces-port-requirements.md).

**Topics**
+ [WorkSpaces metrics](#wsp-metrics)
+ [Dimensions for WorkSpaces metrics](#wsp-metric-dimensions)
+ [Monitoring example](#monitoring_example)

## WorkSpaces metrics
<a name="wsp-metrics"></a>

The `AWS/WorkSpaces` namespace includes the following metrics.


| Metric | Description | Dimensions | Statistics | Units | 
| --- | --- | --- | --- | --- | 
| `Available`1 |  The number of WorkSpaces that returned a healthy status.  |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `Unhealthy`1 |  The number of WorkSpaces that returned an unhealthy status.  |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `ConnectionAttempt`2 |  The number of connection attempts.  |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `ConnectionSuccess`2 |  The number of successful connections.  |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `ConnectionFailure`2 |  The number of failed connections.  |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `SessionLaunchTime`2,6 | The amount of time it takes to initiate a WorkSpaces session. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Second (time) | 
| `InSessionLatency`2,6 | The round trip time between the WorkSpaces client and the WorkSpace. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Millisecond (time) | 
| `SessionDisconnect`2,6 | The number of connections that were closed, including user-initiated and failed connections. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `UserConnected`3 | The number of WorkSpaces that have a user connected. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `Stopped` | The number of WorkSpaces that are stopped. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `Maintenance`4 | The number of WorkSpaces that are under maintenance. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `TrustedDeviceValidationAttempt`5,6 | The number of device authentication signature validation attempts. |  `DirectoryId`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `TrustedDeviceValidationSuccess`5,6 | The number of successful device authentication signature validations. |  `DirectoryId`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `TrustedDeviceValidationFailure`5,6 | The number of failed device authentication signature validations.  |  `DirectoryId`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `TrustedDeviceCertificateDaysBeforeExpiration`6 | Days left before the root certificate associated with the directory is expired. |  `CertificateId`  | Average, Sum, Maximum, Minimum, Data Samples | Count | 
| `CPUUsage` | The percentage of the CPU resource used. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Maximum, Minimum | Percentage | 
| `MemoryUsage` | The percentage of the machine memory used. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Maximum, Minimum | Percentage | 
| `RootVolumeDiskUsage` | The percentage of the root disk volume used. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Maximum, Minimum | Percentage | 
| `UserVolumeDiskUsage` | The percentage of the user disk volume used. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Maximum, Minimum | Percentage | 
| `UDPPacketLossRate`7 | The percentage of packets dropped between the client and the gateway. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Maximum, Minimum, Data Samples | Percentage | 
| `UpTime` | The time since the last reboot of a WorkSpace. |  `DirectoryId` `WorkspaceId` `RunningMode` `Protocol` `ComputeType` `BundleId` `UserName` `ComputerName`  | Average, Maximum, Minimum, Data Samples | Seconds | 

1 WorkSpaces periodically sends status requests to a WorkSpace. A WorkSpace is marked `Available` when it responds to these requests, and `Unhealthy` when it fails to respond to these requests. These metrics are available at a per-WorkSpace level of granularity, and also aggregated for all WorkSpaces in an organization. 

2 WorkSpaces records metrics on connections made to each WorkSpace. These metrics are emitted after a user has successfully authenticated via the WorkSpaces client and the client then initiates a session. The metrics are available at a per-WorkSpace level of granularity, and also aggregated for all WorkSpaces in a directory.

3 WorkSpaces periodically sends connection status requests to a WorkSpace. Users are reported as connected when they are actively using their sessions. This metric is available at a per-WorkSpace level of granularity, and is also aggregated for all WorkSpaces in an organization.

4 This metric applies to WorkSpaces that are configured with an AutoStop running mode. If you have maintenance enabled for your WorkSpaces, this metric captures the number of WorkSpaces that are currently under maintenance. This metric is available at a per-WorkSpace level of granularity, which describes when a WorkSpace went into maintenance and when it was removed.

5 If the trusted devices feature is enabled for the directory, Amazon WorkSpaces uses certificate-based authentication to determine whether a device is trusted. When users attempt to access their WorkSpaces, these metrics are emitted to indicate successful or failed trusted device authentication. These metrics are available at a per-directory level of granularity, and only for the Amazon WorkSpaces Windows and macOS client applications. 

6 Not available on WorkSpaces Web Access.

7 This metric measures average packet loss.
+ **On PCoIP**: Measures average UDP packet loss from client to gateway.
**Note**  
This is measured at the gateway.
+ **On DCV**: Measures UDP packet loss from gateway to client. 
**Note**  
This is measured at the gateway.

## Dimensions for WorkSpaces metrics
<a name="wsp-metric-dimensions"></a>

To filter the metric data, use the following dimensions.


| Dimension | Description | 
| --- | --- | 
| `DirectoryId` | Filters the metric data to the WorkSpaces in the specified directory. The form of the directory ID is `d-XXXXXXXXXX`. | 
| `WorkspaceId` | Filters the metric data to the specified WorkSpace. The form of the WorkSpace ID is `ws-XXXXXXXXXX`. | 
| `CertificateId` | Filters the metric data to the specified root certificate associated with the directory. The form of the certificate ID is `wsc-XXXXXXXXX`. | 
| `RunningMode` | Filters the metric data to the WorkSpaces by their running mode. The form of the running mode is AutoStop or AlwaysOn. | 
| `BundleId` | Filters the metric data to the WorkSpaces by the protocol. The form of the bundle is `wsb-XXXXXXXXXX`. | 
| `ComputeType` | Filters the metric data to the WorkSpaces by the compute type.  | 
| `Protocol` | Filters the metric data to the WorkSpaces by the protocol type. | 
| `UserName` |  Filters the metric data to the WorkSpaces by the user's name.  The `UserName` cannot consist of non-ASCII characters, such as the following:  Accented letters: é, à, ö, ñ, etc. Non-Latin alphabets Symbols: ©️, ®️, €, £, µ, ¥, etc.    | 
| `ComputerName` | Filters the metric data to the specified WorkSpace. See various formats for [WorkSpaces Computer Name]( https://docs.aws.amazon.com/workspaces/latest/adminguide/wsp-directory-identify-computer.html). | 

## Monitoring example
<a name="monitoring_example"></a>

The following example demonstrates how you can use the AWS CLI to respond to a CloudWatch alarm and determine which WorkSpaces in a directory have experienced connection failures.

**To respond to a CloudWatch alarm**

1. Determine which directory the alarm applies to using the [describe-alarms](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/describe-alarms.html) command.

   ```
   aws cloudwatch describe-alarms --state-value "ALARM"
   
   {
     "MetricAlarms": [
       {
         ...
         "Dimensions": [
           {
             "Name": "DirectoryId",
             "Value": "directory_id"
           }
         ],
         ...
       }
     ]
   }
   ```

1. Get the list of WorkSpaces in the specified directory using the [describe-workspaces](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspaces.html) command.

   ```
   aws workspaces describe-workspaces --directory-id directory_id
   
   {
     "Workspaces": [
       {
         ...
         "WorkspaceId": "workspace1_id",
         ...
       },
       {
         ...
         "WorkspaceId": "workspace2_id",
         ...
       },
       {
         ...
         "WorkspaceId": "workspace3_id",
         ...
       }
     ]
   }
   ```

1. Get the CloudWatch metrics for each WorkSpace in the directory using the [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) command.

   ```
   aws cloudwatch get-metric-statistics \
   --namespace AWS/WorkSpaces \
   --metric-name ConnectionFailure \
   --start-time 2015-04-27T00:00:00Z \
   --end-time 2015-04-28T00:00:00Z \
   --period 3600 \
   --statistics Sum \
   --dimensions "Name=WorkspaceId,Value=workspace_id"
   
   {
     "Datapoints" : [
       {
         "Timestamp": "2015-04-27T00:18:00Z",
         "Sum": 1.0,
         "Unit": "Count"
       },
       {
         "Timestamp": "2014-04-27T01:18:00Z",
         "Sum": 0.0,
         "Unit": "Count"
       }
     ],
     "Label" : "ConnectionFailure"
   }
   ```

# Monitor your WorkSpaces using Amazon EventBridge
<a name="cloudwatch-events"></a>

You can use events from Amazon WorkSpaces to view, search, download, archive, analyze, and respond to successful logins to your WorkSpaces. For example, you can use events for the following purposes:
+ Store or archive WorkSpaces login events as logs for future reference, analyze the logs to look for patterns, and take action based on those patterns.
+ Use the WAN IP address to determine where users are logged in from, and then use policies to allow users access only to files or data from WorkSpaces that meet the access criteria found in the event type of `WorkSpaces Access`.
+ Analyze login data and perform automated actions using AWS Lambda.
+ Use policy controls to block access to files and applications from unauthorized IP addresses.
+ Find out the WorkSpaces client version used to connect to WorkSpaces.

Amazon WorkSpaces emits these events on a best-effort basis. Events are delivered to EventBridge in near real time. With EventBridge, you can create rules that trigger programmatic actions in response to an event. For example, you can configure a rule that invokes an SNS topic to send an email notification or invokes a Lambda function to take some action. For more information, see the [Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/).

## WorkSpaces Access events
<a name="workspaces-event-types"></a>

WorkSpaces client applications send `WorkSpaces Access` events when a user successfully logs in to a WorkSpace. All WorkSpaces clients send these events.

Events emitted for WorkSpaces using DCV require the WorkSpaces client application version 4.0.1 or later.

Events are represented as JSON objects. The following is example data for a `WorkSpaces Access` event.

```
{
    "version": "0",
    "id": "64ca0eda-9751-dc55-c41a-1bd50b4fc9b7",
    "detail-type": "WorkSpaces Access",
    "source": "aws.workspaces",
    "account": "123456789012",
    "time": "2023-04-05T16:13:59Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "clientIpAddress": "192.0.2.3",
        "actionType": "successfulLogin",
        "workspacesClientProductName": "WorkSpacesWebClient",
        "loginTime": "2023-04-05T16:13:37.603Z",
        "clientPlatform": "Windows",
        "directoryId": "domain/d-123456789",
        "clientVersion": "5.7.0.3472",
        "workspaceId": "ws-xyskdga"
    }
}
```Event-specific fields

`clientIpAddress`  
The WAN IP address of the client application. For PCoIP zero clients, this is the IP address of the Teradici auth client.

`actionType`  
This value is always `successfulLogin`.

`workspacesClientProductName`  
The following values are case-sensitive.  
+ `WorkSpaces Desktop client` — Windows, macOS, and Linux clients
+ `Amazon WorkSpaces Mobile client` — iOS client
+ `WorkSpaces Mobile Client` — Android clients
+ `WorkSpaces Chrome Client` — Chromebook client
+ `WorkSpacesWebClient` — Web Access client
+ `AmazonWorkSpacesThinClient` — Amazon WorkSpaces Thin Client device
+ `Teradici PCoIP Zero Client, Teradici PCoIP Desktop Client, or Dell Wyse PCoIP Client ` — Zero Client

`loginTime`  
The time at which the user logged in to the WorkSpace.

`clientPlatform`  
+ `Android`
+ `Chrome`
+ `iOS`
+ `Linux`
+ `OSX`
+ `Windows`
+ `Teradici PCoIP Zero Client and Tera2`
+ `Web`

`directoryId`  
The identifier of the directory for the WorkSpace. You must prepend the directory identifier with `domain/`. For example, `"domain/d-123456789"`.

`clientVersion`  
The client version used to connect to WorkSpaces.

`workspaceId`  
The identifier of the WorkSpace.

## Create a rule to handle WorkSpaces events
<a name="create-event-rule"></a>

Use the following procedure to create a rule to handle the WorkSpaces events.

**Prerequisite**

To receive email notifications, create an Amazon Simple Notification Service topic.

1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).

1. In the navigation pane, choose **Topics**.

1. Choose **Create topic**.

1. For **Type**, choose **Standard**.

1. For **Name**, enter a name for your topic.

1. Choose **Create topic**.

1. Choose **Create subscription**.

1. For **Protocol**, choose **Email**.

1. For **Endpoint**, enter the email address that receives the notifications.

1. Choose **Create subscription**.

1. You'll receive an email message with the following subject line: AWS Notification - Subscription Confirmation. Follow the directions to confirm your subscription.

**To create a rule to handle WorkSpaces events**

1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).

1. Choose **Create rule**.

1. For **Name**, enter a name for your rule.

1. For **Rule type**, choose **Rule with an event pattern**.

1. Choose **Next**.

1. For **Event pattern**, do the following:

   1. For **Event source**, choose **AWS services**.

   1. For **AWS service**, choose **WorkSpaces**.

   1. For **Event type**, choose **WorkSpaces Access**.

   1. By default, we send notifications for every event. If you prefer, you can create an event pattern that filters events for specific clients or workspaces.

1. Choose **Next**.

1. Specify a target as follows:

   1. For **Target types**, choose **AWS service**.

   1. For **Select a target**, choose **SNS topic**.

   1. For **Topic**, choose the SNS topic that you created for notifications.

1. Choose **Next**.

1. (Optional) Add tags to your rule.

1. Choose **Next**.

1. Choose **Create rule**.

# Understanding AWS sign-in events for smart card users
<a name="signin-events"></a>

AWS CloudTrail logs successful and unsuccessful sign-in events for smart card users. This includes sign-in events that are captured each time a user is prompted to solve a specific credential challenge or factor, as well as the status of that particular credential verification request. A user is signed in only after completing all required credential challenges, which results in a `UserAuthentication` event being logged.

The following table captures each of the sign-in CloudTrail event names and their purposes.


| Event name | Event purpose | 
| --- | --- | 
| `CredentialChallenge` |  Notifies that AWS sign-in has requested that the user solve a specific credential challenge and specifies the `CredentialType` that is required (for example, SMARTCARD).  | 
| `CredentialVerification` |  Notifies that the user has attempted to solve a specific `CredentialChallenge` request, and specifies whether that credential has succeeded or failed.  | 
| `UserAuthentication` |  Notifies that all authentication requirements that the user was challenged with have been successfully completed and that the user was successfully signed in. When users fail to successfully complete the required credential challenges, no `UserAuthentication` event is logged.  | 

The following table captures additional useful event data fields contained within specific sign-in CloudTrail events.


| Event name | Event purpose | Sign-in event applicability | Example values | 
| --- | --- | --- | --- | 
| `AuthWorkflowID` |  Correlates all events emitted across an entire sign-in sequence. For each user sign-in, multiple events can be emitted by AWS sign-in.  |  `CredentialChallenge`, `CredentialVerification`, `UserAuthentication`  |  "AuthWorkflowID": "9de74b32-8362-4a01-a524-de21df59fd83"  | 
| `CredentialType` |  Notifies that the user has attempted to solve a specific `CredentialChallenge` request and specifies whether that credential has succeeded or failed.  |  `CredentialChallenge`, `CredentialVerification`, `UserAuthentication`  |  CredentialType": "SMARTCARD" (possible values today: SMARTCARD)  | 
| `LoginTo` |  Notifies that all authentication requirements that the user was challenged with have been successfully completed and that the user was successfully signed in. When users fail to successfully complete the required credential challenges, no `UserAuthentication` event is logged.  |  `UserAuthentication`  |  "LoginTo": "https://skylight.local“  | 

## Example events for AWS sign-in scenarios
<a name="example-event-signin"></a>

The following examples show the expected sequence of CloudTrail events for different sign-in scenarios.

**Topics**
+ [Successful sign-in when authenticating with smart card](#successful-signin)
+ [Failed sign-in when authenticating with only a smart card](#failed-signin)

### Successful sign-in when authenticating with smart card
<a name="successful-signin"></a>

The following sequence of events captures an example of a successful smart card sign-in.

**CredentialChallenge**  

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "Unknown",
        "principalId": "509318101470",
        "arn": "",
        "accountId": "509318101470",
        "accessKeyId": ""
    },
    "eventTime": "2021-07-30T17:23:29Z",
    "eventSource": "signin.amazonaws.com",
    "eventName": "CredentialChallenge", 
    "awsRegion": "us-east-1", 
    "sourceIPAddress": "AWS Internal", 
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
    "requestParameters": null,
    "responseElements": null,
    "additionalEventData": {
        "AuthWorkflowID": "6602f256-3b76-4977-96dc-306a7283269e",
        "CredentialType": "SMARTCARD"
    },
    "requestID": "65551a6d-654a-4be8-90b5-bbfef7187d3a",
    "eventID": "fb603838-f119-4304-9fdc-c0f947a82116",
    "readOnly": false,
    "eventType": "AwsServiceEvent",
    "managementEvent": true,
    "eventCategory": "Management", 
    "recipientAccountId": "509318101470", 
    "serviceEventDetails": {
        CredentialChallenge": "Success"
    }
}
```

**Successful CredentialVerification**  

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "Unknown",
        "principalId": "509318101470",
        "arn": "",
        "accountId": "509318101470",
        "accessKeyId": ""
    },
    "eventTime": "2021-07-30T17:23:39Z",
    "eventSource": "signin.amazonaws.com",
    "eventName": "CredentialVerification",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
    "requestParameters": null,
    "responseElements": null,
    "additionalEventData": {
        "AuthWorkflowID": "6602f256-3b76-4977-96dc-306a7283269e",
        "CredentialType": "SMARTCARD"
    },
    "requestID": "81869203-1404-4bf2-a1a4-3d30aa08d8d5",
    "eventID": "84c0a2ff-413f-4d0f-9108-f72c90a41b6c",
    "readOnly": false,
    "eventType": "AwsServiceEvent",
    "managementEvent": true,
    "eventCategory": "Management",
    "recipientAccountId": "509318101470",
    "serviceEventDetails": {
        CredentialVerification": "Success"
    }
}
```

**Successful UserAuthentication**  

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "Unknown",
        "principalId": "509318101470",
        "arn": "",
        "accountId": "509318101470",
        "accessKeyId": ""
    },
    "eventTime": "2021-07-30T17:23:39Z",
    "eventSource": "signin.amazonaws.com",
    "eventName": "UserAuthentication", 
    "awsRegion": "us-east-1", 
    "sourceIPAddress": "AWS Internal", 
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
    "requestParameters": null,
    "responseElements": null,
    "additionalEventData": {
        "AuthWorkflowID": "6602f256-3b76-4977-96dc-306a7283269e", 
        "LoginTo": "https://skylight.local", 
        "CredentialType": "SMARTCARD"
    },
    "requestID": "81869203-1404-4bf2-a1a4-3d30aa08d8d5", 
    "eventID": "acc0dba8-8e8b-414b-a52d-6b7cd51d38f6", 
    "readOnly": false,
    "eventType": "AwsServiceEvent", 
    "managementEvent": true,
    "eventCategory": "Management", 
    "recipientAccountId": "509318101470", 
    "serviceEventDetails": {
        UserAuthentication": "Success"
    }
}
```

### Failed sign-in when authenticating with only a smart card
<a name="failed-signin"></a>

The following sequence of events captures an example of failed smart card sign-in.

**CredentialChallenge**  

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "Unknown",
        "principalId": "509318101470",
        "arn": "",
        "accountId": "509318101470",
        "accessKeyId": ""
    },
    "eventTime": "2021-07-30T17:23:06Z",
    "eventSource": "signin.amazonaws.com",
    "eventName": "CredentialChallenge", 
    "awaRegion": "us-east-1", 
    "sourceIPAddress": "AWS Internal", 
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
    "requestParameters": null,
    "responseElements": null,
    "additionalEventData": {
        "AuthWorkflowID": "73dfd26b-f812-4bd2-82e9-0b2abb358cdb",
        "CredentialType": "SMARTCARD"
    },
    "requestID": "73eb499d-91a8-4c18-9c5d-281fd45ab50a",
    "eventID": "f30a50ec-71cf-415a-a5ab-e287edc800da",
    "readOnly": false,
    "eventType": "AwsServiceEvent",
    "managementEvent": true,
    "eventCategory": "Management", 
    "recipientAccountId": "509318101470", 
    "serviceEventDetails": {
        CredentialChallenge": "Success"
    }
}
```

**Failed CredentialVerification**  

```
{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "Unknown",
        "principalId": "509318101470",
        "arn": "",
        "accountId": "509318101470",
        "accessKeyId": ""
    },
    "eventTime": "2021-07-30T17:23:13Z",
    "eventSource": "signin.amazonaws.com",
    "eventName": "CredentialVerification",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
    "requestParameters": null,
    "responseElements": null,
    "additionalEventData": {
        "AuthWorkflowID": "73dfd26b-f812-4bd2-82e9-0b2abb358cdb",
        "CredentialType": "SMARTCARD"
    },
    "requestID": "051ca316-0b0d-4d38-940b-5fe5794fda03",
    "eventID": "4e6fbfc7-0479-48da-b7dc-e875155a8177",
    "readOnly": false,
    "eventType": "AwsServiceEvent",
    "managementEvent": true,
    "eventCategory": "Management", 
    "recipientAccountId": "509318101470", 
    "serviceEventDetails": {
        CredentialVerification": "Failure"
    }
}
```

# Create custom CloudWatch dashboards using CloudFormation templates
<a name="cloudformation-templates"></a>

AWS provides CloudFormation templates that you can use to create custom CloudWatch dashboards for WorkSpaces. Choose from the following CloudFormation template options to create custom dashboards for your WorkSpaces in the CloudFormation console.

## Considerations before getting started
<a name="before-starting-custom-cw-templates"></a>

Consider the following before you get started with custom CloudWatch dashboards:
+ Create your dashboards in the same AWS Region as the deployed WorkSpaces you want to monitor.
+ You can also create custom dashboards using the CloudWatch console.
+ A cost might be associated with custom CloudWatch dashboards. For information about pricing, see [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing)

## Help Desk dashboard
<a name="help-desk-dashboard"></a>

The Help Desk dashboard displays the following metrics for a specific WorkSpace:
+ CPU usage
+ Memory usage
+ In-session latency
+ Root volume
+ User volume
+ Packet loss
+ Disk usage

Following is an example of the Help Desk dashboard.

![\[The sample help desk dashboard for CloudWatch.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/help-desk.png)


Complete the following procedure to create a custom dashboard in CloudWatch using CloudFormation.

1. [Open the Create Stack page in the CloudFormation console](https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=YourStackName&templateURL=https://cfn-templates-global-prod-iad.s3.us-east-1.amazonaws.com/cfn-templates/workspaces_helpdesk_dashboard.yaml). This link opens the page with the Amazon S3 bucket location of the Help Desk custom CloudWatch dashboard template pre-populated.

1. Review the default selections on the **Create Stack** page. Note that the **Amazon S3 URL** field is pre-populated with the Amazon S3 bucket location of the CloudFormation template.

1. Choose **Next**.

1. In the **Stack name** text box, enter the name of the stack.

   The stack name is an identifier that helps you find a particular stack from a list of stacks. A stack name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 128 characters.

1. In the **DashboardName** text box, enter the name you want to give your dashboard.

   The dashboard name can contain only alphanumerics, dash (`–`), and underscore (`_`).

1. Choose **Next**.

1. Review the default selections on the **Configure stack options** page, and choose **Next**.

1. Scroll down to **Transforms might require access capabilities** and check the boxes for acknowledgement. Then choose **Submit** to create the stack and the custom CloudWatch dashboard.
**Important**  
A cost might be associated with custom CloudWatch dashboards. For information about pricing, see [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing)

1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. In the left navigation bar, choose **Dashboards**.

1. Under **Custom Dashboards**, choose the dashboard with the dashboard name you entered earlier in this procedure.

1. Using the Help Desk sample template, enter the UserName of the WorkSpace to monitor its data.

## Connection Insights dashboard
<a name="connection-insights-dashboard"></a>

The Connection Insights dashboard displays the client versions, platforms, and IP addresses that are connected to your WorkSpaces. This dashboard allows you to better understand how your users are connecting so that you can proactively notify your users using an outdated client. The dynamic variables allows you to monitor the details of IP addresses or specific directories.

Following is an example of the Connection Insights dashboard.

![\[The sample connection insights dashboard for CloudWatch.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/connection-insights.png)


Complete the following procedure to create a custom dashboard in CloudWatch using CloudFormation.

1. [Open the Create Stack page in the CloudFormation console](https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=YourStackName&templateURL=https://cfn-templates-global-prod-iad.s3.us-east-1.amazonaws.com/cfn-templates/workspaces_connection_insights_dashboard.yaml). This link opens the page with the Amazon S3 bucket location of the Connection Insights custom CloudWatch dashboard template pre-populated.

1. Review the default selections on the **Create Stack** page. Note that the **Amazon S3 URL** field is pre-populated with the Amazon S3 bucket location of the CloudFormation template.

1. Choose **Next**.

1. In the **Stack name** text box, enter the name of the stack.

   The stack name is an identifier that helps you find a particular stack from a list of stacks. A stack name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 128 characters.

1. In the **DashboardName** text box, enter the name you want to give your dashboard. Enter other relevant CloudWatch access group setup information.

   The dashboard name can contain only alphanumerics, dash (`–`), and underscore (`_`).

1. Under **LogRetention**, enter the number of days you want to retain your LogGroup for.

1. Under **SetupEventBridge**, choose whether you want to deploy the EventBridge rule to get WorkSpaces access logs.

1. Under **WorkSpaceAccessLogsName**, enter the name of the CloudWatch LogGroup that has the WorkSpaces access logs.

1. Choose **Next**.

1. Review the default selections on the **Configure stack options** page, and choose **Next**.

1. Scroll down to **Transforms might require access capabilities** and check the boxes for acknowledgement. Then choose **Submit** to create the stack and the custom CloudWatch dashboard.
**Important**  
A cost might be associated with custom CloudWatch dashboards. For information about pricing, see [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing)

1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. In the left navigation bar, choose **Dashboards**.

1. Under **Custom Dashboards**, choose the dashboard with the dashboard name you entered earlier in this procedure.

1. You can now monitor you WorkSpace's data using the Connection Insights dashboard.

## Internet Monitoring dashboard
<a name="cloudwatch-internet-monitoring-dashboard"></a>

The Internet Monitoring dashboard displays details about the Internet Service Provider (ISP) that your users are using to join their WorkSpaces instances. It provides details on the city, state, ASN, network name, number of connected WorkSpaces, performance, and experience scores. You can also use specific IP addresses to get the details of your users connecting from a specific location. Deploy CloudWatch internet monitor to get ISP data information. For more information, see [ Using Amazon CloudWatch Internet Monitor](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-InternetMonitor.html).

Following is an example of the Internet Monitoring dashboard.

![\[The sample Internet Monitoring dashboard for CloudWatch.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/cw-internet-monitor.png)


**To create a custom dashboard in CloudWatch using CloudFormation**
**Note**  
Before creating a custom dashboard, make sure you create an Internet Monitor with CloudWatch Internet Monitor. For more information, see [ Creating a monitor in Amazon CloudWatch Internet Monitor using the console](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/CloudWatch-IM-get-started.create.html)

1. [Open the Create Stack page in the CloudFormation console](https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=YourStackName&templateURL=https://cfn-templates-global-prod-iad.s3.us-east-1.amazonaws.com/cfn-templates/workspaces_cloudwatch_internet_monitor_dashboard.yaml). This link opens the page with the Amazon S3 bucket location of the Internet Monitoring custom CloudWatch dashboard template pre-populated.

1. Review the default selections on the **Create Stack** page. Note that the **Amazon S3 URL** field is pre-populated with the Amazon S3 bucket location of the CloudFormation template.

1. Choose **Next**.

1. In the **Stack name** text box, enter the name of the stack.

   The stack name is an identifier that helps you find a particular stack from a list of stacks. A stack name can contain only alphanumeric characters (case-sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 128 characters.

1. In the **DashboardName** text box, enter the name you want to give your dashboard. Enter other relevant CloudWatch access group setup information.

   The dashboard name can contain only alphanumerics, dash (`–`), and underscore (`_`).

1. Under **ResourcesToMonitor**, enter the directory ID of the directory that you've enabled internet monitoring for.

1. Under **MonitorName**, enter the name of the internet monitor you want to use.

1. Choose **Next**.

1. Review the default selections on the **Configure stack options** page, and choose **Next**.

1. Scroll down to **Transforms might require access capabilities** and check the boxes for acknowledgement. Then choose **Submit** to create the stack and the custom CloudWatch dashboard.
**Important**  
A cost might be associated with custom CloudWatch dashboards. For information about pricing, see [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing)

1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. In the left navigation bar, choose **Dashboards**.

1. Under **Custom Dashboards**, choose the dashboard with the dashboard name you entered earlier in this procedure.

1. You can now monitor you WorkSpace's data using the Internet Monitoring dashboard.

# Business continuity for WorkSpaces Personal
<a name="business-continuity"></a>

Amazon WorkSpaces is built on the AWS global infrastructure, which is organized into AWS Regions and Availability Zones. These Regions and Availability Zones provide resiliency in terms of both physical isolation and data redundancy. For more information, see [Resilience in Amazon WorkSpaces](disaster-recovery-resiliency.md).

Amazon WorkSpaces also provides cross-Region redirection, a feature that works with your Domain Name System (DNS) routing policies to redirect your WorkSpaces users to alternative WorkSpaces when their primary WorkSpaces aren't available. For example, by using DNS failover routing policies, you can connect your users to WorkSpaces in your specified failover Region when they can't access their WorkSpaces in the primary Region.

You can use cross-Region redirection to achieve regional resiliency and high availability. You can also use it for other purposes, such as traffic distribution or providing alternative WorkSpaces during maintenance periods. If you use Amazon Route 53 for your DNS configuration, you can take advantage of health checks that monitor Amazon CloudWatch alarms.

Amazon WorkSpaces Multi-Region Resilience provides automated, redundant virtual desktop infrastructure in a secondary WorkSpace Region and streamlines the process of redirecting users to the secondary Region when the primary Region is unreachable due to outages.

You can use WorkSpaces Multi-Region Resilience with cross-Region redirection to deploy redundant virtual desktop infrastructure in a secondary WorkSpace Region and design a cross-Region failover strategy in preparation for disruptive events. You can also use this solution for other purposes, such as traffic distribution or providing alternative WorkSpaces during maintenance periods. If you use Route 53 for your DNS configuration, you can take advantage of health checks that monitor CloudWatch alarms.

**Topics**
+ [Cross-Region redirection for WorkSpaces Personal](cross-region-redirection.md)
+ [Multi-Region Resilience for WorkSpaces Personal](multi-region-resilience.md)

# Cross-Region redirection for WorkSpaces Personal
<a name="cross-region-redirection"></a>

With the cross-Region redirection feature in Amazon WorkSpaces, you can use a fully qualified domain name (FQDN) as the registration code for your WorkSpaces. Cross-Region redirection works with your Domain Name System (DNS) routing policies to redirect your WorkSpaces users to alternative WorkSpaces when their primary WorkSpaces aren't available. For example, by using DNS failover routing policies, you can connect your users to WorkSpaces in your specified failover AWS Region when they can't access their WorkSpaces in the primary Region.

You can use cross-Region redirection along with your DNS failover routing policies to achieve regional resiliency and high availability. You can also use this feature for other purposes, such as traffic distribution or providing alternative WorkSpaces during maintenance periods. If you use Amazon Route 53 for your DNS configuration, you can take advantage of health checks that monitor Amazon CloudWatch alarms.

To use this feature, you must set up WorkSpaces for your users in two (or more) AWS Regions. You must also create special FQDN-based registration codes called *connection aliases*. These connection aliases replace Region-specific registration codes for your WorkSpaces users. (The Region-specific registration codes remain valid; however, for cross-Region redirection to work, your users must use the FQDN instead as their registration code.)

To create a connection alias, you specify a *connection string*, which is your FQDN, such as `www.example.com` or `desktop.example.com`. To use this domain for cross-Region redirection, you must register it with a domain registrar and configure the DNS service for your domain.

After you've created your connection aliases, you associate them with your WorkSpaces directories in different Regions to create *association pairs*. Each association pair has a primary Region and one or more failover Regions. If an outage occurs in the primary Region, your DNS failover routing policies redirect your WorkSpaces users to the WorkSpaces that you've set up for them in the failover Region.

To designate your primary and failover Regions, you define the Region priority (either primary or secondary) when configuring your DNS failover routing policies.

**Topics**
+ [Prerequisites](#cross-region-redirection-prerequisites)
+ [Limitations](#cross-region-redirection-limitations)
+ [Step 1: Create connection aliases](#cross-region-redirection-create-connection-aliases)
+ [(Optional) Step 2: Share a connection alias with another account](#cross-region-redirection-share-connection-alias)
+ [Step 3: Associate connection aliases with directories in each Region](#cross-region-redirection-associate-connection-aliases)
+ [Step 4: Configure your DNS service and set up DNS routing policies](#cross-region-redirection-configure-DNS-routing)
+ [Step 5: Send the connection string to your WorkSpaces users](#cross-region-redirection-send-connection-string-to-users)
+ [Cross-Region Redirection architecture diagram](#cross-region-redirection-architecture-diagram)
+ [Initiate cross-Region redirection](#initiate-cross-region-redirection)
+ [What happens during cross-Region redirection](#cross-region-redirection-what-happens)
+ [Disassociate a connection alias from a directory](#cross-region-redirection-disassociate-connection-alias)
+ [Unshare a connection alias](#cross-region-redirection-unshare-connection-alias)
+ [Delete a connection alias](#cross-region-redirection-delete-connection-alias)
+ [IAM permissions to associate and disassociate connection aliases](#cross-region-redirection-iam)
+ [Security considerations if you stop using cross-Region redirection](#cross-region-redirection-security-considerations)

## Prerequisites
<a name="cross-region-redirection-prerequisites"></a>
+ You must own and register the domain that you want to use as the FQDN in your connection aliases. If you're not already using another domain registrar, you can use Amazon Route 53 to register your domain. For more information, see [ Registering domain names using Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html) in the *Amazon Route 53 Developer Guide*.
**Important**  
You must have all necessary rights to use any domain name that you use in conjunction with Amazon WorkSpaces. You agree that the domain name does not violate or infringe on the legal rights of any third party or otherwise violate applicable law.

  The total length of your domain name can't exceed 255 characters. For more information about domain names, see [ DNS domain name format](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/DomainNameFormat.html) in the *Amazon Route 53 Developer Guide*.

  Cross-Region redirection works with both public domain names and domain names in private DNS zones. If you're using a private DNS zone, you must provide a virtual private network (VPN) connection to the virtual private cloud (VPC) that contains your WorkSpaces. If your WorkSpaces users attempt to use a private FQDN from the public internet, the WorkSpaces client applications return the following error message:

  `"We're unable to register the WorkSpace because of a DNS server issue. Contact your administrator for help."`
+ You must set up your DNS service and configure the necessary DNS routing policies. Cross-Region redirection works in conjunction with your DNS routing policies to redirect your WorkSpaces users as needed.
+ In each primary and failover Region where you want to set up cross-Region redirection, create WorkSpaces for your users. Make sure that you use the same usernames in each WorkSpaces directory in each Region. To keep your Active Directory user data in sync, we recommend using AD Connector to point to the same Active Directory in each Region where you've set up WorkSpaces for your users. For more information about creating WorkSpaces, see [Launch WorkSpaces](launch-workspaces-tutorials.md).
**Important**  
If you configure your AWS Managed Microsoft AD directory for multi-Region replication, only the directory in the primary Region can be registered for use with Amazon WorkSpaces. Attempts to register the directory in a replicated Region for use with Amazon WorkSpaces will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.

  When you've finished setting up cross-Region redirection, you must make sure your WorkSpaces users are using the FQDN-based registration code instead of the Region-based registration code (for example, `WSpdx+ABC12D`) for their primary Region. To do this, you must send them an email with the FQDN connection string by using the procedure in [Step 5: Send the connection string to your WorkSpaces users](#cross-region-redirection-send-connection-string-to-users).
**Note**  
If you create your users in the WorkSpaces console instead of creating them in Active Directory, WorkSpaces automatically sends an invitation email to your users with a Region-based registration code whenever you launch a new WorkSpace. This means that when you set up WorkSpaces for your users in the failover Region, your users will also automatically receive emails for these failover WorkSpaces. You will need to instruct your users to ignore emails with Region-based registration codes.

## Limitations
<a name="cross-region-redirection-limitations"></a>
+ Cross-Region redirection doesn't automatically check whether connections to the primary Region have failed and then fails your WorkSpaces over to another Region. In other words, automatic failover doesn't occur.

  To implement an automatic failover scenario, you must use some other mechanism in conjunction with cross-Region redirection. For example, you can use an Amazon Route 53 failover DNS routing policy paired with a Route 53 health check that monitors a CloudWatch alarm in the primary Region. If the CloudWatch alarm in the primary Region is triggered, your DNS failover routing policy then redirects your WorkSpaces users to the WorkSpaces that you've set up for them in the failover Region.
+ Cross-Region redirection is supported only on version 3.0.9 or later of the Linux, macOS, and Windows WorkSpaces client applications. You can also use cross-Region redirection with Web Access.
+ Cross-Region redirection is available in all [AWS Regions where Amazon WorkSpaces is available](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/), except for the AWS GovCloud (US) Regions and the China (Ningxia) Region. 

## Step 1: Create connection aliases
<a name="cross-region-redirection-create-connection-aliases"></a>

Using the same AWS account, create connection aliases in each primary and failover Region where you want to set up cross-Region redirection.

**To create a connection alias**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. <a name="step_select_region_create_alias"></a>In the upper-right corner of the console, select the primary AWS Region for your WorkSpaces. 

1. In the navigation pane, choose **Account Settings**.

1. Under **Cross-Region redirection**, choose **Create connection alias**.

1. For **Connection string**, enter an FQDN, such as `www.example.com` or `desktop.example.com`. A connection string can be a maximum of 255 characters. It can include only letters (A-Z and a-z), numbers (0-9), and the following characters: .-
**Important**  
After you create a connection string, it is always associated with your AWS account. You cannot recreate the same connection string with a different account, even if you delete all instances of it from the original account. The connection string is globally reserved for your account.

1. (Optional) Under **Tags**, specify any tags that you want to associate with your connection alias.

1. Choose **Create connection alias**.

1. Repeat these steps, but in [Step 2](#step_select_region_create_alias), be sure to select the failover Region for your WorkSpaces. If you have more than one failover Region, repeat these steps for each failover Region. Be sure to use the same AWS account to create the connection alias in each failover Region.

## (Optional) Step 2: Share a connection alias with another account
<a name="cross-region-redirection-share-connection-alias"></a>

You can share a connection alias with one other AWS account in the same AWS Region. Sharing a connection alias with another account gives that account permission to associate or disassociate that alias with a directory owned by that account in the same Region only. Only the account that owns a connection alias can delete the alias.

**Note**  
A connection alias can be associated with only one directory per AWS Region. If you share a connection alias with another AWS account, only one account (your account or the shared account) can associate the alias with a directory in that Region.

**To share a connection alias with another AWS account**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the upper-right corner of the console, select the AWS Region where you want to share the connection alias with another AWS account.

1. In the navigation pane, choose **Account Settings**.

1. Under **Cross-Region redirection associations**, select the connection string, and then choose **Actions**, **Share/unshare connection alias**.

   You can also share an alias from the details page for your connection alias. To do so, under **Shared account**, choose **Share connection alias**.

1. On the **Share/unshare connection alias** page, under **Share with an account**, enter the AWS account ID that you want to share your connection alias with in this AWS Region.

1. Choose **Share**.

## Step 3: Associate connection aliases with directories in each Region
<a name="cross-region-redirection-associate-connection-aliases"></a>

Associating the same connection alias with a WorkSpaces directory in two or more Regions creates an association pair between the directories. Each association pair has a primary Region and one or more failover Regions. 

For example, if your primary Region is the US West (Oregon) Region, you can pair your WorkSpaces directory in the US West (Oregon) Region with a WorkSpaces directory in the US East (N. Virginia) Region. If an outage occurs in the primary Region, cross-Region redirection works in conjunction with your DNS failover routing policies and any health checks that you've put in place on the US West (Oregon) Region to redirect your users to the WorkSpaces you've set up for them in the US East (N. Virginia) Region. For more information about the cross-Region redirection experience, see [What happens during cross-Region redirection](#cross-region-redirection-what-happens).

**Note**  
If your WorkSpaces users are located a significant distance from the failover Region (for example, thousands of miles away), their WorkSpaces experience might be less responsive than usual. To check the round-trip time (RTT) to the various AWS Regions from your location, use the [Amazon WorkSpaces Connection Health Check](https://clients.amazonworkspaces.com/Health.html).

**To associate a connection alias with a directory**

You can associate a connection alias with only one directory per AWS Region. If you have shared a connection alias with another AWS account, only one account (your account or the shared account) can associate the alias with a directory in that Region. 

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. <a name="step_select_region_associate_alias"></a>In the upper-right corner of the console, select the primary AWS Region for your WorkSpaces. 

1. In the navigation pane, choose **Account Settings**.

1. Under **Cross-Region redirection associations**, select the connection string, and then choose **Actions**, **Associate/disassociate**.

   You can also associate a connection alias with a directory from the details page for your connection alias. To do so, under **Associated directory**, choose **Associate directory**.

1. On the **Associate/disassociate** page, Under **Associate to a directory**, select the directory that you want to associate your connection alias with in this AWS Region.
**Note**  
If you configure your AWS Managed Microsoft AD directory for multi-Region replication, only the directory in the primary Region can be used with Amazon WorkSpaces. Attempts to use the directory in a replicated Region with Amazon WorkSpaces will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.

1. Choose **Associate**.

1. Repeat these steps, but in [Step 2](#step_select_region_associate_alias), be sure to select the failover Region for your WorkSpaces. If you have more than one failover Region, repeat these steps for each failover Region. Be sure to associate the same connection alias with a directory in each failover Region.

## Step 4: Configure your DNS service and set up DNS routing policies
<a name="cross-region-redirection-configure-DNS-routing"></a>

After you've created your connection aliases and your connection alias association pairs, you can then configure the DNS service for the domain that you've used in your connection strings. You can use any DNS service provider for this purpose. If you don't already have a preferred DNS service provider, you can use Amazon Route 53. For more information, see [ Configuring Amazon Route 53 as your DNS service](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-configuring.html) in the *Amazon Route 53 Developer Guide*.

After you've configured the DNS service for your domain, you must set up the DNS routing policies that you want to use for cross-Region redirection. For example, you can use Amazon Route 53 health checks to determine whether your users can connect to their WorkSpaces in a particular Region. If your users can't connect, you can use a DNS failover policy to route your DNS traffic from one Region to another.

For more information about choosing your DNS routing policy, see [Choosing a routing policy](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html) in the *Amazon Route 53 Developer Guide*. For more information about Amazon Route 53 health checks, see [ How Amazon Route 53 checks the health of your resources](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/welcome-health-checks.html) in the *Amazon Route 53 Developer Guide*.

When you're setting up your DNS routing policies, you will need the *connection identifier* for the association between the connection alias and the WorkSpaces directory in the primary Region. You will also need the connection identifier for the association between the connection alias and the WorkSpaces directory in your failover Region or Regions.

**Note**  
The connection identifier is **not** the same as the connection alias ID. The connection alias ID starts with `wsca-`.

**To find the connection identifier for a connection alias association**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. <a name="step_select_region_connection_id"></a>In the upper-right corner of the console, select the primary AWS Region for your WorkSpaces.

1. In the navigation pane, choose **Account Settings**.

1. Under **Cross-Region redirection associations**, select the connection string text (the FQDN) to view the connection alias details page.

1. On the details page for your connection alias, under **Associated directory**, make note of the value that's displayed for **Connection identifier**.

1. Repeat these steps, but in [Step 2](#step_select_region_connection_id), be sure to select the failover Region for your WorkSpaces. If you have more than one failover Region, repeat these steps to find the connection identifier for each failover Region.

**Example: To set up a DNS failover routing policy using Route 53**

The following example sets up a public hosted zone for your domain. However, you can set up a public or a private hosted zone. For more information about setting up a hosted zone, see [ Working with hosted zones](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) in the *Amazon Route 53 Developer Guide*.

This example also uses a failover routing policy. You can use other routing policy types for your cross-Region redirection strategy. For more information about choosing your DNS routing policy, see [Choosing a routing policy](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html) in the *Amazon Route 53 Developer Guide*.

When you're setting up a failover routing policy in Route 53, a health check is required for the primary Region. For more information about creating a health check in Route 53, see [ Creating Amazon Route 53 health checks and configuring DNS failover](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover.html) and [ Creating, updating, and deleting health checks](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-deleting.html) in the *Amazon Route 53 Developer Guide*.

If you want to use an Amazon CloudWatch alarm with your Route 53 health check, you'll also need to set up a CloudWatch alarm to monitor the resources in your primary Region. For more information about CloudWatch, see [ What Is Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) in the *Amazon CloudWatch User Guide*. For more information about how Route 53 uses CloudWatch alarms in its health checks, see [ How Route 53 determines the status of health checks that monitor CloudWatch alarms](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover-determining-health-of-endpoints.html#dns-failover-determining-health-of-endpoints-cloudwatch) and [ Monitoring a CloudWatch alarm](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-values.html#health-checks-creating-values-cloudwatch) in the *Amazon Route 53 Developer Guide*.

To set up a DNS failover routing policy in Route 53, you first need to create a hosted zone for your domain.

1. Open the Route 53 console at [https://console.aws.amazon.com/route53/](https://console.aws.amazon.com/route53/).

1. In the navigation pane, choose **Hosted zones**, and then choose **Create hosted zone**.

1. On the **Created hosted zone** page, enter your domain name (such as `example.com`) under **Domain name**.

1. Under **Type**, choose **Public hosted zone**.

1. Choose **Create hosted zone**.

Then create a health check for your primary Region.

1. Open the Route 53 console at [https://console.aws.amazon.com/route53/](https://console.aws.amazon.com/route53/).

1. In the navigation pane, choose **Health checks**, and then choose **Create health check**.

1. On the **Configure health check** page, enter a name for your health check.

1. For **What to monitor**, select either **Endpoint**, **Status of other health checks (calculated health check)**, or **State of CloudWatch alarm**.

1. Depending on what you've selected in the prior step, configure your health check, and then choose **Next**.

1. On the **Get notified when health check fails** page, for **Create alarm**, choose **Yes** or **No**.

1. Choose **Create health check**.

After you've created your health check, you can create the DNS failover records.

1. Open the Route 53 console at [https://console.aws.amazon.com/route53/](https://console.aws.amazon.com/route53/).

1. In the navigation pane, choose **Hosted zones**.

1. On the **Hosted zones** page, select your domain name.

1. On the details page for your domain name, choose **Create record**.

1. On the **Choose routing policy** page, select **Failover**, and then choose **Next**.

1. On the **Configure records** page, under **Basic configuration**, for **Record name**, enter your subdomain name. For example, if your FQDN is `desktop.example.com`, enter **desktop**.
**Note**  
If you want to use the root domain, leave **Record name** blank. However, we recommend using a subdomain, such as `desktop` or `workspaces`, unless you've set up the domain solely for use with your WorkSpaces.

1. For **Record type**, select **TXT – Used to verify email senders and for application-specific values**.

1. Leave the **TTL seconds** settings at the default. 

1. Under **Failover records to add to *your\$1domain\$1name***, choose **Define failover record**.

Now you need to set up the failover records for your primary and failover Regions.

**Example: To set up the failover record for your primary Region**

1. In the **Define failover record** dialog box, for **Value/route traffic to**, select **IP address or another value depending on the record type**. 

1. A box opens for you to enter your sample text entries. Enter the connection identifier for the connection alias association for your primary Region.

1. For **Failover record type**, choose **Primary**.

1. For **Health check**, select a health check that you've created for your primary Region. 

1. For **Record ID**, enter a description to identify this record. 

1. Choose **Define failover record**. Your new failover record appears under **Failover records to add to *your\$1domain\$1name***.

**Example: To set up the failover record for your failover Region**

1. Under **Failover records to add to *your\$1domain\$1name***, choose **Define failover record**.

1. In the **Define failover record** dialog box, for **Value/route traffic to**, select **IP address or another value depending on the record type**. 

1. A box opens for you to enter your sample text entries. Enter the connection identifier for the connection alias association for your failover Region.

1. For **Failover record type**, choose **Secondary**.

1. (Optional) For **Health check**, enter a health check that you've created for your failover Region. 

1. For **Record ID**, enter a description to identify this record. 

1. Choose **Define failover record**. Your new failover record appears under **Failover records to add to *your\$1domain\$1name***.

If the health check that you've set up for your primary Region fails, your DNS failover routing policy redirects your WorkSpaces users to your failover Region. Route 53 continues to monitor the health check for your primary Region, and when the health check for your primary Region no longer fails, Route 53 automatically redirects your WorkSpaces users back to their WorkSpaces in the primary Region.

For more information about creating DNS records, see [ Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html) in the *Amazon Route 53 Developer Guide*. For more information about configuring DNS TXT records, see [TXT record type](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html#TXTFormat) in the *Amazon Route 53 Developer Guide*.

## Step 5: Send the connection string to your WorkSpaces users
<a name="cross-region-redirection-send-connection-string-to-users"></a>

To make sure your users' WorkSpaces will be redirected as needed during an outage, you must send the connection string (FQDN) to your users. If you've already issued Region-based registration codes (for example, `WSpdx+ABC12D`) to your WorkSpaces users, those codes remain valid. However, for cross-Region redirection to work, your WorkSpaces users must use the connection string as their registration code when registering their WorkSpaces in the WorkSpaces client application. 

**Important**  
If you create your users in the WorkSpaces console instead of creating them in Active Directory, WorkSpaces automatically sends an invitation email to your users with a Region-based registration code (for example, `WSpdx+ABC12D`) whenever you launch a new WorkSpace. Even if you've already set up cross-Region redirection, the invitation email that's automatically sent for new WorkSpaces contains this Region-based registration code instead of your connection string.  
To make sure your WorkSpaces users are using the connection string instead of the Region-based registration code, you must send them another email with the connection string by using the procedure below. 

**To send the connection string to your WorkSpaces users**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the upper-right corner of the console, select the primary AWS Region for your WorkSpaces.

1. In the navigation pane, choose **WorkSpaces**.

1. On the **WorkSpaces** page, use the search box to search for a user that you want to send an invitation to, and then select the corresponding WorkSpace from the search results. You can select only one WorkSpace at a time. 

1. Choose **Actions**, **Invite User**.

1. On the **Invite Users to Their WorkSpaces** page, you will see an email template to send to your users. 

1. (Optional) If there is more than one connection alias associated with your WorkSpaces directory, select the connection string that you want your users to use from the **Connection alias string** list. The email template updates to display the string that you've chosen.

1. Copy the email template text and paste it into an email to the users using your own email application. In your email application, you can modify the text as needed. When the invitation email is ready, send it to your users.

## Cross-Region Redirection architecture diagram
<a name="cross-region-redirection-architecture-diagram"></a>

The following diagram describes the deployment process of cross-Region redirection.

![\[Cross-Region redirection\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/Doppel-admin-LT-MRR.png)


**Note**  
Cross-Region redirection only facilitates cross-Region failover and fallback. It doesn't facilitate creating and maintaining WorkSpaces in the secondary Region and doesn't allow cross-Region data replication. WorkSpaces in both the primary and secondary Regions should be managed separately.

## Initiate cross-Region redirection
<a name="initiate-cross-region-redirection"></a>

In the event of an outage, you can either update the DNS records manually or use automated routing policies based on health checks, which determine the failover Region. We recommend following the disaster recovery mechanisms outlined in [ Creating Disaster Recovery Mechanisms Using Amazon Route 53](https://aws.amazon.com/blogs/networking-and-content-delivery/creating-disaster-recovery-mechanisms-using-amazon-route-53/).

## What happens during cross-Region redirection
<a name="cross-region-redirection-what-happens"></a>

During Region failover, your WorkSpaces users are disconnected from their WorkSpaces in the primary Region. When they attempt to reconnect, they receive the following error message:

`We can't connect to your WorkSpace. Check your network connection, and then try again.`

Your users are then prompted to log in again. If they're using the FQDN as their registration code, when they log in again, your DNS failover routing policies redirect them to the WorkSpaces that you've set up for them in the failover Region.

**Note**  
In some cases, users might be unable to reconnect when they log in again. If this behavior occurs, they must close and restart the WorkSpaces client application, and then try to log in again.

## Disassociate a connection alias from a directory
<a name="cross-region-redirection-disassociate-connection-alias"></a>

Only the account that owns a directory can disassociate a connection alias from the directory. 

If you've shared a connection alias with another account and that account has associated the connection alias with a directory owned by that account, that account must be used to disassociate the connection alias from the directory.

**To disassociate a connection alias from a directory**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the upper-right corner of the console, select the AWS Region that contains the connection alias that you want to disassociate.

1. In the navigation pane, choose **Account Settings**.

1. Under **Cross-Region redirection associations**, select the connection string, and then choose **Actions**, **Associate/disassociate**.

   You can also dissociate a connection alias from the connection alias details page. To do so, under **Associated directory**, choose **Disassociate**. 

1. On the **Associate/disassociate** page, choose **Disassociate**.

1. In the dialog box that asks you to confirm the disassociation, choose **Disassociate**.

## Unshare a connection alias
<a name="cross-region-redirection-unshare-connection-alias"></a>

Only the owner of a connection alias can unshare the alias. If you unshare a connection alias with an account, that account can no longer associate the connection alias with a directory.

**To unshare a connection alias**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the upper-right corner of the console, select the AWS Region that contains the connection alias that you want to unshare.

1. In the navigation pane, choose **Account Settings**.

1. Under **Cross-Region redirection associations**, select the connection string, and then choose **Actions**, **Share/unshare connection alias**.

   You can also unshare a connection alias from the connection alias details page. To do so, under **Shared account**, choose **Unshare**.

1. On the **Share/unshare connection alias** page, choose **Unshare**.

1. In the dialog box that asks you to confirm unsharing the connection alias, choose **Unshare**.

## Delete a connection alias
<a name="cross-region-redirection-delete-connection-alias"></a>

You can delete a connection alias only if it is owned by your account and if it isn't associated with a directory. 

If you've shared a connection alias with another account and that account has associated the connection alias with a directory owned by that account, that account must first disassociate the connection alias from the directory before you can delete the connection alias. 

**Important**  
After you create a connection string, it is always associated to your AWS account. You cannot recreate the same connection string with a different account, even if you delete all instances of it from the original account. The connection string is globally reserved for your account.

**Warning**  
**If you will no longer be using an FQDN as the registration code for your WorkSpaces users, you must take certain precautions to prevent potential security issues.** For more information, see [Security considerations if you stop using cross-Region redirection](#cross-region-redirection-security-considerations).

**To delete a connection alias**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the upper-right corner of the console, select the AWS Region that contains the connection alias that you want to delete.

1. In the navigation pane, choose **Account Settings**.

1. Under **Cross-Region redirection associations**, select the connection string, and then choose **Delete**.

   You can also delete a connection alias from the connection alias details page. To do so, choose **Delete** in the upper-right corner of the page.
**Note**  
If the **Delete** button is disabled, make sure that you are the owner of the alias, and make sure that the alias isn't associated with a directory.

1. In the dialog box that asks you to confirm deletion, choose **Delete**.

## IAM permissions to associate and disassociate connection aliases
<a name="cross-region-redirection-iam"></a>

If you use an IAM user to associate or disassociate connection aliases, the user must have permissions for `workspaces:AssociateConnectionAlias` and `workspaces:DisassociateConnectionAlias`.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "workspaces:AssociateConnectionAlias",
        "workspaces:DisassociateConnectionAlias"
      ],
      "Resource": [
          "arn:aws:workspaces:us-east-1:123456789012:connectionalias/wsca-a1bcd2efg"
      ]
    }
  ]
}
```

------

**Important**  
If you are creating an IAM policy for associating or disassociating connection aliases for accounts that don't own the connection aliases, you cannot specify an account ID in the ARN. Instead, you must use `*` for the account ID, as shown in the following example policy.  

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "workspaces:AssociateConnectionAlias",
        "workspaces:DisassociateConnectionAlias"
      ],
      "Resource": [
          "arn:aws:workspaces:us-east-1:*:connectionalias/wsca-a1bcd2efg"
      ]
    }
  ]
}
```
You can specify an account ID in the ARN only when that account owns the connection alias to be associated or disassociated.

For more information about working with IAM, see [Identity and access management for WorkSpaces](workspaces-access-control.md).

## Security considerations if you stop using cross-Region redirection
<a name="cross-region-redirection-security-considerations"></a>

If you will no longer be using an FQDN as the registration code for your WorkSpaces users, you must take the following precautions to prevent potential security issues:
+ Be sure to issue your WorkSpaces users the Region-specific registration code (for example, `WSpdx+ABC12D`) for their WorkSpaces directory and instruct them to stop using the FQDN as their registration code.
+ **If you still own this domain**, be sure to update your DNS TXT record to remove this domain so that it cannot be exploited in a phishing attack. If you remove this domain from your DNS TXT record and your WorkSpaces users attempt to use the FQDN as their registration code, their connection attempts will fail harmlessly. 
+ **If you no longer own this domain**, your WorkSpaces users **must** use their Region-specific registration code. If they continue trying to use the FQDN as their registration code, their connection attempts could be redirected to a malicious site.

# Multi-Region Resilience for WorkSpaces Personal
<a name="multi-region-resilience"></a>

Amazon WorkSpaces Multi-Region Resilience (MRR) enables you to redirect users to a secondary Region when your primary WorkSpaces Region is unreachable due to disruptive events, without requiring your users to switch registration codes when logging to their standby WorkSpaces. Standby WorkSpaces is a feature of Amazon WorkSpaces Multi-Region Resilience that streamlines the standby deployment creation and management. After setting up a user directory in your secondary Region, select the WorkSpace in your primary Region that you want to create a standby WorkSpace for. The system automatically mirrors the primary WorkSpace bundle images to the secondary Region. It then automatically provisions a new standby WorkSpace in your secondary Region

Amazon WorkSpaces Multi-Region Resilience is built upon cross-Region redirection that leverages DNS health check and failover capabilities. It allows you to use a fully qualified domain name (FQDN) as your WorkSpaces registration code. When your users log in to WorkSpaces, you can redirect them across supported WorkSpaces Regions based on your Domain Name System (DNS) policies for the FQDN. If you use Amazon Route 53, we recommend using health checks that monitor Amazon CloudWatch alarms when devising a cross-Region redirection strategy for WorkSpaces. For more information, see [ Creating Amazon Route 53 health checks and configuring DNS failover](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-failover.html) in the *Amazon Route 53 Developer Guide*.

Data replication is an add-on feature of standby WorkSpaces that replicates data one-way from the primary Region to the secondary Region. After enabling data replication, EBS snapshots of the system and user volumes are taken every 12 hours. Multi-Region Resilience regularly checks for fresh snapshots. When the snapshots are found, it initiates a copy to the secondary Region. As copies arrive in the secondary Region, they are used to update the secondary WorkSpace.

**Topics**
+ [Prerequisites](#multi-region-resilience-prerequisites)
+ [Limitations](#multi-region-resilience-limitations)
+ [Configure your Multi-Region Resilience standby WorkSpace](#multi-region-resilience-congfigurations)
+ [Create a standby WorkSpace](#create-standby-workspace)
+ [Manage a standby WorkSpace](#manage-standby-workspace)
+ [Delete a standby WorkSpace](#delete-standby-workspace)
+ [One-way data replication for standby WorkSpaces](#one-way-data-replication)
+ [Plan to reserve Amazon EC2 capacity for recovery](#mrr-ec2-recovery)

## Prerequisites
<a name="multi-region-resilience-prerequisites"></a>
+ You must create WorkSpaces for your users in the primary Region before creating standby WorkSpaces. For more information about creating WorkSpaces, see [Create a directory for WorkSpaces Personal](launch-workspaces-tutorials.md).
+ To enable data replication on standby WorkSpaces, you should have either a self- managed Active Directory or an AWS Managed Microsoft AD configured to replicate to your standby Regions. For more information, see [ Create your AWS Managed Microsoft AD directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started_create_directory.html) and [ Add a replicated Region](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/multi-region-add-region.html).
+ Ensure you update networking dependency drivers like ENA, NVMe, and PV drivers on your primary WorkSpaces. You should do this at least once every 6 months. For more information, see [ Install or upgrade Elastic Network Adapter (ENA) driver ](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/enhanced-networking-ena.html#ena-adapter-driver-install-upgrade-win), [AWS NVMe drivers for Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/aws-nvme-drivers.html), and [Upgrade PV drivers on Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Upgrading_PV_drivers.html).
+ Ensure you update the EC2Config, EC2Launch, and EC2Launch V2 agents to the latest versions periodically. You should do this at least once every 6 months. For more information, see [Update EC2Config and EC2Launch](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/migrating-latest-types.html#upgdate-ec2config-ec2launch).
+ To ensure proper data replication, ensure the Active Directories in the primary and secondary regions are in sync for FQDN, OU, and user SID.
+ The default quota (limit) for standby WorkSpaces is 0. You need to request a service quota increase before creating a standby WorkSpace. For more information, see [Amazon WorkSpaces quotas](workspaces-limits.md).
+ Ensure you are using [customer managed keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) to encrypt both your primary and standby WorkSpaces. You can either use single Region keys or [multi-Region keys](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) to encrypt your primary and standby WorkSpaces. 

## Limitations
<a name="multi-region-resilience-limitations"></a>
+ Standby WorkSpaces only copies the bundle image of your primary WorkSpaces but it doesn't copy the system volume (drive C) or user volume (drive D) from your primary WorkSpaces. To copy the system volume (drive C) or user volume (drive D) from your primary WorkSpaces to standby WorkSpaces, you have to enable data replication.
+ You cannot directly modify, rebuild, restore, or migrate a standby WorkSpace.
+ Failover for cross-Region redirection is controlled by your DNS settings. To implement an automatic failover scenario, you must use a different mechanism in conjunction with cross-Region redirection. For example, you can use an Amazon Route 53 failover DNS routing policy paired with a Route 53 health check that monitors a CloudWatch alarm in the primary Region. If the CloudWatch alarm in the primary Region is invoked, your DNS failover routing policy then redirects your WorkSpaces users to the WorkSpaces that you've set up for them in the failover Region.
+ Data replication only goes one way, copying data from primary Region to secondary Region. During standby WorkSpaces failover, you can access the data and application between 12 and 24 hours. After an outage, manually back up any data that you created on the secondary WorkSpace and log out. We recommend saving your work to external drives, such as your network drive, so that you can access your data from the primary WorkSpace.
+ Data replication does not support AWS Simple AD.
+ When you enable data replication on standby WorkSpaces, EBS snapshots of the primary WorkSpaces (both root and system volumes) are taken every 12 hours. The initial snapshot for a particular data volume is full and subsequent snapshots are incremental. As a result, the first replication for a given WorkSpace will take longer than subsequent ones. Snapshots are initiated on a schedule that is internal to WorkSpaces and you cannot control the timing.
+ If the primary WorkSpace and standby WorkSpace join using the same domain, we recommend that you only connect to either the primary WorkSpace or standby WorkSpace at a given point in time to avoid losing connection with the domain controller.
+ If you configure your AWS Managed Microsoft AD for Multi-Region replication, only the directory in the primary Region can be registered for use with WorkSpaces. If you try to register the directory in a replicated Region for use with WorkSpaces, it will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with WorkSpaces within replicated Regions.
+ If you’ve already set up your cross-Region redirection and created WorkSpaces in both your primary and secondary Regions without using standby WorkSpaces, you cannot convert the existing WorkSpace in the secondary Region to a standby WorkSpace directly. Instead, you need to shut down the WorkSpace in your secondary Region, select the WorkSpace in your primary Region that you want to create a standby WorkSpace for, and use standby WorkSpaces to create the standby WorkSpace. 
+ After an outage, manually back up any data that you created on the secondary WorkSpace and log out. We recommend saving your work to external drives, such as your network drive, so that you can access your data from the primary WorkSpace.
+ WorkSpaces Multi-Region Resilience is currently available in the following Regions:
  + US East (N. Virginia) Region
  + US West (Oregon) Region
  + Europe (Frankfurt) Region
  + Europe (Ireland) Region
+ WorkSpaces Multi-Region Resilience is only supported on version 3.0.9 or later of the Linux, macOS, and Windows WorkSpaces client applications. You can also use Multi-Region Resilience with Web Access.
+ WorkSpaces Multi-Region Resilience supports Windows and Bring Your Own License (BYOL) WorkSpaces. It doesn't support Amazon Linux 2, Ubuntu, Red Hat Enterprise Linux, GeneralPurpose.4xlarge, GeneralPurpose.8xlarge, or GPU-enabled WorkSpaces (e.g., Graphics G6, Graphics.g4dn, or GraphicsPro.g4dn).
+ After failover or failback completes, wait 15 to 30 minutes before connecting to your WorkSpace.

## Configure your Multi-Region Resilience standby WorkSpace
<a name="multi-region-resilience-congfigurations"></a>

**To configure your Multi-Region Resilience standby WorkSpace**

1. Set up user directories in both your primary and secondary Regions. Ensure that you use the same user names in each WorkSpaces directory in each Region.

   To keep your Active Directory user data in sync, we recommend using AD Connector to point to the same Active Directory in each Region where you've set up WorkSpaces for your users. For more information about creating a directory, see [ Register a directory with WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/register-deregister-directory.html).
**Important**  
If you configure your AWS Managed Microsoft AD directory for multi-Region replication, only the directory in the primary Region can be registered for use with WorkSpaces. Attempts to register the directory in a replicated Region for use with WorkSpaces will fail. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with WorkSpaces within replicated Regions.

1. Create WorkSpaces for your users in the primary Region. For more information about creating WorkSpaces, see [ Launch WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/launch-workspaces-tutorials.html).

1. Create a standby WorkSpace in the secondary Region. For more information about creating a standby WorkSpace, see [ Create a standby WorkSpace](https://docs.aws.amazon.com/workspaces/latest/adminguide/multi-region-resilience.html#create-standby-workspace).

1. Create and associate connection strings (FQDN) with user directories in primary and secondary Regions.

   You must enable cross-Region redirection in your account because standby WorkSpaces is built upon cross-Region redirection. Follow step 1 - 3 of the instructions for [ Cross-Region redirection for Amazon WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/cross-region-redirection.html#cross-region-redirection-create-connection-aliases).

1. Configure DNS service and set up DNS routing policies.

   You must set up your [ DNS service and configure the necessary DNS routing policies](https://docs.aws.amazon.com/workspaces/latest/adminguide/cross-region-redirection.html#cross-region-redirection-configure-DNS-routing). Cross-Region redirection works in conjunction with your DNS routing policies to redirect your WorkSpaces users as needed.

1. When you've finished setting up cross-Region redirection, you must send your users an email with a FQDN connection string. For more information see [ Step 5: Send the connection string to your WorkSpaces users](https://docs.aws.amazon.com/workspaces/latest/adminguide/cross-region-redirection.html#cross-region-redirection-send-connection-string-to-users). Ensure your WorkSpaces users are using the FQDN-based registration code instead of the Region-based registration code (for example, WSpdx\$1ABC12D) for their primary Region.
**Important**  
If you create your users in the WorkSpaces console instead of creating them in Active Directory, WorkSpaces automatically sends an invitation email to your users with a Region-based registration code whenever you launch a new WorkSpace. This means that when you set up WorkSpaces for your users in the secondary Region, your users will also automatically receive emails for these secondary WorkSpaces. You will need to instruct your users to ignore emails with Region-based registration codes.
The Region-specific registration codes remain valid; however, for cross- Region redirection to work, your users must use the FQDN instead as their registration code.

## Create a standby WorkSpace
<a name="create-standby-workspace"></a>

Before you create a standby WorkSpace, ensure you have completed the prerequisites, including creating a user directory in both primary and secondary Regions, provisioning WorkSpaces for your users in your primary Region, configuring cross-Region redirection in your account, and requesting standby WorkSpaces limit increase through the service quota.

**To create a standby WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the upper-right corner of the console, select the primary AWS Region for your WorkSpaces. 

1. In the navigation pane, choose **WorkSpaces**.

1. Select a WorkSpace you want to create a standby WorkSpace for.

1. Choose **Actions** and then choose **Create standby WorkSpace**.

1. Select the secondary Region, where you will create your standby WorkSpace, and then choose **Next**.

1. Select the user directory in your secondary Region and then choose **Next**.

1. (Optional) Add encryption key, enable data encryption, and manage tags.
   + To add an encryption key, enter it under Input encryption key.
   + To enable data replication, choose **Enable data replication**. Then, check the checkbox to confirm that you authorize additional monthly charge.
   + To add a new tag, choose **Add new tag**.

   Then, choose **Next**.
**Note**  
If the original WorkSpace is encrypted, this field is prepopulated. However, you can choose to replace it with your own encryption key.
It takes a few minutes to update the data replication status.
After the standby WorkSpace is successfully updated with the snapshots from the primary WorkSpace, you can find the times stamps of the snapshots under **Recovery Snapshot**.

1. Review the settings of your standby WorkSpaces and then choose **Create**.
**Note**  
To view information about your standby WorkSpaces, go to the primary WorkSpace detail page.
The standby WorkSpace only copies the bundle image of your primary WorkSpace but it does not copy the system volume (drive C) or user volume (drive D) from your primary WorkSpaces. By default, data replication is off. To copy the system volume (drive C) or user volume (drive D) from your primary WorkSpaces to standby WorkSpaces, you have to enable data replication.

## Manage a standby WorkSpace
<a name="manage-standby-workspace"></a>

You cannot directly modify, rebuild, restore, or migrate a standby WorkSpace.

**To enable data replication for your standby WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. Go to your primary Region, select the primary WorkSpace ID. 

1. Scroll down to the Standby WorkSpace section and choose **Edit Standby WorkSpace**.

1. Choose **Enable data replication**. Then, check the checkbox to confirm that you authorize additional monthly charge. Then, choose **Save**.

**Note**  
Standby WorkSpaces cannot hibernate. If you stop the standby WorkSpace, it does not preserve your unsaved work. We recommend users to always save their work before exiting their standby WorkSpaces.
To enable data replication on standby WorkSpaces, you should have either a self- managed Active Directory or an AWS Managed Microsoft AD configured to replicate to your standby Regions. To set up your directories, follow steps 1 to 3 in the Walkthrough section of [ Building for business continuity with Amazon WorkSpaces and AWS Directory Services ](https://aws.amazon.com/blogs/desktop-and-application-streaming/building-for-business-continuity-with-amazon-workspaces-and-aws-directory-services/#:~:text=Region(s).-,Walkthrough,-Step%201%3A%20Provision) or see [ Using multi-Region AWS Managed Active Directory with Amazon WorkSpaces ](https://docs.aws.amazon.com/whitepapers/latest/best-practices-deploying-amazon-workspaces/using-multi-region-aws-managed-active-directory-with-amazon-workspaces.html). Multi-Region replication is only supported for the Enterprise Edition of AWS Managed Microsoft AD.
It takes a few minutes to update the data replication status.
After the standby WorkSpace is successfully updated with the snapshots from the primary WorkSpace, you can find the times stamps of the snapshots under **Recovery Snapshot**.

## Delete a standby WorkSpace
<a name="delete-standby-workspace"></a>

You can terminate a standby WorkSpace the same way you terminate a regular WorkSpace. 

**To delete a standby WorkSpace**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the upper-right corner of the console, select the primary AWS Region for your WorkSpaces. 

1. In the navigation pane, choose **WorkSpaces**.

1. Select the standby WorkSpace and choose **Delete**. It takes approximately 5 minutes to delete a standby WorkSpace. During deletion, the status of the standby WorkSpace will be set to **Terminating**. When the deletion is complete, the standby WorkSpace disappears from the console.

**Note**  
Deleting a standby WorkSpace is a permanent action and cannot be undone. The standby WorkSpace user's data does not persist and is destroyed. For help with backing up user data, contact AWS Support.

## One-way data replication for standby WorkSpaces
<a name="one-way-data-replication"></a>

Enabling data replication in Multi-Region Resilience allows you to replicate data from a primary Region to a secondary Region. During steady state, Multi-Region Resilience captures snapshots of the system (C drive) and data (D drive) of primary WorkSpaces every 12 hours. These snapshots are transferred to the secondary Region and used to update the standby WorkSpaces. By default, data replication is disabled for standby WorkSpaces.

After data replication is enabled for the standby WorkSpaces, the initial snapshot for a particular data volume is complete, while subsequent snapshots are incremental. As a consequence, the first replication for a given WorkSpace will take longer than subsequent ones. Snapshots are triggered at predetermined intervals within WorkSpaces and the timing cannot be controlled by users.

![\[One-way data replication for standby WorkSpaces\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/Doppel-admin-LT-one-way.png)


During failover, when users are redirected to the secondary Region, they can access their standby WorkSpaces with data and applications that are between 12 and 24 hours old. While users are using standby WorkSpaces, Multi-Region Resilience will not force them to log out of their standby WorkSpaces or update the standby WorkSpaces with the snapshots from the primary Region.

After an outage, users should manually back up any data they have created on their secondary WorkSpaces before logging out of their standby WorkSpaces. When they log in again, they will be directed to the primary Region and their primary WorkSpaces.

## Plan to reserve Amazon EC2 capacity for recovery
<a name="mrr-ec2-recovery"></a>

Amazon Multi-Region Resilience(MRR) relies on Amazon EC2 On-Demand pools by default. If a specific Amazon EC2 instance type is unavailable to support your recovery, MRR will automatically attempt to scale up the instance repeatedly until an available instance type is found, but in extreme circumstances, instances may not always be available. To improve the availability of the required instance types you need for your most critical WorkSpaces, contact AWS Support and we will assist you on capacity planning.

# Troubleshoot issues for WorkSpaces Personal
<a name="amazon-workspaces-troubleshooting"></a>

The following information can help you troubleshoot issues with your WorkSpaces.

**Tip**  
You can also use Amazon WorkSpaces Advisor to identify and resolve issues with AI-powered troubleshooting. For more information, see [What is Amazon WorkSpaces Advisor?](workspaces-advisor.md).

## Enabling advanced logging
<a name="advanced-logging"></a>

To help troubleshoot issues that your users might experience, you can enable advanced logging on any Amazon WorkSpaces client.

Advanced logging generates log files that contain diagnostic information and debugging-level details, including verbose performance data. For the 1.0\$1 and 2.0\$1 clients, these advanced logging files are automatically uploaded to a database in AWS.

**Note**  
To get AWS review of advanced logging files, and to receive technical support for issues with your WorkSpaces clients, contact AWS Support. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/).

### To enable advanced logging for Web Access
<a name="logging-web-access"></a>

**To enable advanced logging for Web Access**

1. Open your Amazon WorkSpaces Web Access client.

1. At the top of the WorkSpaces sign in page, choose **Diagnostic logging**.

1. In the pop-up dialog box, ensure that **Diagnostic logging** is enabled.

1. For **Log level**, choose **Advanced logging**.

**To access log files in Google Chrome, Microsoft Edge, and Firefox**

1. Open the context (right-click) menu on the browsers or press **Ctrl**\$1**Shift**\$1**I** (or for Mac, **command**\$1**option**\$1**I**) on your keyboard to open the developer tools panel.

1. In the developer tools panel, choose the **Console** tab to find the log files.

**To access log files in Safari**

1. Choose **Safari**, **Settings**.

1. In the **Settings** window, choose the **Advanced** tab.

1. Choose **Show Develop menu in menu bar**.

1. From the **Develop** tab in the menu bar, choose **Develop** > **Show Web Inspector**.

1. In the Safari Web Inspector panel, choose the **Console** tab to find the log files.

### To enable advanced logging for 4.0\$1 clients
<a name="logging-new-clients"></a>

**Topics**

The Windows client logs are stored in the following location:

`%LOCALAPPDATA%\Amazon Web Services\Amazon WorkSpaces\logs`

**To enable advanced logging for Windows clients**

1. Close the Amazon WorkSpaces client.

1. Open the Command Prompt app.

1. Launch the WorkSpaces client with the `-l3` flag.

   `c:`

   `cd "C:\Program Files\Amazon Web Services, Inc\Amazon WorkSpaces"`

   `workspaces.exe -l3`
**Note**  
If WorkSpaces is installed for one user and not all users, use the following commands:  
`c:`  
`cd "%LocalAppData%\Programs\Amazon Web Services, Inc\Amazon WorkSpaces"`  
`workspaces.exe -l3`

**Topics**

The macOS client logs are stored in the following location:

`~/Library/"Application Support"/"Amazon Web Services"/"Amazon WorkSpaces"/logs`

**To enable advanced logging for macOS clients**

1. Close the Amazon WorkSpaces client.

1. Open Terminal.

1. Run the following command.

   `open -a workspaces --args -l3`

**Topics**

**To enable advanced logging for Android clients**

1. Close the Amazon WorkSpaces client.

1. Open the Android client menu.

1. Select **Support**.

1. Select **Logging settings**.

1. Select **Enable advanced logging**.

**To retrieve logs for Android clients after enabling advanced logging:**
+ Select **Extract log** to save zipped logs locally.

**Topics**

The Linux client logs are stored in the following location:

`~/.local/share/Amazon Web Services/Amazon WorkSpaces/logs`

**To enable advanced logging for Linux clients**

1. Close the Amazon WorkSpaces client.

1. Open Terminal.

1. Run the following command.

   `/opt/workspacesclient/workspacesclient -l3`

### To enable advanced logging for 3.0 clients
<a name="logging-new-clients"></a>

**Topics**

The Windows client logs are stored in the following location:

`%LOCALAPPDATA%\Amazon Web Services\Amazon WorkSpaces\logs`

**To enable advanced logging for Windows clients**

1. Close the Amazon WorkSpaces client.

1. Open the Command Prompt app.

1. Launch the WorkSpaces client with the `-l3` flag.

   `c:`

   `cd "C:\Program Files (x86)\Amazon Web Services, Inc\Amazon WorkSpaces"`

   `workspaces.exe -l3`
**Note**  
If WorkSpaces is installed for one user and not all users, use the following commands:  
`c:`  
`cd "%LocalAppData%\Programs\Amazon Web Services, Inc\Amazon WorkSpaces"`  
`workspaces.exe -l3`

**Topics**

The macOS client logs are stored in the following location:

`~/Library/"Application Support"/"Amazon Web Services"/"Amazon WorkSpaces"/logs`

**To enable advanced logging for macOS clients**

1. Close the Amazon WorkSpaces client.

1. Open Terminal.

1. Run the following command.

   `open -a workspaces --args -l3`

**Topics**

**To enable advanced logging for Android clients**

1. Close the Amazon WorkSpaces client.

1. Open the Android client menu.

1. Select **Support**.

1. Select **Logging settings**.

1. Select **Enable advanced logging**.

**To retrieve logs for Android clients after enabling advanced logging:**
+ Select **Extract log** to save zipped logs locally.

**Topics**

The Linux client logs are stored in the following location:

`~/.local/share/Amazon Web Services/Amazon WorkSpaces/logs`

**To enable advanced logging for Linux clients**

1. Close the Amazon WorkSpaces client.

1. Open Terminal.

1. Run the following command.

   `/opt/workspacesclient/workspacesclient -l3`

### To enable advanced logging for 1.0\$1 and 2.0\$1 clients
<a name="logging-legacy-clients"></a>

1. Open the WorkSpaces client.

1. Choose the gear icon in the upper-right corner of the client application.

1. Choose **Advanced Settings**.

1. Select the **Enable Advanced Logging** check box.

1. Choose **Save**.

The Windows client logs are stored in the following location:

`%LOCALAPPDATA%\Amazon Web Services\Amazon WorkSpaces\1.0\Logs`

The macOS client logs are stored in the following location:

`~/Library/Logs/Amazon Web Services/Amazon WorkSpaces/1.0`

## Troubleshoot specific issues
<a name="troubleshooting-specific-issues"></a>

The following information can help you troubleshoot specific issues with your WorkSpaces.

**Topics**
+ [I can't create an Amazon Linux WorkSpace because there are non-valid characters in the user name](#linux_workspace_provision_fail_username)
+ [I changed the shell for my Amazon Linux WorkSpace and now I can't provision a PCoIP session](#linux_workspace_provision_fail_shell_override)
+ [My Amazon Linux WorkSpaces won't start](#linux_workspace_provision_fail_pcoip_agent_upgrade)
+ [Launching WorkSpaces in my connected directory often fails](#provision_fail)
+ [Launching WorkSpaces fails with an internal error](#launch-failure-ipv6)
+ [When I try to register a directory, the registration fails and leaves the directory in an ERROR state](#cannot-register-directory)
+ [My users can't connect to a Windows WorkSpace with an interactive logon banner](#logon_banner)
+ [My users can't connect to a Windows WorkSpace](#gpo_security_user_rights)
+ [My users are having issues when they try to log on to WorkSpaces from WorkSpaces Web Access](#byol_logon_issues)
+ [The Amazon WorkSpaces client displays a gray "Loading..." screen for a while before returning to the login screen. No other error message appears.](#loading_screen)
+ [My users receive the message "WorkSpace Status: Unhealthy. We were unable to connect you to your WorkSpace. Please try again in a few minutes."](#unhealthy_cant_connect)
+ [My users receive the message "This device is not authorized to access the WorkSpace. Please contact your administrator for assistance."](#device_not_authorized)
+ [My users receive the message "No network. Network connection lost. Check your network connection or contact your administrator for help." when trying to connect to a DCV WorkSpace](#no_network)
+ [The WorkSpaces client gives my users a network error, but they are able to use other network-enabled apps on their devices](#network_error)
+ [My WorkSpace users see the following error message: "Device can't connect to the registration service. Check your network settings."](#registration_service_failure)
+ [My PCoIP zero client users are receiving the error "The supplied certificate is invalid due to timestamp"](#pcoip_zero_client_ntp)
+ [USB printers and other USB peripherals aren't working for PCoIP zero clients](#pcoip_zero_client_usb)
+ [My users skipped updating their Windows or macOS client applications and aren't getting prompted to install the latest version](#client_update_skipped)
+ [My users are unable to install the Android client application on their Chromebooks](#install_android_chromebook)
+ [My users aren't receiving invitation emails or password reset emails](#welcome_emails)
+ [My users don't see the Forgot password? option on the client login screen](#forgot_password)
+ [I receive the message "The system administrator has set policies to prevent this installation" when I try to install applications on a Windows WorkSpace](#msi_wont_install)
+ [No WorkSpaces in my directory can connect to the internet](#no_internet)
+ [My WorkSpace has lost its internet access](#lost_internet_access)
+ [I receive a "DNS unavailable" error when I try to connect to my on-premises directory](#dns_unavailable)
+ [I receive a "Connectivity issues detected" error when I try to connect to my on-premises directory](#connectivity_issues_detected)
+ [I receive an "SRV record" error when I try to connect to my on-premises directory](#srv_record_not_found)
+ [My Windows WorkSpace goes to sleep when it's left idle](#windows_workspace_sleeps_when_idle)
+ [One of my WorkSpaces has a state of `UNHEALTHY`](#unhealthy)
+ [My WorkSpace is unexpectedly crashing or rebooting](#crash_web_access)
+ [The same username has more than one WorkSpace, but the user can log in to only one of the WorkSpaces](#multiple_workspaces_same_username)
+ [I'm having trouble using Docker with Amazon WorkSpaces](#docker_support)
+ [I receive ThrottlingException errors to some of my API calls](#throttled-api-calls)
+ [My WorkSpace keeps disconnecting when I let it run in the background](#workspaces-disconnecting)
+ [SAML 2.0 federation isn't working. My users are not authorized to stream their WorkSpaces desktop.](#saml-federation-not-working)
+ [My users are getting disconnected from their WorkSpaces session every 60 minutes.](#disconnected-workspace)
+ [My users get a redirect URI error when they federate using the SAML 2.0 identity provider (IdP)-initiated flow, or an additional instance of the WorkSpaces client application starts every time my users attempt to sign in from the client after federating to the IdP.](#invalid-redirect-uri)
+ [My users receive the message, "Something went wrong: An error occurred while launching your WorkSpace" when they attempt to sign in to the WorkSpaces client application after federating to the IdP.](#federating-error-message)
+ [My users receive the message, "Unable to validate tags” when they attempt to sign in to the WorkSpaces client application after federating to the IdP.](#unable-to-validate-tags)
+ [My users receive the message, "The client and the server cannot communicate, because they do not possess a common algorithm".](#no-common-algorithm)
+ [My microphone or web cam is not working on Windows WorkSpaces.](#microphone-not-working)
+ [My users cannot log in using certificate-based authentication and are prompted for the password either at the WorkSpaces client or the Windows sign-on screen when they connect to their desktop session.](#cert-based-auth-troubleshooting)
+ [I am trying to do something that requires Windows installation media but WorkSpaces does not provide it.](#install-media-troubleshooting)
+ [I want to launch WorkSpaces with an existing AWS Managed Directory created in an unsupported WorkSpaces Region.](#unsupported-regions-troubleshooting)
+ [I want to update Firefox on Amazon Linux 2.](#firefox_al2)
+ [My user is able to reset their password using the WorkSpaces client, ignoring the Fine Grained Password Policy (FFGP) setting that is configured on AWS Managed Microsoft AD.](#password-setting-mad)
+ [My users receive the error message "This OS/platform is not authorized to access your WorkSpace" when trying to access the Windows/Linux WorkSpace using Web Access](#os-authorized-access)
+ [My user's WorkSpace is showing as unhealthy after they connect to an AutoStop WorkSpace that is in the stopped state](#autostop-unhealthy)
+ [Gnome crashes on WorkSpaces Ubuntu bundles after login](#gnome-crashes-ubuntu)

### I can't create an Amazon Linux WorkSpace because there are non-valid characters in the user name
<a name="linux_workspace_provision_fail_username"></a>

For Amazon Linux WorkSpaces, user names: 
+ Can contain a maximum of 20 characters
+ Can contain letters, spaces, and numbers that are representable in UTF-8
+ Can include the following special characters: \$1.-\$1
+ Cannot begin with a dash symbol (-) as the first character of the user name

**Note**  
These limitations do not apply to Windows WorkSpaces. Windows WorkSpaces support the @ and - symbols for all characters in the user name.

### I changed the shell for my Amazon Linux WorkSpace and now I can't provision a PCoIP session
<a name="linux_workspace_provision_fail_shell_override"></a>

To override the default shell for Linux WorkSpaces, see [Override the default shell for Amazon Linux WorkSpaces](manage_linux_workspace.md#linux_shell). 

### My Amazon Linux WorkSpaces won't start
<a name="linux_workspace_provision_fail_pcoip_agent_upgrade"></a>

Starting July 20, 2020, Amazon Linux WorkSpaces will be using new license certificates. These new certificates are compatible only with versions 2.14.1.1, 2.14.7, 2.14.9, and 20.10.6 or later of the PCoIP agent. 

If you're using an unsupported version of the PCoIP agent, you must upgrade it to the latest version (20.10.6), which has the latest fixes and performance improvements that are compatible with the new certificates. If you don't make these upgrades by July 20, session provisioning for your Linux WorkSpaces will fail and your end users won't be able to connect to their WorkSpaces.

**To upgrade your PCoIP agent to the latest version**

1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

1. In the navigation pane, choose **WorkSpaces**.

1. Select your Linux WorkSpace, and reboot it by choosing **Actions**, **Reboot WorkSpaces**. If the WorkSpace status is `STOPPED`, you must choose **Actions**, **Start WorkSpaces** first and wait until its status is `AVAILABLE` before you can reboot it.

1. <a name="step_maintenance_mode"></a>After your WorkSpace has rebooted and its status is `AVAILABLE`, we recommend that you change the status of the WorkSpace to `ADMIN_MAINTENANCE` while you are performing this upgrade. When you are finished, change the status of the WorkSpace to `AVAILABLE`. For more information about `ADMIN_MAINTENANCE` mode, see [ Manual Maintenance](https://docs.aws.amazon.com/workspaces/latest/adminguide/workspace-maintenance.html#admin-maintenance).

   To change the status of a WorkSpace to `ADMIN_MAINTENANCE`, do the following:

   1. Select the WorkSpace and choose **Actions**, **Modify WorkSpace**.

   1. Choose **Modify State**.

   1. For **Intended State**, select **ADMIN\$1MAINTENANCE**.

   1. Choose **Modify**.

1. Connect to your Linux WorkSpace through SSH. For more information, see [Enable SSH connections for your Linux WorkSpaces in WorkSpaces Personal](connect-to-linux-workspaces-with-ssh.md). 

1. To update the PCoIP agent, run the following command:

   ```
   sudo yum --enablerepo=pcoip-stable install pcoip-agent-standard-20.10.6
   ```

1. To verify the agent version and to confirm that the update succeeded, run the following command:

   ```
   rpm -q pcoip-agent-standard
   ```

   The verification command should produce following result:

   ```
   pcoip-agent-standard-20.10.6-1.el7.x86_64
   ```

1. Disconnect from the WorkSpace and reboot it again. 

1. If you set the status of the WorkSpace to `ADMIN_MAINTENANCE` in [Step 4](#step_maintenance_mode), repeat [Step 4](#step_maintenance_mode) and set **Intended State** to `AVAILABLE`.

If your Linux WorkSpace still fails to start after you upgrade the PCoIP agent, contact AWS Support.

### Launching WorkSpaces in my connected directory often fails
<a name="provision_fail"></a>

Verify that the two DNS servers or domain controllers in your on-premises directory are accessible from each of the subnets that you specified when you connected to your directory. You can verify this connectivity by launching an Amazon EC2 instance in each subnet and joining the instance to your directory using the IP addresses of the two DNS servers.

### Launching WorkSpaces fails with an internal error
<a name="launch-failure-ipv6"></a>

Check whether your subnets are configured to automatically assign IPv6 addresses to instances launched in the subnet. To check this setting, open the Amazon VPC console, select your subnet, and choose **Subnet Actions**, **Modify auto-assign IP settings**. If this setting is enabled, you cannot launch WorkSpaces using the Performance or Graphics bundles. Instead, disable this setting and specify IPv6 addresses manually when you launch your instances.

### When I try to register a directory, the registration fails and leaves the directory in an ERROR state
<a name="cannot-register-directory"></a>

This problem can occur if you're trying to register an AWS Managed Microsoft AD directory that has been configured for multi-Region replication. Although the directory in the primary Region can be successfully registered for use with Amazon WorkSpaces, attempting to register the directory in a replicated Region fails. Multi-Region replication with AWS Managed Microsoft AD isn't supported for use with Amazon WorkSpaces within replicated Regions.

### My users can't connect to a Windows WorkSpace with an interactive logon banner
<a name="logon_banner"></a>

If an interactive logon message has been implemented to display a logon banner, this prevents users from being able to access their Windows WorkSpaces. The interactive logon message Group Policy setting is not currently supported by PCoIP WorkSpaces. Move the WorkSpaces to an organizational unit (OU) where the **Interactive logon: Message text for users attempting to log on** Group Policy isn’t applied. The logon message is supported on DCV WorkSpaces, and users have to login again after accepting the logon banner. 

### My users can't connect to a Windows WorkSpace
<a name="gpo_security_user_rights"></a>

My users receive the following error when they try to connect to their Windows WorkSpaces:

```
"An error occurred while launching your WorkSpace. Please try again."
```

This error often occurs when the WorkSpace can't load the Windows desktop using PCoIP. Check the following:
+ This message appears if the PCoIP Standard Agent for Windows service is not running. [Connect using RDP](https://aws.amazon.com/premiumsupport/knowledge-center/connect-workspace-rdp/) to verify that the service is running, that it's set to start automatically, and that it can communicate over the management interface (eth0).
+ If the PCoIP agent was uninstalled, reboot the WorkSpace through the Amazon WorkSpaces console to reinstall it automatically.
+ You might also receive this error on the Amazon WorkSpaces client after a long delay if the [WorkSpaces security group](amazon-workspaces-security-groups.md) was modified to restrict outbound traffic. Restricting outbound traffic prevents Windows from communicating with your directory controllers for login. Verify that your security groups allow your WorkSpaces to communicate with your directory controllers on all [required ports](workspaces-port-requirements.md) over the primary network interface.

Another cause of this error is related to the User Rights Assignment Group Policy. If the following group policy is incorrectly configured, it prevents users from being able to access their Windows WorkSpaces:

**Computer Configuration\$1Windows Settings\$1Security Settings\$1Local Policies\$1User Rights Assignment**
+ **Incorrect policy:**

  Policy: **Access this computer from the network**

  Setting: *Domain name*\$1Domain Computers

  Winning GPO: Allow File Access
+ **Correct policy:**

  Policy: **Access this computer from the network**

  Setting: *Domain name*\$1Domain Users

  Winning GPO: Allow File Access

**Note**  
This policy setting should be applied to **Domain Users** instead of **Domain Computers**.

For more information, see [ Access this computer from the network - security policy setting](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/access-this-computer-from-the-network) and [ Configure security policy settings](https://docs.microsoft.com/windows/security/threat-protection/security-policy-settings/how-to-configure-security-policy-settings) in the Microsoft Windows documentation.

### My users are having issues when they try to log on to WorkSpaces from WorkSpaces Web Access
<a name="byol_logon_issues"></a>

Amazon WorkSpaces relies on a specific logon screen configuration to enable users to successfully log on from their Web Access client.

To enable Web Access users to log on to their WorkSpaces, you must configure a Group Policy setting and three Security Policy settings. If these settings are not correctly configured, users might experience long logon times or black screens when they try to log on to their WorkSpaces. To configure these settings, see [Enable and configure WorkSpaces Web Access for WorkSpaces Personal](web-access.md).

**Important**  
Beginning October 1, 2020, customers will no longer be able to use the Amazon WorkSpaces Web Access client to connect to Windows 7 custom WorkSpaces or to Windows 7 Bring Your Own License (BYOL) WorkSpaces.

### The Amazon WorkSpaces client displays a gray "Loading..." screen for a while before returning to the login screen. No other error message appears.
<a name="loading_screen"></a>

This behavior usually indicates that the WorkSpaces client can authenticate over port 443, but can't establish a streaming connection over port 4172 (PCoIP) or port 4195 (DCV). This situation can occur when [network prerequisites](workspaces-port-requirements.md) aren't met. Issues on the client side often cause the network check in the client to fail. To see which health checks are failing, choose the network check icon (typically a red triangle with an exclamation point in the bottom-right corner of the login screen for 2.0\$1 clients or the network icon ![\[Network icon\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/network-icon.png) in the upper-right corner of the 3.0\$1 clients).

**Note**  
The most common cause of this problem is a client-side firewall or proxy preventing access over port 4172 or 4195 (TCP and UDP). If this health check fails, check your local firewall settings.

If the network check passes, there might be a problem with the network configuration of the WorkSpace. For example, a Windows Firewall rule might block port UDP 4172 or 4195 on the management interface. [ Connect to the WorkSpace using a Remote Desktop Protocol (RDP) client](https://aws.amazon.com/premiumsupport/knowledge-center/connect-workspace-rdp/) to verify that the WorkSpace meets the necessary [ port requirements](workspaces-port-requirements.md).

### My users receive the message "WorkSpace Status: Unhealthy. We were unable to connect you to your WorkSpace. Please try again in a few minutes."
<a name="unhealthy_cant_connect"></a>

This error usually indicates the SkyLightWorkSpacesConfigService service isn't responding to health checks.

If you just rebooted or started your WorkSpace, wait a few minutes, and then try again.

If the WorkSpace has been running for some time and you still see this error, [connect using RDP](https://aws.amazon.com/premiumsupport/knowledge-center/connect-workspace-rdp/) to verify that the SkyLightWorkSpacesConfigService service:
+ Is running.
+ Is set to start automatically.
+ Can communicate over the management interface (eth0).
+ Isn't blocked by any third-party antivirus software.

### My users receive the message "This device is not authorized to access the WorkSpace. Please contact your administrator for assistance."
<a name="device_not_authorized"></a>

This error indicates that one of the following might be occurring:
+ [IP access control groups](amazon-workspaces-ip-access-control-groups.md) are configured on the WorkSpace directory, but the client IP address isn't allowlisted.

  Check the settings on your directory. Confirm that the public IP address the user is connecting from allows access to the WorkSpace.
+ Under access control, your device’s operating system isn’t allowed as a trusted device or your device doesn’t have the proper certificates installed when using the **Trusted devices** option. Add your device type as a trusted device by doing the following: 

  1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

  1. In the navigation pane, choose **Directories**.

  1. Choose the directory you're using.

  1. Scroll down to **Access control options** and choose **Edit**.

  1. Under **Trusted devices**, for the device types you want to allow access to, choose **Allow all** in the drop-down. If you want to restrict the devices to ones that have client certificates installed, choose **Trusted devices**. 

  1. If you chose **Trusted devices** in the previous step, ensure you have imported at least one root certificate and that the client certificate that has been issued by the root certification authority (CA) has been installed on the client. For more information about creating, deploying, and importing root certificates, see [Restrict access to trusted devices for WorkSpaces Personal](trusted-devices.md).

  1. Choose **Save**.
+ Your device types are not granted access to WorkSpaces. Grant access to your device type by doing the following:

  1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).

  1. In the navigation pane, choose **Directories**.

  1. Choose the directory you're using.

  1. Scroll down to **Other platforms** and choose **Edit**.

  1. Check from one of the following device types you want to grant WorkSpaces access.
     + ChromeOS
     + iOS
     + Linux
     + Web Access
     + Zero Clients

  1. Choose **Save**.



### My users receive the message "No network. Network connection lost. Check your network connection or contact your administrator for help." when trying to connect to a DCV WorkSpace
<a name="no_network"></a>

If this error occurs and your users don't have connectivity issues, make sure that port 4195 is open on your network's firewalls. For WorkSpaces using DCV, the port used to stream the client session was changed from 4172 to 4195.

### The WorkSpaces client gives my users a network error, but they are able to use other network-enabled apps on their devices
<a name="network_error"></a>

The WorkSpaces client applications rely on access to resources in the AWS Cloud, and require a connection that provides at least 1 Mbps download bandwidth. If a device has an intermittent connection to the network, the WorkSpaces client application might report an issue with the network.

WorkSpaces enforces the use of digital certificates issued by Amazon Trust Services, as of May 2018. Amazon Trust Services is already a trusted Root CA on the operating systems that are supported by WorkSpaces. If the Root CA list for the operating system is not up to date, the device cannot connect to WorkSpaces and the client gives a network error.

**To recognize connection issues due to certificate failures**
+ PCoIP zero clients — The following error message is displayed.

  ```
  Failed to connect. The server provided a certificate that is invalid. See below for details:
  - The supplied certificate is invalid due to timestamp
  - The supplied certificate is not rooted in the devices local certificate store
  ```
+ Other clients — The health checks fail with a red warning triangle for **Internet**.

**Topics**
+ [Windows client application](#certificate-issues-windows)
+ [PCoIP zero clients](#certificate-issues-zero-clients)
+ [Other client applications](#certificate-issues-other)

#### Windows client application
<a name="certificate-issues-windows"></a>

Use one of the following solutions for certificate failures.

**Solution 1: Update the client application**  
Download and install the latest Windows client application from [https://clients.amazonworkspaces.com/](https://clients.amazonworkspaces.com/) . During installation, the client application ensures that your operating system trusts certificates issued by Amazon Trust Services.

**Solution 2: Add Amazon Trust Services to the local Root CA list**

1. Open [https://www.amazontrust.com/repository/](https://www.amazontrust.com/repository/).

1. Download the Starfield certificate in DER format (2b071c59a0a0ae76b0eadb2bad23bad4580b69c3601b630c2eaf0613afa83f92).

1. Open the Microsoft Management Console. (From the Command Prompt, run **mmc**.)

1. Choose **File**, **Add/Remove Snap-in**, **Certificates**, **Add**.

1. On the **Certificates snap-in** page, select **Computer account** and choose **Next**. Keep the default, **Local computer**. Choose **Finish**. Choose **OK**.

1. Expand **Certificates (Local Computer)** and select **Trusted Root Certification Authorities**. Choose **Action**, **All Tasks**, **Import**.

1. Follow the wizard to import the certificate that you downloaded.

1. Exit and restart the WorkSpaces client application.

**Solution 3: Deploy Amazon Trust Services as a trusted CA using Group Policy**  
Add the Starfield certificate to the trusted Root CAs for the domain using Group Policy. For more information, see [Use Policy to Distribute Certificates](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc772491(v=ws.11)).

#### PCoIP zero clients
<a name="certificate-issues-zero-clients"></a>

To connect directly to a WorkSpace using firmware version 6.0 or later, download and install the certificate issued by Amazon Trust Services.

**To add Amazon Trust Services as a trusted Root CA**

1. Open [https://certs.secureserver.net/repository/](https://certs.secureserver.net/repository/).

1. Download the certificate under **Starfield Certificate Chain** with the thumbprint 14 65 FA 20 53 97 B8 76 FA A6 F0 A9 95 8E 55 90 E4 0F CC 7F AA 4F B7 C2 C8 67 75 21 FB 5F B6 58.

1. Upload the certificate to the zero client. For more information, see [Uploading Certificates](https://www.teradici.com/web-help/TER1504003/6.0/default.htm#05_Managing/04_UploadCertificate.htm) in the Teradici documentation.

#### Other client applications
<a name="certificate-issues-other"></a>

Add the Starfield certificate (2b071c59a0a0ae76b0eadb2bad23bad4580b69c3601b630c2eaf0613afa83f92) from [Amazon Trust Services](https://www.amazontrust.com/repository/). For more information about how to add a Root CA, see the following documentation:
+ Android: [Add & remove certificates](https://support.google.com/nexus/answer/2844832)
+ Chrome OS: [Manage client certificates on Chrome devices](https://support.google.com/chrome/a/answer/6080885)
+ macOS and iOS: [Installing a CA's Root Certificate on Your Test Device](https://developer.apple.com/library/content/qa/qa1948/_index.html#/apple_ref/doc/uid/DTS40017603-CH1-SECINSTALLING)

### My WorkSpace users see the following error message: "Device can't connect to the registration service. Check your network settings."
<a name="registration_service_failure"></a>

When a registration service failure occurs, your WorkSpace users might see the following error message on the **Connection Health Check** page: "Your device is not able to connect to the WorkSpaces Registration service. You will not be able to register your device with WorkSpaces. Please check your network settings."

This error occurs when the WorkSpaces client application can't reach the registration service. Typically, this happens when the WorkSpaces directory has been deleted. To resolve this error, make sure that the registration code is valid and corresponds to a running directory in the AWS Cloud.

### My PCoIP zero client users are receiving the error "The supplied certificate is invalid due to timestamp"
<a name="pcoip_zero_client_ntp"></a>

If Network Time Protocol (NTP) isn't enabled in Teradici, your PCoIP zero client users might receive certificate failure errors. To set up NTP, see [Set up PCoIP zero clients for WorkSpaces Personal](set-up-pcoip-zero-client.md).

### USB printers and other USB peripherals aren't working for PCoIP zero clients
<a name="pcoip_zero_client_usb"></a>

Starting with version 20.10.4 of the PCoIP agent, Amazon WorkSpaces disables USB redirection by default through the Windows registry. This registry setting affects the behavior of USB peripherals when your users are using PCoIP zero client devices to connect to their WorkSpaces. 

If your WorkSpaces are using version 20.10.4 or later of the PCoIP agent, USB peripheral devices won't work with PCoIP zero client devices until you've enabled USB redirection.

**Note**  
If you're using 32-bit virtual printer drivers, you must also update those drivers to their 64-bit versions.

**To enable USB redirection for PCoIP zero client devices**

We recommend that you push out these registry changes to your WorkSpaces through Group Policy. For more information, see [ Configuring the agent](https://www.teradici.com/web-help/pcoip_agent/standard_agent/windows/20.10/admin-guide/configuring/configuring/) and [ Configurable settings](https://www.teradici.com/web-help/pcoip_agent/standard_agent/windows/20.10/admin-guide/configuring/configuring/#enabledisable-usb-in-the-pcoip-session) in the Teradici documentation.

1. Set the following registry key value to 1 (enabled):

   KeyPath = **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Policies\$1Teradici\$1PCoIP\$1pcoip\$1admin**

   KeyName = **pcoip.enable\$1usb**

   KeyType = **DWORD**

   KeyValue = **1**

1. Set the following registry key value to 1 (enabled):

   KeyPath = **HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Policies\$1Teradici\$1PCoIP\$1pcoip\$1admin\$1defaults**

   KeyName = **pcoip.enable\$1usb**

   KeyType = **DWORD**

   KeyValue = **1**

1. If you haven't already done so, log out of the WorkSpace, and then log back in. Your USB devices should now work.

### My users skipped updating their Windows or macOS client applications and aren't getting prompted to install the latest version
<a name="client_update_skipped"></a>

When users skip updates to the Amazon WorkSpaces Windows client application, the **SkipThisVersion** registry key gets set, and they are no longer prompted to update their clients when a new version of the client is released. To update to the latest version, you can edit the registry as described in [ Update the WorkSpaces Windows Client Application to a Newer Version](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-windows-client.html#windows_setup) in the *Amazon WorkSpaces User Guide*. You can also run the following PowerShell command: 

```
Remove-ItemProperty -Path "HKCU:\Software\Amazon Web Services. LLC\Amazon WorkSpaces\WinSparkle" -Name "SkipThisVersion"
```

When users skip updates to the Amazon WorkSpaces macOS client application, the `SUSkippedVersion` preference gets set, and they are no longer prompted to update their clients when a new version of the client is released. To update to the latest version, you can reset this preference as described in [ Update the WorkSpaces macOS Client Application to a Newer Version](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-osx-client.html#osx_setup) in the *Amazon WorkSpaces User Guide*.

### My users are unable to install the Android client application on their Chromebooks
<a name="install_android_chromebook"></a>

Version 2.4.13 is the final release of the Amazon WorkSpaces Chromebook client application. Because [ Google is phasing out support for Chrome Apps](https://blog.chromium.org/2020/01/moving-forward-from-chrome-apps.html), there will be no further updates to the WorkSpaces Chromebook client application, and its use is unsupported.

For [ Chromebooks that support installing Android applications](https://sites.google.com/a/chromium.org/dev/chromium-os/chrome-os-systems-supporting-android-apps), we recommend using the [ WorkSpaces Android client application](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-android-client.html) instead.

In some cases, you might need to enable your users' Chromebooks to install Android applications. For more information, see [Set up Android for Chromebook for WorkSpaces Personal](set-up-android-chromebook.md).

### My users aren't receiving invitation emails or password reset emails
<a name="welcome_emails"></a>

Users do not automatically receive welcome or password reset emails for WorkSpaces that were created using AD Connector or a trusted domain. Invitation emails also aren't sent automatically if the user already exists in Active Directory.

To manually send welcome emails to these users, see [Send an invitation email](manage-workspaces-users.md#send-invitation).

To reset user passwords, see [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md).

### My users don't see the Forgot password? option on the client login screen
<a name="forgot_password"></a>

If you're using AD Connector or a trusted domain, your users won't be able to reset their own passwords. (The **Forgot password?** option on the WorkSpaces client application login screen won't be available.) For information about how to reset user passwords, see [Set up Active Directory Administration Tools for WorkSpaces Personal](directory_administration.md).

### I receive the message "The system administrator has set policies to prevent this installation" when I try to install applications on a Windows WorkSpace
<a name="msi_wont_install"></a>

You can address this issue by modifying the Windows Installer Group Policy setting. To deploy this policy to multiple WorkSpaces in your directory, apply this setting to a Group Policy object that is linked to the WorkSpaces organizational unit (OU) from a domain-joined EC2 instance. If you are using AD Connector, you can make these changes from a domain controller. For more information about using the Active Directory administration tools to work with Group Policy objects, see [Installing the Active Directory Administration Tools](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_install_ad_tools.html) in the *AWS Directory Service Administration Guide*.

The following procedure shows how to configure the Windows Installer setting for the WorkSpaces Group Policy object.

1. Make sure that the most recent [WorkSpaces Group Policy administrative template](group_policy.md#gp_install_template) is installed in your domain.

1. Open the Group Policy Management tool on your Windows WorkSpace client and navigate to and select the WorkSpaces Group Policy object for your WorkSpaces machine accounts. From the main menu, choose **Action**, **Edit**.

1. In the Group Policy Management Editor, choose **Computer Configuration**, **Policies**, **Administrative Templates**, **Classic Administrative Templates**, **Windows Components**, **Windows Installer**.

1. Open the **Turn Off Windows Installer** setting.

1. In the **Turn Off Windows Installer** dialog box, change **Not Configured** to **Enabled**, and then set **Disable Windows Installer** to **Never**.

1. Choose **OK**.

1. To apply the group policy changes, do one of the following:
   + Reboot the WorkSpace (in the WorkSpaces console, select the WorkSpace, then choose **Actions**, **Reboot WorkSpaces**).
   + From an administrative command prompt, enter **gpupdate /force**.

### No WorkSpaces in my directory can connect to the internet
<a name="no_internet"></a>

WorkSpaces cannot communicate with the internet by default. You must explicitly provide internet access. For more information, see [Provide internet access for WorkSpaces Personal](amazon-workspaces-internet-access.md).

### My WorkSpace has lost its internet access
<a name="lost_internet_access"></a>

If your WorkSpace has lost access to the internet and you can't [connect to the WorkSpace by using RDP](https://aws.amazon.com/premiumsupport/knowledge-center/connect-workspace-rdp/), this issue is probably caused by the loss of the public IP address for the WorkSpace. If you have [enabled automatic assignment of Elastic IP addresses](automatic-assignment.md) at the directory level, an [ Elastic IP address](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-eips.html) (from the Amazon-provided pool) is assigned to your WorkSpace when it is launched. However, if you associate an Elastic IP address that you own to a WorkSpace, and then you later disassociate that Elastic IP address from the WorkSpace, the WorkSpace loses its public IP address, and it doesn't automatically get a new one from the Amazon-provided pool.

To associate a new public IP address from the Amazon-provided pool with the WorkSpace, you must [rebuild the WorkSpace](rebuild-workspace.md). If you don't want to rebuild the WorkSpace, you must associate another Elastic IP address that you own to the WorkSpace.

We recommend that you not modify the elastic network interface of a WorkSpace after the WorkSpace is launched. After an Elastic IP address has been assigned to a WorkSpace, the WorkSpace retains the same public IP address (unless the WorkSpace is rebuilt, in which case it gets a new public IP address).

### I receive a "DNS unavailable" error when I try to connect to my on-premises directory
<a name="dns_unavailable"></a>

You receive an error message similar to the following when connecting to your on-premises directory.

```
DNS unavailable (TCP port 53) for IP: dns-ip-address
```

AD Connector must be able to communicate with your on-premises DNS servers via TCP and UDP over port 53. Verify that your security groups and on-premises firewalls allow TCP and UDP communication over this port.

### I receive a "Connectivity issues detected" error when I try to connect to my on-premises directory
<a name="connectivity_issues_detected"></a>

You receive an error message similar to the following when connecting to your on-premises directory.

```
Connectivity issues detected: LDAP unavailable (TCP port 389) for IP: ip-address
Kerberos/authentication unavailable (TCP port 88) for IP: ip-address
Please ensure that the listed ports are available and retry the operation.
```

AD Connector must be able to communicate with your on-premises domain controllers via TCP and UDP over the following ports. Verify that your security groups and on-premises firewalls allow TCP and UDP communication over these ports:
+ 88 (Kerberos)
+ 389 (LDAP)

### I receive an "SRV record" error when I try to connect to my on-premises directory
<a name="srv_record_not_found"></a>

You receive an error message similar to one or more of the following when connecting to your on-premises directory.

```
SRV record for LDAP does not exist for IP: dns-ip-address

SRV record for Kerberos does not exist for IP: dns-ip-address
```

AD Connector needs to obtain the `_ldap._tcp.dns-domain-name` and `_kerberos._tcp.dns-domain-name` SRV records when connecting to your directory. You get this error if the service cannot obtain these records from the DNS servers that you specified when connecting to your directory. Make sure that your DNS servers contain these SRV records. For more information, see [SRV Resource Records](https://technet.microsoft.com/en-us/library/cc961719.aspx) on Microsoft TechNet.

### My Windows WorkSpace goes to sleep when it's left idle
<a name="windows_workspace_sleeps_when_idle"></a>

To resolve this issue, connect to the WorkSpace and change the power plan to **High performance** by using the following procedure:

1. From the WorkSpace, open **Control Panel**, then choose **Hardware** or choose **Hardware and Sound** (the name might differ, depending on your version of Windows).

1. Under **Power Options**, choose **Choose a power plan**. 

1. In the **Choose or customize a power plan** pane, choose the **High performance** power plan, and then choose **Change plan settings**. 
   + If the option to choose the **High performance** power plan is disabled, choose **Change settings that are currently unavailable**, and then choose the **High performance** power plan. 
   + If the **High performance** plan isn't visible, choose the arrow to the right of **Show additional plans** to display it, or choose **Create a power plan** in the left navigation, choose **High performance**, give the power plan a name, and then choose **Next**. 

1. On the **Change settings for the plan: High performance** page, make sure **Turn off the display** and (if available) **Put the computer to sleep** are set to **Never**.

1. If you made any changes to the high performance plan, choose **Save changes** (or choose **Create** if you're creating a new plan).

If the preceding steps do not solve the issue, do the following: 

1. From the WorkSpace, open **Control Panel**, then choose **Hardware** or choose **Hardware and Sound** (the name might differ, depending on your version of Windows).

1. Under **Power Options**, choose **Choose a power plan**. 

1. In the **Choose or customize a power plan** pane, choose the **Change plan settings** link to the right of the **High performance** power plan, then choose the **Change advanced power settings** link.

1. In the **Power Options** dialog box, in the list of settings, choose the plus sign to the left of **Hard disk** to display the relevant settings. 

1. Verify that the **Turn off hard disk after** value for **Plugged in** is greater than the value for **On battery** (the default value is 20 minutes).

1. Choose the plus sign to the left of **PCI Express**, and do the same for **Link State Power Management**.

1. Verify that the **Link State Power Management** settings are **Off**.

1. Choose **OK** (or **Apply** if you changed any settings) to close the dialog box.

1. In the **Change settings for the plan** pane, if you changed any settings, choose **Save changes**.

### One of my WorkSpaces has a state of `UNHEALTHY`
<a name="unhealthy"></a>

The WorkSpaces service periodically sends status requests to a WorkSpace. A WorkSpace is marked `UNHEALTHY` when it fails to respond to these requests. Common causes for this problem are:
+ An application on the WorkSpace is blocking network ports, which prevents the WorkSpace from responding to the status request.
+ High CPU utilization is preventing the WorkSpace from responding to the status request in a timely manner.
+ The computer name of the WorkSpace has been changed. This prevents a secure channel from being established between WorkSpaces and the WorkSpace.

You can attempt to correct the situation using the following methods:
+ Reboot the WorkSpace from the WorkSpaces console.
+ Connect to the unhealthy WorkSpace using the following procedure, which should be used only for troubleshooting purposes:

  1. Connect to an operational WorkSpace in the same directory as the unhealthy WorkSpace.

  1. From the operational WorkSpace, use Remote Desktop Protocol (RDP) to connect to the unhealthy WorkSpace using the IP address of the unhealthy WorkSpace. Depending on the extent of the problem, you might not be able to connect to the unhealthy WorkSpace.

  1. On the unhealthy WorkSpace, confirm that the minimum [port requirements](workspaces-port-requirements.md) are met.
+ Make sure the SkyLightWorkSpacesConfigService service can respond to health checks. To troubleshoot this issue, see [My users receive the message "WorkSpace Status: Unhealthy. We were unable to connect you to your WorkSpace. Please try again in a few minutes."](#unhealthy_cant_connect).
+ Rebuild the WorkSpace from the WorkSpaces console. Because rebuilding a WorkSpace can potentially cause a loss of data, this option should be used only if all other attempts to correct the problem have been unsuccessful.

### My WorkSpace is unexpectedly crashing or rebooting
<a name="crash_web_access"></a>

If your WorkSpace configured for PCoIP is repeatedly crashing or rebooting and your error logs or crash dumps are pointing to problems with `spacedeskHookKmode.sys` or `spacedeskHookUmode.dll`, or if you're receiving the following error messages, you might need to disable Web Access to the WorkSpace:

```
The kernel power manager has initiated a shutdown transition.
Shutdown reason: Kernel API
```

```
The computer has rebooted from a bugcheck.
```

**Note**  
These troubleshooting steps are not applicable to WorkSpaces that are configured for DCV. They are applicable only to WorkSpaces that are configured for PCoIP.
You should disable Web Access only if you aren't allowing your users to use Web Access.

To disable Web Access to the WorkSpace, you must disable Web Access in the WorkSpaces directory and reboot the WorkSpace.

### The same username has more than one WorkSpace, but the user can log in to only one of the WorkSpaces
<a name="multiple_workspaces_same_username"></a>

If you delete a user in Active Directory (AD) without first deleting their WorkSpace and then you add the user back to Active Directory and create a new WorkSpace for that user, the same username will now have two WorkSpaces in the same directory. However, if the user tries to connect to their original WorkSpace, they will receive the following error:

```
"Unrecognized user. No WorkSpace found under your username. Contact your administrator to request one."
```

Additionally, searches for the username in the Amazon WorkSpaces console return only the new WorkSpace, even though both WorkSpaces still exist. (You can find the original WorkSpace by searching for the WorkSpace ID instead of the username.)

This behavior can also occur if you rename a user in Active Directory without first deleting their WorkSpace. If you then change their username back to the original username and create a new WorkSpace for the user, the same username will have two WorkSpaces in the directory. 

This problem occurs because Active Directory uses the user's security identifier (SID), rather than the username, to uniquely identify the user. When a user is deleted and recreated in Active Directory, the user is assigned a new SID, even if their username remains the same. During searches for a username, the Amazon WorkSpaces console uses the SID to search Active Directory for matches. The Amazon WorkSpaces clients also use the SID to identify users when they are connecting to WorkSpaces.

To resolve this problem, do one of the following: 
+ If this problem occurred because the user was deleted and recreated in Active Directory, you might be able to restore the original deleted user object if you have enabled the [ Recycle Bin feature in Active Directory](https://docs.microsoft.com/windows-server/identity/ad-ds/get-started/adac/introduction-to-active-directory-administrative-center-enhancements--level-100-). If you're able to restore the original user object, make sure the user can connect to their original WorkSpace. If they can, you can [delete the new WorkSpace](delete-workspaces.md) after manually backing up and transferring any user data from the new WorkSpace to the original WorkSpace (if needed).
+ If you can't restore the original user object, [ delete the user's original WorkSpace](delete-workspaces.md). The user should be able to connect to and use their new WorkSpace instead. Be sure to manually back up and transfer any user data from the original WorkSpace to the new WorkSpace. 
**Warning**  
Deleting a WorkSpace is a permanent action and cannot be undone. The WorkSpace user's data does not persist and is destroyed. For help with backing up user data, contact AWS Support.

### I'm having trouble using Docker with Amazon WorkSpaces
<a name="docker_support"></a>

**Windows WorkSpaces**  
Nested virtualization (including the use of Docker) is not supported on Windows WorkSpaces. For more information, see the [ Docker documentation](https://docs.docker.com/docker-for-windows/troubleshoot/#running-docker-desktop-in-nested-virtualization-scenarios).

**Linux WorkSpaces**  
To use Docker on Linux WorkSpaces, make sure that the CIDR blocks used by Docker don't overlap with the CIDR blocks used in the two elastic network interfaces (ENIs) associated with the WorkSpace. If you encounter problems with using Docker on Linux WorkSpaces, contact Docker for assistance.

### I receive ThrottlingException errors to some of my API calls
<a name="throttled-api-calls"></a>

The default allowed rate for WorkSpaces API calls is a constant rate of two API calls per second, with a maximum allowed "burst" rate of five API calls per second. The following table shows how the burst rate limit works for API requests.


| Second | Number of requests sent | Net requests allowed | Details | 
| --- | --- | --- | --- | 
|  1  |  0  |  5  |  During the first second (second 1), five requests are allowed, up to the burst rate maximum of five calls per second.  | 
|  2  |  2  |  5  |  Because two or fewer calls were issued in second 1, the full burst capacity of five calls is still available.  | 
|  3  |  5  |  5  |  Because only two calls were issued in second 2, the full burst capacity of five calls is still available.  | 
|  4  |  2  |  2  |  Because the full burst capacity was used in second 3, only the constant rate of two calls per second is available.  | 
|  5  |  3  |  2  |  Because there is no remaining burst capacity, only two calls are allowed at this time. This means that one of the three API calls is throttled. The one throttled call will respond after a short delay.  | 
|  6  |  0  |  1  |  Because one of the calls from second 5 is being retried in second 6, there is capacity for only one additional call in second 6 because of the constant rate limit of two calls per second.  | 
|  7  |  0  |  3  |  Now that there are no longer any throttled API calls in the queue, the rate limit continues to increase, up to the burst rate limit of five calls.  | 
|  8  |  0  |  5  |  Because no calls were issued in second 7, the maximum number of requests is allowed.  | 
|  9  |  0  |  5  |  Even though no calls were issued in second 8, the rate limit does not increase above five.  | 

### My WorkSpace keeps disconnecting when I let it run in the background
<a name="workspaces-disconnecting"></a>

For Mac users, check to see if the Power Nap feature is on. If it is on, turn it off. To turn Power Nap off, open your terminal and run the following command:

```
defaults write com.amazon.workspaces NSAppSleepDisabled -bool YES
```

### SAML 2.0 federation isn't working. My users are not authorized to stream their WorkSpaces desktop.
<a name="saml-federation-not-working"></a>

This might happen because the inline policy that is embedded for the SAML 2.0 federation IAM role does not include permissions to stream from the directory Amazon Resource Name (ARN). The IAM role is assumed by the federated user who is accessing a WorkSpaces directory. Edit the role permissions to include the directory ARN and ensure that the user has a WorkSpace in the directory. For more information, see [SAML 2.0 Authentication](https://docs.aws.amazon.com/workspaces/latest/adminguide/amazon-workspaces-saml.html) and [Troubleshooting SAML 2.0 Federation with AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_saml.html).

### My users are getting disconnected from their WorkSpaces session every 60 minutes.
<a name="disconnected-workspace"></a>

If you have configured SAML 2.0 authentication to WorkSpaces, depending on your identity provider (IdP), you might need to configure the information that the IdP passes as SAML attributes to AWS as part of the authentication response. This includes configuring the **Attribute** element with the `SessionDuration` attribute set to `https://aws.amazon.com/SAML/Attributes/SessionDuration`.

`SessionDuration` specifies the maximum amount of time that a federated streaming session can remain active for a user before reauthentication is required. Although `SessionDuration` is an optional attribute, we recommend that you include it in the SAML authentication response. If you don't specify this attribute, the session duration defaults to 60 minutes.

To resolve this issue, configure your IdP to include the `SessionDuration` value in the SAML authentication response and set the value as required. For more information, see [ Step 5: Create assertions for the SAML authentication response](https://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml.html#create-assertions-saml-auth).

### My users get a redirect URI error when they federate using the SAML 2.0 identity provider (IdP)-initiated flow, or an additional instance of the WorkSpaces client application starts every time my users attempt to sign in from the client after federating to the IdP.
<a name="invalid-redirect-uri"></a>

This error occurs due to a relay state URL that's not valid. Make sure that the relay state in your IdP federation setup is correct, and that the user access URL and relay state parameter name are configured correctly for your IdP federation in the WorkSpaces directory properties. If they are valid and the problem still persists, contact AWS Support. For more information, see [Setting Up SAML](https://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml).

### My users receive the message, "Something went wrong: An error occurred while launching your WorkSpace" when they attempt to sign in to the WorkSpaces client application after federating to the IdP.
<a name="federating-error-message"></a>

Review the SAML 2.0 assertions for your federation. The **SAML Subject NameID** value must match the WorkSpaces user name, and is typically the same as the **sAMAccountName** attribute for the Active Directory user. In addition, the **Attribute** element that has the `PrincipalTag:Email` attribute set to `https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email` must match the WorkSpaces user's email address as defined in the WorkSpaces directory. For more information, see [Setting Up SAML](https://docs.aws.amazon.com/workspaces/latest/adminguide/setting-up-saml).

### My users receive the message, "Unable to validate tags” when they attempt to sign in to the WorkSpaces client application after federating to the IdP.
<a name="unable-to-validate-tags"></a>

Review the `PrincipalTag` attribute values in the SAML 2.0 assertions for your federation, such as `https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email`. Tag values may include combinations of the characters `_ . : / = + - @`, letters, numbers, and spaces.. For more information, see [Rules for tagging in IAM and AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html#id_tags_rules).

### My users receive the message, "The client and the server cannot communicate, because they do not possess a common algorithm".
<a name="no-common-algorithm"></a>

This problem can occur if you do not enable TLS 1.2.

### My microphone or web cam is not working on Windows WorkSpaces.
<a name="microphone-not-working"></a>

Check your privacy setting by opening the Start menu
+ **Start** > **Settings** > **Privacy** > **Camera**
+ **Start** > **Settings** > **Privacy** > **Microphone**

If they are turned off turn them on.

Alternatively, WorkSpaces administrators can create a Group Policy Object (GPO) to enable microphone and or webcam as needed.

### My users cannot log in using certificate-based authentication and are prompted for the password either at the WorkSpaces client or the Windows sign-on screen when they connect to their desktop session.
<a name="cert-based-auth-troubleshooting"></a>

Certificate-based authentication was unsuccessful for the session. If the problem continues, certificate-based authentication failure can be the result of one of the following issues:
+ The WorkSpaces or the client is not supported. Certificate-based authentication is supported with Windows WorkSpaces on DCV bundles using the latest WorkSpaces Windows client application.
+ The WorkSpaces needs to be rebooted after enabling certificate-based authentication on the WorkSpaces Directory.
+ WorkSpaces could not communicate with AWS Private CA, or AWS Private CA did not issue the certificate. Check [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/) to determine if a certificate was issued. For more information, see [Manage certificate-based authentication](certificate-based-authentication.md#manage-cert-based-auth).
+ The domain controller has no domain controller certificate for smart card logon, or it is expired. For more information, see step 7, “*Configure domain controllers with a domain controller certificate to authenticate smart card users*” in [Prerequisites](certificate-based-authentication.md#cert-based-auth-prerequesites).
+ The certificate is not trusted. For more information, see step 7, “*Publish the CA to Active Directory*” in [Prerequisites](certificate-based-authentication.md#cert-based-auth-prerequesites). Run `certutil –viewstore –enterprise NTAuth` on domain controllers to confirm that the CA is published. 
+ There is a certificate in cache, but attributes have changed for the user that have invalidated the certificate. Contact Support to clear the cache before certificate expiry (24 hours). For more information, see [Support Center](https://console.aws.amazon.com/support/home#/).
+ The userPrincipalName format for the `UserPrincipalName` SAML attribute is not formatted properly or does not resolve to the actual domain for the user. For more information, see step 1 in [Prerequisites](certificate-based-authentication.md#cert-based-auth-prerequesites).
+ The (optional) `ObjectSid` attribute in your SAML assertion does not match the Active Directory security identifier (SID) for user specified in the SAML\$1Subject `NameID`. Confirm that attribute mapping is correct in your SAML federation and that your SAML identity provider is synchronizing the SID attribute for the Active Directory user.
+ There are Group Policy settings that are modifying the default Active Directory settings for smart card logon or taking action if a smart card is removed from a smart card reader. These settings may cause additional unexpected behavior than the errors listed above. Certificate-based authentication presents a virtual smart card to the instance operating system and removes it after logon is complete. Check the [Primary Group Policy settings for smart cards](https://learn.microsoft.com/en-us/windows/security/identity-protection/smart-cards/smart-card-group-policy-and-registry-settings#primary-group-policy-settings-for-smart-cards) and the [Additional smart card Group Policy settings and registry keys](https://learn.microsoft.com/en-us/windows/security/identity-protection/smart-cards/smart-card-group-policy-and-registry-settings#additional-smart-card-group-policy-settings-and-registry-keys), including Smart card removal behavior.
+ The CRL distribution point for the private CA is not online nor accessible from either the WorkSpaces or the domain controller. For more information, see step 5 in [Prerequisites](certificate-based-authentication.md#cert-based-auth-prerequesites).
+ To check if there are any stale CAs in the domain or forest, run `PKIVIEW.msc` on the CA to verify. If there are stale CAs, use the `PKIVIEW.msc` mmc to manually delete them.
+ To check if Active Directory replication is working and that there are no stale domain controllers in the domain, run `repadmin /replsum`.

Additional troubleshooting steps involve reviewing the WorkSpaces instance Windows event logs. A common event to review for logon failure is [Event 4625: An account failed to logon](https://learn.microsoft.com/en-us/windows/security/threat-protection/auditing/event-4625) in the Windows Security log.

If the problem persists, contact Support. For more information, see [Support Center](https://console.aws.amazon.com/support/home#/).

### I am trying to do something that requires Windows installation media but WorkSpaces does not provide it.
<a name="install-media-troubleshooting"></a>

 If you are using an AWS-provided public bundle, you can use the Windows Server OS installation media EBS snapshots provided by Amazon EC2 when needed. 

 Create an EBS volume from these snapshots, attach it to Amazon EC2, and transfer the files to the WorkSpace where the files as needed. If you are using Windows 10 on BYOL on WorkSpaces and need an installation media, you will need to prepare your own installation media. For more information, see [ Add Windows components using installation media](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/windows-optional-components.html#adding-windows-components-console). Since you can't directly attach an EBS volume to a WorkSpace, you'll need to attach it to an Amazon EC2 instance and copy the files. 

### I want to launch WorkSpaces with an existing AWS Managed Directory created in an unsupported WorkSpaces Region.
<a name="unsupported-regions-troubleshooting"></a>

To launch Amazon WorkSpaces using a directory in a Region that is not currently supported by WorkSpaces, follow the steps below.

**Note**  
If you receive errors when running AWS Command Line Interface commands, ensure you’re using the most recent AWS CLI version. For more information, see [Confirm that you're running a recent version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-troubleshooting.html#general-latest).

#### Step 1: Create virtual private cloud (VPC) peering with another VPC in your account
<a name="w2aac11c39b9c93b7"></a>

1. Create the VPC peering connection with a VPC in a different Region. For more information, see [ Create with VPCs in the same account and different Regions](https://docs.aws.amazon.com/vpc/latest/peering/create-vpc-peering-connection.html#same-account-different-region).

1. Accept the VPC peering connection. For more information, see [Accept a VPC peering connection](https://docs.aws.amazon.com/vpc/latest/peering/accept-vpc-peering-connection.html). 

1. After you activate the VPC peering connection, you can view your VPC peering connections using the Amazon VPC console, the AWS CLI, or an API. 

#### Step 2: Update route tables for VPC peering in both Regions
<a name="w2aac11c39b9c93b9"></a>

 Update your route tables to turn on communication with the peer VPC over IPv4 or IPv6. For more information, see [Update your route tables for a VPC peering connection](https://docs.aws.amazon.com/vpc/latest/peering/vpc-peering-routing.html). 

#### Step 3: Create an AD Connector and register Amazon WorkSpaces
<a name="w2aac11c39b9c93c11"></a>

1.  To review the AD Connector prerequisites, see [ AD Connector prerequisites](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/prereq_connector.html). 

1.  Connect your existing directory with AD Connector. For more information, see [Create an AD Connector](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/create_ad_connector.html).

1. When the AD Connector status changes to **Active**, open the [AWS Directory Service console](https://console.aws.amazon.com/directoryservice), then choose the hyperlink for your **Directory ID**.

1. For AWS apps and services, choose **Amazon WorkSpaces** to turn on access for WorkSpaces on this directory.

1. Register the directory with WorkSpaces. For more information, see [Register a directory with WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/register-deregister-directory.html).

### I want to update Firefox on Amazon Linux 2.
<a name="firefox_al2"></a>

#### Step 1: Verify auto-update is enabled
<a name="w2aac11c39b9c95b3"></a>

To verify that autoupdate is enabled, run the command `systemctl status *os-update-mgmt.timer | grep enabled` on your WorkSpace. In the output, there should be two lines with the word `enabled` on them.

#### Step 2: Initiate an update
<a name="w2aac11c39b9c95b5"></a>

Firefox usually updates automatically in Amazon Linux 2 WorkSpaces along with all other software packages in the system during the maintenance window. However, this depends on the type of WorkSpaces you are using.
+ For AlwaysOn WorkSpaces, the weekly maintenance window is on Sunday 00h00 to 04h00, in the time zone of the WorkSpace.
+ For AutoStop WorkSpaces. beginning on the third Monday of the month, and for up to two weeks, the maintenance window is open each day from about 00h00 to 05h00, in the time zone of the AWS Region for the WorkSpace. 

For more information about maintenance windows, see [ WorkSpace maintenance](https://docs.aws.amazon.com/workspaces/latest/adminguide/workspace-maintenance.html).

You can also initiate an immediate update cycle by rebooting your WorkSpace and reconnecting after 15 minutes. You can also initiate updates by entering `sudo yum update`. To initiate an update for Firefox only, enter `sudo yum install firefox`.

 If you are not able to configure access for Amazon Linux 2 repositories and prefer to install Firefox using binaries built by Mozilla, see [Install Firefox from Mozilla builds](https://support.mozilla.org/en-US/kb/install-firefox-linux#w_install-firefox-from-mozilla-builds) on Mozilla support. We recommend uninstalling the RPM-packaged version of Firefox altogether to make sure you don't run an outdated version by mistake. You can uninstall it by running command `sudo yum remove firefox`. 

You can also download the necessary RPM packages from Amazon Linux 2 repositories by running the command `yumdownloader firefox` on a different machine. Then, side-load the repositories onto WorkSpaces, where you can install them with a standard `YUM` command like `sudo yum install firefox-102.11.0-2.amzn2.0.1.x86_64.rpm`.

**Note**  
The exact file name will change based on the package version.

#### Step 3: Verify Firefox repository is used
<a name="w2aac11c39b9c95b7"></a>

Amazon Linux Extras automatically provides Firefox updates for Amazon Linux 2 WorkSpaces. Amazon Linux 2 WorkSpaces created after July 31, 2023 will already have the Firefox Extra repository activated. To verify that your WorkSpace is using the Firefox Extra repository, run the following command.

```
yum repolist | grep amzn2extra-firefox
```

The command output should look something like `amzn2extra-firefox/2/x86_64 Amazon Extras repo for firefox 10` if Firefox Extra repository is used. It will be empty if the Firefox Extra repository is not used. If Firefox Extra repository is not used, you can attempt to enable it manually with the following command:

```
sudo amazon-linux-extras install firefox
```

If the Firefox Extra repository activation still fails, check your internet access and ensure that your VPC endpoints are unconfigured. To continue receiving Firefox updates for Amazon Linux 2 WorkSpaces via YUM repositories, ensure that your WorkSpaces are able to reach Amazon Linux 2 repositories. For more information on accessing Amazon Linux 2 repositories without internet access, see [this knowledge center article](https://repost.aws/knowledge-center/ec2-al1-al2-update-yum-without-internet).

### My user is able to reset their password using the WorkSpaces client, ignoring the Fine Grained Password Policy (FFGP) setting that is configured on AWS Managed Microsoft AD.
<a name="password-setting-mad"></a>

If your user's WorkSpaces client is associated with AWS Managed Microsoft AD, they will have to reset their password using the default complexity setting. 

 The default complexity password is case-sensitive and must be between 8 and 64 characters in length, inclusive. It must contain at least one character from each of the following categories:
+ Lowercase characters (a-z)
+ Uppercase characters (A-Z)
+ Numbers (0-9)
+ Non-alphanumeric characters (\$1\$1@\$1\$1%^&\$1\$1-\$1=`\$1\$1()\$1\$1[]:;"'<>,.?/)

Make sure the password doesn't include non-printable unicode characters, such as white spaces, carriage reture tabs, line breaks, and null characters.

If your organization requires you to enforce FFGP for WorkSpaces, contact your Active Directory administrator to reset your user's password directly from the Active Directory instead of the WorkSpaces client.

### My users receive the error message "This OS/platform is not authorized to access your WorkSpace" when trying to access the Windows/Linux WorkSpace using Web Access
<a name="os-authorized-access"></a>

The operating system version your user is trying to use isn't compatible with WorkSpaces Web Access. Make sure you enable Web Access under the WorkSpace directory's **Other Platform** setting. For more information on enabling your WorkSpace's Web Access, see [Enable and configure WorkSpaces Web Access for WorkSpaces Personal](web-access.md).

### My user's WorkSpace is showing as unhealthy after they connect to an AutoStop WorkSpace that is in the stopped state
<a name="autostop-unhealthy"></a>

Your user might be using software that is known to cause issues to the network interfaces when resuming from hibernation. For example, if the WorkSpace has the NPCAP 1.1 application installed, update to version 1.2 or above to resolve this issue.

### Gnome crashes on WorkSpaces Ubuntu bundles after login
<a name="gnome-crashes-ubuntu"></a>

If a WorkSpace is launched using the `ubuntu` username, there will be conflicts with the `ubuntu` user that exists by default. This will cause crashes in Gnome and potentially other degraded performance. To avoid this issue, don't specify the `ubuntu` username when provisioning Ubuntu WorkSpaces.

# DCV host agent versions in WorkSpaces Personal
<a name="workspaces-release-notes"></a>

DCV host agent is a host agent that runs inside your WorkSpace. It streams the pixels of your WorkSpace to a client application and includes in-session features, such as two-way audio and video, and printing. For more information about DCV, see [Protocols for Amazon WorkSpaces](https://docs.aws.amazon.com/workspaces/latest/adminguide/amazon-workspaces-protocols.html).

We recommend keeping your host agent software updated with the latest version. You can manually reboot your WorkSpaces to update the DCV host agent. The DCV host agent is also updated automatically during the regular WorkSpaces default maintenance window. For more information about maintenance windows, see [WorkSpace maintenance](https://docs.aws.amazon.com/workspaces/latest/adminguide/workspace-maintenance.html). Some of these features require the latest WorkSpaces client version. For more information about the latest client versions, see [WorkSpaces Clients](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-clients.html). 



The following table describes the changes in each version of the DCV host agent for WorkSpaces Personal.


| Release | Date | Changes | 
| --- | --- | --- | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | January 26, 2026 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | October 1, 2025 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | August 30, 2025 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | July 7, 2025 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | May 1, 2025 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | April 10, 2025 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | March 19, 2025 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | November 19, 2024 | Bug fixes and performance improvements.  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | October 31, 2024 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | August 19, 2024 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | July 29, 2024 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | May 15, 2024 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | February 29, 2024 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | February 22, 2024 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | January 11, 2024 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | November 16, 2023 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | October 13, 2023 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | August 18, 2023 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | June 30, 2023 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | June 8, 2023 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | May 16, 2023 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | May 8, 2023 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/workspaces-release-notes.html)  | 



**Note**  
For information about how to check your host agent version, see [What client and host operating systems are supported by the latest version of DCV?](https://aws.amazon.com/workspaces/faqs/#:~:text=Q%3A%20What%20client%20and%20host%20operating%20systems%20are%20supported%20by%20the%20latest%20version%20of%20WSP%3F). 
For information about how to update your host agent version, see [ If I already have a DCV WorkSpace, how do I update it?](https://aws.amazon.com/workspaces/faqs/#:~:text=Q%3A%20If%20I%20already%20have%20a%20WSP%20WorkSpace%2C%20how%20do%20I%20update%20it%3F). 
For DCV macOS client version release notes, see [Release notes](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-osx-client.html#osx-release-notes) in the WorkSpaces macOS client application section of the WorkSpaces User Guide. 
For DCV Windows client version release notes, see [Release notes](https://docs.aws.amazon.com/workspaces/latest/userguide/amazon-workspaces-windows-client.html#windows-release-notes) in the WorkSpaces Windows client application section of the WorkSpaces User Guide.