# Use and manage WorkSpaces Pools WorkSpaces Pools offers non-persistent virtual desktops, tailored for users who need access to highly-curated desktop environments hosted on ephemeral infrastructure. **Topics** + [AWS Regions and Availability Zones for WorkSpaces Pools](wsp-pools-regions.md) + [Manage directories for WorkSpaces Pools](manage-workspaces-pools-directory.md) + [Networking and Access for WorkSpaces Pools](managing-network.md) + [Create a WorkSpaces Pool](set-up-pools-create.md) + [Administer WorkSpaces Pools](managing-stacks-fleets.md) + [Using Active Directory with WorkSpaces Pools](active-directory.md) + [Bundles and images for WorkSpaces Pools](pools-images.md) + [Monitoring WorkSpaces Pools](configure-monitoring-reporting.md) + [Enable and Administer Persistent Storage for WorkSpaces Pools](persistent-storage.md) + [Enable application settings persistence for your WorkSpaces Pools users](app-settings-persistence.md) + [WorkSpaces Pools troubleshooting notification codes](wsp-pools-troubleshooting.md) # AWS Regions and Availability Zones for WorkSpaces Pools WorkSpaces Pools is available in the following AWS Regions. **Note** For the AWS Regions that apply to WorkSpaces Personal, see [Amazon WorkSpaces endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/wsp.html) in the *AWS General Reference Reference guide*. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/wsp-pools-regions.html) # Manage directories for WorkSpaces Pools WorkSpaces Pools uses a directory to store and manage information for your WorkSpaces and users. In this section, we show you how to create and manage directories for WorkSpaces Pools. **Topics** + [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md) + [Update directory details for your WorkSpaces Pools](update-directory-pools-details.md) + [Delete a WorkSpaces Pools directory](delete-directory-pools.md) # Configure SAML 2.0 and create a WorkSpaces Pools directory You can enable WorkSpaces client application registration and signing in to WorkSpaces in a WorkSpaces Pool by setting up identity federation using SAML 2.0. To do this, you use an AWS Identity and Access Management (IAM) role and a relay state URL to configure your SAML 2.0 identity provider (IdP) and enable it for AWS. This grants your federated users access to a WorkSpace Pool directory. The relay state is the WorkSpaces directory endpoint to which users are forwarded after successfully signing in to AWS. **Important** WorkSpaces Pools doesn't support IP-based SAML 2.0 configurations. **Topics** + [Step 1: Consider the requirements](#saml-directory-consider-the-requirements) + [Step 2: Complete the prerequisites](#saml-directory-complete-the-prereqs) + [Step 3: Create a SAML identity provider in IAM](#saml-directory-create-saml-idp) + [Step 4: Create WorkSpace Pool directory](#saml-directory-create-wsp-pools-directory) + [Step 5: Create a SAML 2.0 federation IAM role](#saml-directory-saml-federation-role-in-iam) + [Step 6: Configure your SAML 2.0 identity provider](#saml-directory-configure-saml-idp) + [Step 7: Create assertions for the SAML authentication response](#saml-directory-create-assertions) + [Step 8: Configure the relay state of your federation](#saml-directory-configure-relay-state) + [Step 9: Enable integration with SAML 2.0 on your WorkSpace Pool directory](#saml-directory-enable-saml-integration) + [Troubleshooting](#saml-pools-troubleshooting) + [Specify Active Directory details for your WorkSpaces Pools directory](pools-service-account-details.md) ## Step 1: Consider the requirements The following requirements apply when setting up SAML for a WorkSpaces Pools directory. + The workspaces\$1DefaultRole IAM role must exist in your AWS account. This role is automatically created when you use the WorkSpaces Quick Setup or if you previously launched a WorkSpace using the AWS Management Console. It grants Amazon WorkSpaces permission to access specific AWS resources on your behalf. If the role already exists, you might need to attach the AmazonWorkSpacesPoolServiceAccess managed policy to it, which Amazon WorkSpaces uses to access required resources in the AWS account for WorkSpaces Pools. For more information, see [Create the workspaces\$1DefaultRole Role](workspaces-access-control.md#create-default-role) and [AWS managed policy: AmazonWorkSpacesPoolServiceAccess](managed-policies.md#workspaces-pools-service-access). + You can configure SAML 2.0 authentication for WorkSpaces Pools in the AWS Regions that support the feature. For more information, see [AWS Regions and Availability Zones for WorkSpaces Pools](wsp-pools-regions.md). + 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 that support this include ADFS, Azure AD, Duo Single Sign-On, Okta, PingFederate, and PingOne. Consult your IdP documentation for more information. + SAML 2.0 authentication is supported only on the following WorkSpaces clients. For the latest WorkSpaces clients, see the [Amazon WorkSpaces Client Download page](https://clients.amazonworkspaces.com/). + Windows client application version 5.20.0 or later + macOS client version 5.20.0 or later + Web Access ## Step 2: Complete the prerequisites Complete the following prerequisites before configuring your SAML 2.0 IdP connection to a WorkSpaces Pool directory. + 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 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. + Create a WorkSpaces Pool directory by using the WorkSpaces console. For more information, see [Using Active Directory with WorkSpaces Pools](active-directory.md). + Create a WorkSpaces Pool for users who can sign in to the IdP using a supported directory type. For more information, see [Create a WorkSpaces Pool](set-up-pools-create.md). ## Step 3: Create a SAML identity provider in IAM To get started, you must create a SAML IdP in 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html#idp-manage-identityprovider-console) in the *AWS Identity and Access Management User Guide*. For information about working with SAML IdPs in AWS GovCloud (US) Regions, see [AWS Identity and Access Management](https://docs.aws.amazon.com//govcloud-us/latest/UserGuide/govcloud-iam.html) in the *AWS GovCloud (US) User Guide*. ## Step 4: Create WorkSpace Pool directory Complete the following procedure to create a WorkSpaces Pool directory. 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose **Create directory**. 1. For **WorkSpace type**, choose **Pool**. 1. In the **User identity source** section of the page: 1. Enter a placeholder value into the **User access URL** text box. For example, enter `placeholder` into the text box. You will edit this later after setting up the application entitlement in your IdP. 1. Leave the **Relay state parameter name** text box blank. You will edit this later after setting up the application entitlement in your IdP. 1. In the **Directory information** section of the page, enter a name and a description for the directory. The directory name and description must be less than 128 characters, can contain alphanumeric characters and the following special characters: `_ @ # % * + = : ? . / ! \ -`. The directory name and description cannot start with a special character. 1. In the **Networking and security** section of the page: 1. Choose a VPC and 2 subnets that have access to the network resources that your application needs. For increased fault tolerance, you should choose two subnets in different Availability Zones. 1. Choose a security group that allows WorkSpaces to create network links in your VPC. Security groups control what network traffic is allowed to flow from WorkSpaces to your VPC. For example, if your security group restricts all inbound HTTPS connections, users accessing your web portal won't be able to load HTTPS websites from the WorkSpaces. 1. The **Active Directory Config** section is optional. However, you should specify your Active Directory (AD) details during the creation of your WorkSpaces Pools directory if you plan to use an AD with your WorkSpaces Pools. You can't edit the **Active Directory Config** for your WorkSpaces Pools directory after you create it. For more information about specifying your AD details for your WorkSpaces Pool directory, see [Specify Active Directory details for your WorkSpaces Pools directory](pools-service-account-details.md). After you complete the process outlined in that topic, you should return to this topic to finish creating your WorkSpaces Pools directory. You can skip the **Active Directory Config** section if you don't plan on using an AD with your WorkSpaces Pools. 1. In the **Streaming properties** section of the page: + Choose the clipboard permissions behavior, and enter a copy to local character limit (optional), and paste to remote session character limit (optional). + Choose to allow or not allow print to local device. + Choose to allow or not allow diagnostic logging. + Choose to allow or not allow smart card sign in. This feature applies only if you enabled AD configuration earlier in this procedure. 1. In the **Storage** section of the page, you can choose to enable home folders. 1. In the **IAM role section** of the page, choose an IAM role to be available to all desktop streaming instances. To create a new one, choose **Create new IAM role**. When you apply an IAM role from your account to a WorkSpace Pool directory, you can make AWS API requests from a WorkSpace in the WorkSpace Pool without manually managing AWS credentials. For more information, see [Creating a role to delegate permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) in *AWS Identity and Access Management User Guide*. 1. Choose **Create directory**. ## Step 5: Create a SAML 2.0 federation IAM role Complete the following procedure to create a SAML 2.0 federation IAM role in the IAM console. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/secretsmanager/). 1. Choose **Roles** in the navigation pane. 1. Choose Create role. 1. Choose **SAML 2.0 federation** for the trusted entity type. 1. For SAML 2.0-based provider, choose the identity provider you created in IAM. For more information, see [Create a SAML identity provider in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html?). 1. Choose **Allow programmatic access only** for the access to be allowed. 1. Choose ** SAML:sub\$1type** for the attribute. 1. For **Value**, enter `https://signin.aws.amazon.com/saml`. 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, see [Uniquely identifying users in SAML-based federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html#CreatingSAML-userid) in *AWS Identity and Access Management User Guide*. 1. Choose **Next** to continue. 1. Don't make changes or selections in the **Add permissions** page. Choose **Next** to continue. 1. Enter a name and a description for the role. 1. Choose **Create role**. 1. In the **Roles** page, choose the role you must created. 1. Choose the **Trust relationships** tab. 1. Choose **Edit trust policy**. 1. In the **Edit trust policy** JSON text box, add the **sts:TagSession** action to the 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 *AWS Identity and Access Management User Guide*. The result should look like the following example. ![\[An example of a trust policy.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/iam-saml-federation-policy-sts-tagsession.png) 1. Choose **Update policy**. 1. Choose the **Permissions** tab. 1. In the **Permissions policies** section of the page choose **Add permissions** and then choose **Create inline policy**. 1. In the **Policy editor** section of the page, choose **JSON**. 1. In the **Policy editor** JSON text box, enter the following policy. Be sure to replace: + ** with the code of the AWS Region in which you created your WorkSpace Pool directory. + ** with the AWS account ID. + ** with the ID of the directory you created earlier. You can get this in the WorkSpaces console. For resources in AWS GovCloud (US) Regions, use the following format for the ARN: `arn:aws-us-gov:workspaces:::directory/`. 1. Choose Next. 1. Enter a name for the policy, and then choose **Create policy**. ## Step 6: Configure your SAML 2.0 identity provider Depending on your SAML 2.0 IdP, you might need to manually update your IdP to trust AWS as a service provider. You do this by downloading the `saml-metadata.xml` file found at [https://signin.aws.amazon.com/static/saml-metadata.xml](https://signin.aws.amazon.com/static/saml-metadata.xml), and then uploading it to your IdP. This updates your IdP’s metadata. For some IdPs, the update might already be configured. You can skip this step if it's already configured. If the 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 of the XML file into their dashboard, and the IdP obtains and installs the file for you. Others require you to download the file from the URL and then upload it to their dashboard. **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. ## Step 7: Create assertions for the SAML authentication response Configure the information that your IdP sends to AWS as SAML attributes in its authentication response. Depending on your IdP, this is might already be configured. You can skip this step if it's already configured. If it's not already configured, provide the following: + **SAML Subject NameID** — The unique identifier for the user who is signing in. Don't change the format/value of this field. Otherwise, the home folder feature will not work as expected because the user will be treated as different user. **Note** For domain-joined WorkSpaces Pools, the `NameID` value for the user must be provided in the `domain\username` format using the `sAMAccountName`, or in the `username@domain.com` format using `userPrincipalName`, or just `userName`. If you are using the `sAMAccountName` format, you can specify the domain by using either the NetBIOS name or the fully qualified domain name (FQDN). The `sAMAccountName` format is required for Active Directory one-way trust scenarios. For more information, see [Using Active Directory with WorkSpaces Pools](active-directory.md). if just `userName` is provided, the user will be logged in to the primary-domain + **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_type` set to `persistent`, as described in the [Step 5: Create a SAML 2.0 federation IAM role](#saml-directory-saml-federation-role-in-iam) section. + **`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:::role/,arn:aws:iam:::saml-provider/`. + **`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 alphanumeric characters and the following special characters: `_ . : / = + - @`. 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 `_ . : / = + - @` 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 *AWS Identity and Access Management User Guide*. + (Optional) **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:UserPrincipalName** — 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 `username@domain.com` format. 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 and WorkSpaces Personal](certificate-based-authentication.md). + (Optional) **`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 and WorkSpaces Personal](certificate-based-authentication.md). + (Optional) **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:Domain** — 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` format, and must include any subdomains. + (Optional) **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/SessionDuration** — 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 re-authentication 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) in the *AWS Identity and Access Management User Guide*. **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 *AWS Identity and Access Management User Guide*. For information about specific configuration requirements for your IdP, see your IdP's documentation. ## Step 8: Configure the relay state of your federation Use your IdP to configure the relay state of your federation to point to the WorkSpaces Pool directory relay state URL. After successful authentication by AWS, the user is directed to the WorkSpaces Pool 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 ``` The following table lists the relay state endpoints for the AWS Regions where WorkSpaces SAML 2.0 authentication is available. AWS Regions in which the WorkSpaces Pools feature is not available have been removed. | 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/create-directory-pools.html) | | US West (Oregon) Region | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html) | | 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 | | AWS GovCloud (US-West) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html) For information about working with SAML IdPs in AWS GovCloud (US) Regions, 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/create-directory-pools.html) For information about working with SAML IdPs in AWS GovCloud (US) Regions, see [ Amazon WorkSpaces](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-workspaces.html) in the *AWS GovCloud (US) User Guide*. | ## Step 9: Enable integration with SAML 2.0 on your WorkSpace Pool directory Complete the following procedure to enable SAML 2.0 authentication for the WorkSpaces Pool directory. 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose the **Pools directories** tab. 1. Choose the ID of the directory you want to edit. 1. Choose **Edit** in the **Authentication** section of the page. 1. Choose **Edit SAML 2.0 Identity Provider**. 1. For the **User Access URL**, which is sometimes know as the "SSO URL", replace the placeholder value with the SSO URL provided to you by your IdP. 1. For the **IdP deep link parameter name**, enter the parameter that is applicable to your IdP and the application you have configured. The default value is `RelayState` if you omit the parameter name. The following table lists the user access URLs and deep link parameter names that are unique to various identity providers for applications. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html) 1. Choose **Save**. **Important** Revoking SAML 2.0 from a user won't directly disconnect their session. They will be removed only after the timeout kicks in. They can also terminate it using the [ TerminateWorkspacesPoolSession](https://docs.aws.amazon.com//workspaces/latest/api/API_TerminateWorkspacesPoolSession.html) API. ## Troubleshooting The following information can help you troubleshoot specific issues with your WorkSpaces Pools. ### I am receiving an "Unable to login" message in the WorkSpaces Pools client after completing SAML authentication The `nameID` and `PrincipalTag:Email` in the SAML claims need to match the username and email configured in Active Directory. Some IdP's may require an update, refresh, or redeploy after adjusting certain attributes. If you make an adjustment and it is not reflected in your SAML capture, refer to your IdP's documentation or support program regarding the specific steps required to make the change take effect. # Specify Active Directory details for your WorkSpaces Pools directory In this topic, we show you how to specify your Active Directory (AD) details within the **Create WorkSpaces Pool directory** page of the WorkSpaces console. As you create your WorkSpaces Pool directory, you should specify your AD details if you plan to use an AD with your WorkSpaces Pools. You cannot edit the **Active Directory Config** for your WorkSpaces Pools directory after you create it. Following is an example of the **Active Directory Config** section of the **Create WorkSpaces Pool directory** page. ![\[The Active Directory Config section of the Create WorkSpaces Pool directory page\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/pools-wsp-active-directory-config.png) **Note** The full process for creating a WorkSpaces Pool directory is outlined in the [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md) topic. The procedures outlined on this page represent only a subset of steps of the full process to create a WorkSpaces Pool directory. **Topics** + [Specify the organization unit and directory domain name for your AD](#pools-specify-ou-and-directory-domain) + [Specify the service account for your AD](#pools-specify-access-account) ## Specify the organization unit and directory domain name for your AD Complete the following procedure to specify an organizational unit (OU) and a directory domain name for your AD in the **Create a WorkSpaces Pool directory** page. 1. For **Organization Unit**, enter the OU that the pool belongs to. WorkSpace machine accounts are placed in the organizational unit (OU) that you specify for the WorkSpaces Pool directory. **Note** The OU name can't contain spaces. If you specify an OU name that contains spaces, when it attempts to rejoin the Active Directory domain, WorkSpaces cannot cycle the computer objects correctly and the domain rejoin doesn't work. 1. For **Directory domain name**, enter the fully qualified domain name (FQDN) of the Active Directory domain (for example, `corp.example.com`). Each AWS Region can have only one directory config value with a specific directory name. + You can join your WorkSpaces Pool directories to domains in Microsoft Active Directory. You can also use your existing Active Directory domains, either cloud-based or on-premises, to launch domain-joined WorkSpaces. + You can also use AWS Directory Service for Microsoft Active Directory, also known as AWS Managed Microsoft AD, to create an Active Directory domain. Then, you can use that domain to support your WorkSpaces resources. + By joining WorkSpaces to your Active Directory domain, you can: + Allow your users and applications to access Active Directory resources, such as printers and file shares from streaming sessions. + Use Group Policy settings that are available in the Group Policy Management Console (GPMC) to define the end user experience. + Stream applications that require users to be authenticated using their Active Directory login credentials. + Apply your enterprise compliance and security policies to your WorkSpaces streaming instances. 1. For **Service account**, continue to the [Specify the service account for your AD](#pools-specify-access-account) next section of this page. ## Specify the service account for your AD When you configure Active Directory (AD) for your WorkSpaces Pools as part of the directory creation process, you must specify the AD service account to be used for managing the AD. This requires that you provide the service account credentials, which must be stored in AWS Secrets Manager and encrypted using a AWS Key Management Service (AWS KMS) customer managed key. In this section, we show you how to create the AWS KMS customer managed key and the Secrets Manager secret to store your AD service account credentials. ### Step 1: Create an AWS KMS customer managed key Complete the following procedure to create an AWS KMS customer managed 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 a key**, and then choose **Next**. 1. Choose **Symetric** for the key type, and **Encrypt and decrypt** for the key usage, and then choose **Next**. 1. Enter an alias for the key, such as `WorkSpacesPoolDomainSecretKey`, and then choose **Next**. 1. Don't choose a key administrator. Choose **Next** to continue. 1. Don't define key usage permissions. Choose **Next** to continue. 1. In the Key policy section of the page, add the following: ``` { "Sid": "Allow access for Workspaces SP", "Effect": "Allow", "Principal": { "Service": "workspaces.amazonaws.com" }, "Action": "kms:Decrypt", "Resource": "*" } ``` The result should appear like the following example. ![\[An example of a AWS KMS key policy.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/kms-key-policy-for-wsp-pools-service-account.png) 1. Choose **Finish**. Your AWS KMS customer managed key is now ready to be used with Secrets Manager. Continue to the [Step 2: Create Secrets Manager secret to store your AD service account credentials](#pools-create-asm-secret) section of this page. ### Step 2: Create Secrets Manager secret to store your AD service account credentials Complete the following procedure to create a Secrets Manager secret to store your AD service account credentials. 1. Open the AWS Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/). 1. Choose **Create a new secret**. 1. Choose **Other type of secret**. 1. For the first key/value pair, enter `Service Account Name` for the key, and the name of the service account for the value, such as `domain\username`. 1. For the second key/value pair, enter a `Service Account Password` for the key, and the password of the service account for the value. 1. For the encryption key, choose the AWS KMS customer managed key that you created earlier, and then choose **Next**. 1. Enter a name for the secret, such as `WorkSpacesPoolDomainSecretAD`. 1. Choose **Edit permissions** in the **Resource permissions** section of the page. 1. Enter the following permission policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "workspaces.amazonaws.com" ] }, "Action": "secretsmanager:GetSecretValue", "Resource": "*" } ] } ``` ------ 1. Choose **Save** to save the permission policy. 1. Choose **Next** to continue. 1. Don't configure automatic rotation. Choose **Next** to continue. 1. Choose **Store** to finish storing your secret. Your AD service account credentials are now stored in Secrets Manager. Continue to the [Step 3: Select the Secrets Manager secret that contains your AD service account credentails](#continue-creating-pools-directory) section of this page. ### Step 3: Select the Secrets Manager secret that contains your AD service account credentails Complete the following procedure to select the Secrets Manager secret you created in the Active Directory config for your WorkSpaces Pool directory. + For **Service account**, choose the AWS Secrets Manager secret that contains your service account credentials. Complete the following steps to create the secret if you haven't already done so. The secret must be encrypted using a AWS Key Management Service customer managed key. Now that you've completed all of the fields within the **Active Directory Config** section of the **Create WorkSpaces Pool directory** page, you can continue to finish creating your WorkSpaces Pool directory. Go to [Step 4: Create WorkSpace Pool directory](create-directory-pools.md#saml-directory-create-wsp-pools-directory) and start on step 9 of the procedure. # Update directory details for your WorkSpaces Pools You can complete the following directory management tasks using the WorkSpaces Pools console. ## Authentication You can configure additional authentication options for your WorkSpaces Pools. Pools requires SAML 2.0 authentication. **To enable and configure SAML 2.0 Identity Provider authentiation** 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose the directory you want to configure. 1. Go to authentication and choose **Edit**. 1. Choose **Edit SAML 2.0 Identity Provider**. 1. Check the **Enable SAML 2.0 authentication** checkbox. 1. Enter the **User Access URL** to direct the WorkSpaces Pools client during federated sign-in. 1. Enter the **IdP deep link parameter name** (optional). 1. Choose **Save**. **To enable and configure 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. Choose **Directories** in the navigation pane. 1. Choose the directory you want to configure. 1. Go to Authentication and choose **Edit**. 1. Choose **Edit Certificate-Based Authentication**. 1. Check the **Enable Certificate-Based Authentication** checkbox. 1. Choose from the dropdown the **AWS Certificate Manager (ACM) Private Certificate Authority (CA)**. 1. Choose **Save**. ## Security group Apply a security group to your WorkSpaces Pools in your directory. **To configure security group for your WorkSpaces Pools** 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose the directory you want to configure. 1. Go to Security group and choose **Edit**. 1. From the dropdown, choose a security group. ## Active Directory Config Configure your directory Active Directory Config with an Organization Unit (OU), directory domain name, and AWS Secrets Manager secret. **To configure your Active Directory** 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose the directory you want to configure. 1. Go to Active Directory Config and choose **Edit**. 1. To find an Organizational Unit (OU), you can start typing all or part of the OU name and choose the OU you want to use. **Note** (Optional) After choosing the OU, rebuild the existing WorkSpaces to update the OU. For more information, see [Rebuild a WorkSpace in WorkSpaces Personal](rebuild-workspace.md) 1. Choose **Save**. **Note** The directory domain name and AWS Secrets Manager secret can't be edited after you've created your pool. ## Streaming properties Configure how your users can transfer data between their pooled WorkSpace and their local device. **To configure streaming properties** 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose the directory you want to configure. 1. Go to Streaming properties and choose **Edit**. 1. Configure the following streaming properties: + Clipboard permissions + From the drop down list, choose one of the following: + **Allow copy and paste** - Allows copying to local device and pasting to remote session. + **Allow paste to remote session** - Allows pasting to remote session. + **Allow copy to local device** - Allows copying to a local device. + Disabled + Choose to allow or not allow print to local device. + Choose to allow or not allow diagnostic logging. + Choose to allow or not allow smart card sign in. + To enable Home Folders storage, choose **Enable Home Folders**. 1. Choose **Save**. ## IAM role Select an IAM role for you WorkSpaces Pools. **To select an IAM role** 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose the directory you want to configure. 1. Go to IAM role and choose **Edit**. 1. Choose an IAM role from the drop down. To create a new IAM role, choose **Create new IAM role**. 1. Choose **Save**. ## Tags Add new tags to your WorkSpaces Pools **To add a new tag** 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Choose the directory you want to configure. 1. Go to Tags and choose **Manage tags**. 1. Choose **Add new tags** and enter 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. Choose **Save changes**. # Delete a WorkSpaces Pools directory Complete the following procedures to delete a WorkSpaces Pools directory. 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. Choose **Directories** in the navigation pane. 1. Select the directory. 1. Choose **Actions**, **Delete**. 1. When prompted for confirmation, enter **delete** in the confirmation text and choose **Delete**. # Networking and Access for WorkSpaces Pools The following topics provide information about enabling users to connect to WorkSpaces Pools and enabling your WorkSpaces Pools to access network resources and the internet. **Topics** + [Internet Access for WorkSpaces Pools](internet-access.md) + [Configure a VPC for WorkSpaces Pools](appstream-vpc.md) + [Configure FedRAMP authorization or DoD SRG compliance for WorkSpaces Pools](fips-encryption-pools.md) + [Using Amazon S3 VPC Endpoints for WorkSpaces Pools Features](managing-network-vpce-iam-policy.md) + [Connections to Your VPC for WorkSpaces Pools](pools-port-requirements.md) + [User connections to WorkSpaces Pools](user-connections-to-appstream2.md) # Internet Access for WorkSpaces Pools If your WorkSpaces in WorkSpaces Pools require internet access, you can enable it in several ways. When you choose a method for enabling internet access, consider the number of users your deployment must support and your deployment goals. For example: + If your deployment must support more than 100 concurrent users, [configure a VPC with private subnets and a NAT gateway](managing-network-internet-NAT-gateway.md). + If your deployment supports fewer than 100 concurrent users, you can [configure a new or existing VPC with a public subnet](managing-network-default-internet-access.md). + If your deployment supports fewer than 100 concurrent users and you are new to WorkSpaces Pools and want to get started using the service, you can [use the default VPC, public subnet, and security group](managing-network-default-internet-access.md). The following sections provide more information about each of these deployment options. + [Configure a VPC with Private Subnets and a NAT Gateway](managing-network-internet-NAT-gateway.md) (recommended) — With this configuration, you launch your WorkSpaces Pools builders in a private subnet and configure a NAT gateway in a public subnet in your VPC. Your streaming instances are assigned a private IP address that is not directly accessible from the internet. In addition, unlike configurations that use the **Default Internet Access** option for enabling internet access, the NAT configuration is not limited to 100 WorkSpaces in WorkSpaces Pools. If your deployment must support more than 100 concurrent users, use this configuration. You can create and configure a new VPC to use with a NAT gateway, or add a NAT gateway to an existing VPC. + [Configure a New or Existing VPC with a Public Subnet](managing-network-default-internet-access.md) — With this configuration, you launch your WorkSpaces Pools in a public subnet. When you enable this option, WorkSpaces Pools uses the internet gateway in your Amazon VPC public subnet to provide the internet connection. Your streaming instances are assigned a public IP address that is directly accessible from the internet. You can create a new VPC or configure an existing one for this purpose. **Note** When you configure a new or existing VPC with a public subnet, a maximum of 100 WorkSpaces are supported in WorkSpaces Pools. If your deployment must support more than 100 concurrent users, use the [NAT gateway configuration](managing-network-internet-NAT-gateway.md) instead. + [Use the Default VPC, Public Subnet, and Security Group](default-vpc-with-public-subnet.md) — If you are new to WorkSpaces Pools and want to get started using the service, you can launch your WorkSpaces Pools in a default public subnet. When you enable this option, WorkSpaces Pools uses the internet gateway in your Amazon VPC public subnet to provide the internet connection. Your streaming instances are assigned a public IP address that is directly accessible from the internet. Default VPCs are available in Amazon Web Services accounts created after 2013-12-04. The default VPC includes a default public subnet in each Availability Zone and an internet gateway that is attached to your VPC. The VPC also includes a default security group. **Note** When you use the default VPC, public subnet, and security group, a maximum of 100 WorkSpaces are supported in WorkSpaces Pools. If your deployment must support more than 100 concurrent users, use the [NAT gateway configuration](managing-network-internet-NAT-gateway.md) instead. # Configure a VPC for WorkSpaces Pools When you set up WorkSpaces Pools, you must specify the virtual private cloud (VPC) and at least one subnet in which to launch your WorkSpaces. A VPC is a virtual network in your own logically isolated area within the Amazon Web Services Cloud. A subnet is a range of IP addresses in your VPC. When you configure your VPC for WorkSpaces Pools, you can specify either public or private subnets, or a mix of both types of subnets. A public subnet has direct access to the internet through an internet gateway. A private subnet, which doesn't have a route to an internet gateway, requires a Network Address Translation (NAT) gateway or NAT instance to provide access to the internet. **Topics** + [VPC Setup Recommendations for WorkSpaces Pools](vpc-setup-recommendations.md) + [Configure a VPC with Private Subnets and a NAT Gateway](managing-network-internet-NAT-gateway.md) + [Configure a New or Existing VPC with a Public Subnet](managing-network-default-internet-access.md) + [Use the Default VPC, Public Subnet, and Security Group](default-vpc-with-public-subnet.md) # VPC Setup Recommendations for WorkSpaces Pools When you create a WorkSpaces Pools, you specify the VPC and one or more subnets to use. You can provide additional access control to your VPC by specifying security groups. The following recommendations can help you configure your VPC more effectively and securely. In addition, they can help you configure an environment that supports effective WorkSpaces Pools scaling. With effective WorkSpaces Pools scaling, you can meet current and anticipated WorkSpaces user demand, while avoiding unnecessary resource usage and associated costs. **Overall VPC Configuration** + Make sure that your VPC configuration can support your WorkSpaces Pools scaling needs. As you develop your plan for WorkSpaces Pools scaling, keep in mind that one user requires one WorkSpaces. Therefore, the size of your WorkSpaces Pools determines the number of users who can stream concurrently. For this reason, for each [instance type](instance-types.md) that you plan to use, make sure that the number of WorkSpaces that your VPC can support is greater than the number of anticipated concurrent users for the same instance type. + Make sure that your WorkSpaces Pools account quotas (also referred to as limits) are sufficient to support your anticipated demand. To request a quota increase, you can use the Service Quotas console at [https://console.aws.amazon.com/servicequotas/](https://console.aws.amazon.com/servicequotas/). For information about default WorkSpaces Pools quotas, see [Amazon WorkSpaces quotas](workspaces-limits.md). + If you plan to provide your WorkSpaces in WorkSpaces Pools with access to the internet, we recommend that you configure a VPC with two private subnets for your streaming instances and a NAT gateway in a public subnet. The NAT gateway lets the WorkSpaces in your private subnets connect to the internet or other AWS services. However, it prevents the internet from initiating a connection with those WorkSpaces. In addition, unlike configurations that use the **Default Internet Access** option for enabling internet access, the NAT configuration supports more than 100 WorkSpaces. For more information, see [Configure a VPC with Private Subnets and a NAT Gateway](managing-network-internet-NAT-gateway.md). **Elastic Network Interfaces** + WorkSpaces Pools creates as many [elastic network interfaces](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_ElasticNetworkInterfaces.html) (network interfaces) as the maximum desired capacity of your WorkSpaces Pools. By default, the limit for network interfaces per Region is 5000. When planning capacity for very large deployments, for example, thousands of WorkSpaces, consider the number of Amazon EC2 instances that are also used in the same Region. **Subnets** + If you are configuring more than one private subnet for your VPC, configure each in a different Availability Zone. Doing so increases fault tolerance and can help prevent insufficient capacity errors. If you use two subnets in the same AZ, you might run out of IP addresses, because WorkSpaces Pools will not use the second subnet. + Make sure that the network resources required for your applications are accessible through both of your private subnets. + Configure each of your private subnets with a subnet mask that allows for enough client IP addresses to account for the maximum number of expected concurrent users. In addition, allow for additional IP addresses to account for anticipated growth. For more information, see [VPC and Subnet Sizing for IPv4](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#vpc-sizing-ipv4). + If you are using a VPC with NAT, configure at least one public subnet with a NAT Gateway for internet access, preferably two. Configure the public subnets in the same Availability Zones where your private subnets reside. To enhance fault tolerance and reduce the chance of insufficient capacity errors for large WorkSpaces Pools deployments, consider extending your VPC configuration into a third Availability Zone. Include a private subnet, public subnet, and NAT gateway in this additional Availability Zone. **Security Groups** + Use security groups to provide additional access control to your VPC. Security groups that belong to your VPC let you control the network traffic between WorkSpaces Pools streaming instances and network resources required by applications. These resources may include other AWS services such as Amazon RDS or Amazon FSx, license servers, database servers, file servers, and application servers. + Make sure that the security groups provide access to the network resources that your applications require. For general information about security groups, see [Control traffic to your AWS resources using security groups](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html) in the *Amazon VPC User Guide*. # Configure a VPC with Private Subnets and a NAT Gateway If you plan to provide your WorkSpaces in WorkSpaces Pools with access to the internet, we recommend that you configure a VPC with two private subnets for your WorkSpaces and a NAT gateway in a public subnet. You can create and configure a new VPC to use with a NAT gateway, or add a NAT gateway to an existing VPC. For additional VPC configuration recommendations, see [VPC Setup Recommendations for WorkSpaces Pools](vpc-setup-recommendations.md). The NAT gateway lets the WorkSpaces in your private subnets connect to the internet or other AWS services, but prevents the internet from initiating a connection with those WorkSpaces. In addition, unlike configurations that use the **Default Internet Access** option for enabling internet access for WorkSpaces, this configuration is not limited to 100 WorkSpaces. For information about using NAT Gateways and this configuration, see [NAT Gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) and [VPC with Public and Private Subnets (NAT)](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html) in the *Amazon VPC User Guide*. **Topics** + [Create and Configure a New VPC](create-configure-new-vpc-with-private-public-subnets-nat.md) + [Add a NAT Gateway to an Existing VPC](add-nat-gateway-existing-vpc.md) + [Enable Internet Access for WorkSpaces Pools](managing-network-manual-enable-internet-access.md) # Create and Configure a New VPC This topic describes how to use the VPC wizard to create a VPC with a public subnet and one private subnet. As part of this process, the wizard creates an internet gateway and a NAT gateway. It also creates a custom route table associated with the public subnet and updates the main route table associated with the private subnet. The NAT gateway is automatically created in the public subnet of your VPC. After you use the wizard to create the initial VPC configuration, you'll add a second private subnet. For more information about this configuration, see [VPC with Public and Private Subnets (NAT)](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html) in the *Amazon VPC User Guide*. **Note** If you already have a VPC, complete the steps in [Add a NAT Gateway to an Existing VPC](add-nat-gateway-existing-vpc.md) instead. **Topics** + [Step 1: Allocate an Elastic IP Address](#allocate-elastic-ip) + [Step 2: Create a New VPC](#vpc-with-private-and-public-subnets-nat) + [Step 3: Add a Second Private Subnet](#vpc-with-private-and-public-subnets-add-private-subnet-nat) + [Step 4: Verify and Name Your Subnet Route Tables](#verify-name-route-tables) ## Step 1: Allocate an Elastic IP Address Before you create your VPC, you must allocate an Elastic IP address in your WorkSpaces Region. You must first allocate an Elastic IP address for use in your VPC, and then associate it with your NAT gateway. For more information, see [Elastic IP Addresses](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-eips.html) in the *Amazon VPC User Guide*. **Note** Charges may apply to Elastic IP addresses that you use. For more information, see [Elastic IP Addresses](https://docs.aws.amazon.com/ec2/pricing/on-demand/#Elastic_IP_Addresses) on the Amazon EC2 pricing page. Complete the following steps if you don't already have an Elastic IP address. If you want to use an existing Elastic IP address, verify that it's not currently associated with another instance or network interface. **To allocate an Elastic IP address** 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 **Elastic IPs**. 1. Choose **Allocate New Address**, and then choose **Allocate**. 1. Note the Elastic IP address. 1. In the upper right of the **Elastic IPs** pane, click the X icon to close the pane. ## Step 2: Create a New VPC Complete the following steps to create a new VPC with a public subnet and one private subnet. **To create a new VPC** 1. Open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://docs.aws.amazon.com/vpc/). 1. In the navigation pane, choose **VPC Dashboard**. 1. Choose **Launch VPC Wizard**. 1. In **Step 1: Select a VPC Configuration**, choose **VPC with Public and Private Subnets**, and then choose **Select**. 1. In **Step 2: VPC with Public and Private Subnets**, configure the VPC as follows: + For **IPv4 CIDR block**, specify an IPv4 CIDR block for the VPC. + For **IPv6 CIDR block**, keep the default value, **No IPv6 CIDR Block**. + For **VPC name**, type a unique name for the VPC. 1. Configure the public subnet as follows: + For **Public subnet's IPv4 CIDR**, specify the CIDR block for the subnet. + For **Availability Zone**, keep the default value, **No Preference**. + For **Public subnet name**, type a name for the subnet; for example, `WorkSpaces Public Subnet`. 1. Configure the first private subnet as follows: + For **Private subnet's IPv4 CIDR**, specify the CIDR block for the subnet. Make a note of the value that you specify. + For **Availability Zone**, select a specific zone and make a note of the zone that you select. + For **Private subnet name**, type a name for the subnet; for example, `WorkSpaces Private Subnet1`. + For the remaining fields, where applicable, keep the default values. 1. For **Elastic IP Allocation ID**, click in the text box and select the value that corresponds to the Elastic IP address that you created. This address is assigned to the NAT gateway. If you don't have an Elastic IP address, create one by using the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://docs.aws.amazon.com/vpc/). 1. For **Service endpoints**, if an Amazon S3 endpoint is required for your environment, specify one. An S3 endpoint is required to provide users with access to [home folders](persistent-storage.md#home-folders) or to enable [application settings persistence](app-settings-persistence.md) for your users in a private network. To specify an Amazon S3 endpoint, do the following: 1. Choose **Add Endpoint**. 1. For **Service**, select the entry in the list that ends with "s3" (the `com.amazonaws.`*region*`.s3` entry that corresponds to the Region in which the VPC is being created). 1. For **Subnet**, choose **Private subnet**. 1. For **Policy**, keep the default value, **Full Access**. 1. For **Enable DNS hostnames**, keep the default value, **Yes**. 1. For **Hardware tenancy**, keep the default value, **Default**. 1. Choose **Create VPC**. 1. Note that it takes several minutes to set up your VPC. After the VPC is created, choose **OK**. ## Step 3: Add a Second Private Subnet In the previous step ([Step 2: Create a New VPC](#vpc-with-private-and-public-subnets-nat)), you created a VPC with one public subnet and one private subnet. Perform the following steps to add a second private subnet. We recommend that you add a second private subnet in a different Availability Zone than your first private subnet. 1. In the navigation pane, choose **Subnets**. 1. Select the first private subnet that you created in the previous step. On the **Description** tab, below the list of subnets, make a note of the Availability Zone for this subnet. 1. On the upper left of the subnets pane, choose **Create Subnet**. 1. For **Name tag**, type a name for the private subnet; for example, `WorkSpaces Private Subnet2`. 1. For **VPC**, select the VPC that you created in the previous step. 1. For **Availability Zone**, select an Availability Zone other than the one you are using for your first private subnet. Selecting a different Availability Zone increases fault tolerance and helps prevent insufficient capacity errors. 1. For **IPv4 CIDR block**, specify a unique CIDR block range for the new subnet. For example, if your first private subnet has an IPv4 CIDR block range of `10.0.1.0/24`, you could specify a CIDR block range of `10.0.2.0/24` for the new private subnet. 1. Choose **Create**. 1. After your subnet is created, choose **Close**. ## Step 4: Verify and Name Your Subnet Route Tables After you've created and configured your VPC, complete the following steps to specify a name for your route tables, and to verify that: + The route table associated with the subnet in which your NAT gateway resides includes a route that points internet traffic to an internet gateway. This ensures that your NAT gateway can access the internet. + The route tables associated with your private subnets are configured to point internet traffic to the NAT gateway. This enables the streaming instances in your private subnets to communicate with the internet. 1. In the navigation pane, choose **Subnets**, and select the public subnet that you created; for example, `WorkSpaces Public Subnet`. 1. On the **Route Table** tab, choose the ID of the route table; for example, `rtb-12345678`. 1. Select the route table. Under **Name**, choose the edit icon (the pencil), and type a name (for example, `workspaces-public-routetable`), and then select the check mark to save the name. 1. With the public route table still selected, on the **Routes** tab, verify that there is one route for local traffic and another route that sends all other traffic to the internet gateway for the VPC. The following table describes these two routes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-configure-new-vpc-with-private-public-subnets-nat.html) 1. In the navigation pane, choose **Subnets**, and select the first private subnet that you created (for example, `WorkSpaces Private Subnet1`). 1. On the **Route Table** tab, choose the ID of the route table. 1. Select the route table. Under **Name**, choose the edit icon (the pencil), and enter a name (for example, `workspaces-private-routetable`), and then choose the check mark to save the name. 1. On the **Routes** tab, verify that the route table includes the following routes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-configure-new-vpc-with-private-public-subnets-nat.html) 1. In the navigation pane, choose **Subnets**, and select the second private subnet that you created (for example, `WorkSpaces Private Subnet2`). 1. On the **Route Table** tab, verify that the route table is the private route table (for example, `workspaces-private-routetable`). If the route table is different, choose **Edit** and select this route table. **Next Steps** To enable your WorkSpaces in WorkSpaces Pools to access the internet, complete the steps in [Enable Internet Access for WorkSpaces Pools](managing-network-manual-enable-internet-access.md). # Add a NAT Gateway to an Existing VPC If you have already configured a VPC, complete the following steps to add a NAT gateway to your VPC. If you need to create a new VPC, see [Create and Configure a New VPC](create-configure-new-vpc-with-private-public-subnets-nat.md). **To add a NAT gateway to an existing VPC** 1. To create your NAT gateway, complete the steps in [Creating a NAT Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html#nat-gateway-creating) in the *Amazon VPC User Guide*. 1. Verify that your VPC has at least one private subnet. We recommend that you specify two private subnets from different Availability Zones for high availability and fault tolerance. For information about how to create a second private subnet, see [Step 3: Add a Second Private Subnet](create-configure-new-vpc-with-private-public-subnets-nat.md#vpc-with-private-and-public-subnets-add-private-subnet-nat). 1. Update the route table associated with one or more of your private subnets to point internet-bound traffic to the NAT gateway. This enables the streaming instances in your private subnets to communicate with the internet. To do so, complete the steps in [Updating Your Route Table](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html#nat-gateway-create-route) in the *Amazon VPC User Guide*. **Next Steps** To enable your WorkSpaces in WorkSpaces Pools to access the internet, complete the steps in [Enable Internet Access for WorkSpaces Pools](managing-network-manual-enable-internet-access.md). # Enable Internet Access for WorkSpaces Pools After your NAT gateway is available on a VPC, you can enable internet access for your WorkSpaces Pools. You can enable internet access when you [create the WorkSpaces Pool directory](https://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html). Choose the VPC with a NAT gateway when you create the directory. Then select a private subnet for **Subnet 1** and, optionally, another private subnet for **Subnet 2**. If you don't already have a private subnet in your VPC, you may need to create a second private subnet. You can test your internet connectivity by starting your WorkSpaces Pool, and then connecting to a WorkSpace in the pool and browsing to the internet. # Configure a New or Existing VPC with a Public Subnet If you created your Amazon Web Services account after 2013-12-04, you have a [default VPC](default-vpc-with-public-subnet.md) in each AWS Region that includes default public subnets. However, you may want to create your own nondefault VPC or configure an existing VPC to use with your WorkSpaces Pool directory. This topic describes how to configure a nondefault VPC and public subnet to use with WorkSpaces Pools. After you configure your VPC and public subnet, you can provide your WorkSpaces in WorkSpaces Pools with access to the internet by enabling the **Default Internet Access** option. When you enable this option, WorkSpaces Pools enables internet connectivity by associating an [Elastic IP address](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/elastic-ip-addresses-eip.html) to the network interface that is attached from the streaming instance to your public subnet. An Elastic IP address is a public IPv4 address that is reachable from the internet. For this reason, we recommend that you instead use a NAT gateway to provide internet access to your WorkSpaces in WorkSpaces Pools. In addition, when **Default Internet Access** is enabled, a maximum of 100 WorkSpaces are supported. If your deployment must support more than 100 concurrent users, use the [NAT gateway configuration](managing-network-internet-NAT-gateway.md) instead. For more information, see the steps in [Configure a VPC with Private Subnets and a NAT Gateway](managing-network-internet-NAT-gateway.md). For additional VPC configuration recommendations, see [VPC Setup Recommendations for WorkSpaces Pools](vpc-setup-recommendations.md). **Topics** + [Step 1: Configure a VPC with a Public Subnet](#vpc-with-public-subnet) + [Step 2: Enable Default Internet Access For Your WorkSpaces Pools](#managing-network-enable-default-internet-access) ## Step 1: Configure a VPC with a Public Subnet You can configure your own non-default VPC with a public subnet by using either of the following methods: + [Create a New VPC with a Single Public Subnet](#new-vpc-with-public-subnet) + [Configure an Existing VPC](#existing-vpc-with-public-subnet) ### Create a New VPC with a Single Public Subnet When you use the VPC wizard to create a new VPC, the wizard creates an internet gateway and a custom route table that is associated with the public subnet. The route table routes all traffic destined for an address outside the VPC to the internet gateway. For more information about this configuration, see [VPC with a Single Public Subnet](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario1.html) in the* Amazon VPC User Guide*. 1. Complete the steps in [Step 1: Create the VPC](https://docs.aws.amazon.com/vpc/latest/userguide/getting-started-ipv4.html#getting-started-create-vpc) in the *Amazon VPC User Guide* to create your VPC. 1. To enable your WorkSpaces to access the internet, complete the steps in [Step 2: Enable Default Internet Access For Your WorkSpaces Pools](#managing-network-enable-default-internet-access). ### Configure an Existing VPC If you want to use an existing VPC that does not have a public subnet, you can add a new public subnet. In addition to a public subnet, you must also have an internet gateway attached to your VPC and a route table that routes all traffic destined for an address outside the VPC to the internet gateway. To configure these components, complete the following steps. 1. To add a public subnet, complete the steps in [Creating a Subnet in Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet). Use the existing VPC that you plan to use with WorkSpaces Pools. If your VPC is configured to support IPv6 addressing, the **IPv6 CIDR block** list displays. Select **Don't assign Ipv6**. 1. To create and attach an internet gateway to your VPC, complete the steps in [Creating and Attaching an Internet Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway). 1. To configure your subnet to route internet traffic through the internet gateway, complete the steps in [Creating a Custom Route Table](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Routing). In step 5, for **Destination**, use IPv4 format (`0.0.0.0/0`). 1. To enable your WorkSpaces and image builders to access the internet, complete the steps in [Step 2: Enable Default Internet Access For Your WorkSpaces Pools](#managing-network-enable-default-internet-access). ## Step 2: Enable Default Internet Access For Your WorkSpaces Pools You can enable internet access when you [create the WorkSpaces Pool directory](https://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html). Choose the VPC with a public subnet when you create the directory. Then select a public subnet for **Subnet 1** and, optionally, another public subnet for **Subnet 2**. You can test your internet connectivity by starting your WorkSpaces Pool, and then connecting to a WorkSpace in the pool and browsing to the internet. # Use the Default VPC, Public Subnet, and Security Group Your Amazon Web Services account, if it was created after 2013-12-04, has a default VPC in each AWS Region. The default VPC includes a default public subnet in each Availability Zone and an internet gateway that is attached to your VPC. The VPC also includes a default security group. If you are new to WorkSpaces Pools and want to get started using the service, you can keep the default VPC and security group selected when you create a WorkSpaces Pool. Then, you can select at least one default subnet. **Note** If your Amazon Web Services account was created before 2013-12-04, you must create a new VPC or configure an existing one to use with WorkSpaces Pools. We recommend that you manually configure a VPC with two private subnets for your WorkSpaces Pools and a NAT gateway in a public subnet. For more information, see [Configure a VPC with Private Subnets and a NAT Gateway](managing-network-internet-NAT-gateway.md). Alternatively, you can configure a non-default VPC with a public subnet. For more information, see [Configure a New or Existing VPC with a Public Subnet](managing-network-default-internet-access.md). You can enable internet access when you [create the WorkSpaces Pool directory](https://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html). Choose the default VPC when you create the directory. The default VPC name uses the following format: `vpc-`*vpc-id*` (No_default_value_Name)`. Then select a default public subnet for **Subnet 1** and, optionally, another default public subnet for **Subnet 2**. The default subnet names use the following format: `subnet-`*subnet-id*` | (`*IPv4 CIDR block*`) | Default in` *availability-zone*. You can test your internet connectivity by starting your WorkSpaces Pool, and then connecting to a WorkSpace in the pool and browsing to the internet. # Configure FedRAMP authorization or DoD SRG compliance for WorkSpaces Pools 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 Pools 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/). **Requirements** + The WorkSpaces Pools directory must be configured to use **FIPS 140-2 Validated Mode** for endpoint encryption. **Note** To use the **FIPS 140-2 Validated Mode** setting, ensure the following: The WorkSpaces Pools directory is either: New and not associated with a Pool Associated with an existing Pool that is in the STOPPED state The Pool directory has [https://docs.aws.amazon.com/workspaces/latest/api/API_ModifyStreamingProperties.html](https://docs.aws.amazon.com/workspaces/latest/api/API_ModifyStreamingProperties.html) set to TCP. + You must create your WorkSpaces Pools in a [US AWS Region that has FedRAMP authorization or is DoD SRG-compliant](https://aws.amazon.com/compliance/services-in-scope/). + Users must access their WorkSpaces from one of the following WorkSpaces client applications: + macOS: 5.20.0 or later + Windows: 5.20.0 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** then choose the directory that you want to use for FedRAMP authorization and DoD SRG compliance. 1. On the **Directory Details** page, choose the directory that you want to configure for FIPS encryption mode. 1. In the **Endpoint encryption** section, choose **Edit** and then select **FIPS 140-2 Validated Mode**. 1. Choose **Save**. # Using Amazon S3 VPC Endpoints for WorkSpaces Pools Features When you enable Application Settings Persistence for a WorkSpaces Pool or Home folders for a WorkSpaces Pool directory, WorkSpaces uses the VPC you specify for your directory to provide access to Amazon Simple Storage Service (Amazon S3) buckets. To enable WorkSpaces Pools access to your private S3 endpoint, attach the following custom policy to your VPC endpoint for Amazon S3. For more information about private Amazon S3 endpoints, see [VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html) and [Endpoints for Amazon S3](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html) in the *Amazon VPC User Guide*. ------ #### [ Commercial AWS Regions ] Use the following policy for resources in the commercial AWS Regions. ------ #### [ AWS GovCloud (US) Regions ] Use the following policy for resources in the commercial AWS GovCloud (US) Regions. ------ # Connections to Your VPC for WorkSpaces Pools To enable WorkSpaces Pools connectivity to network resources and the internet, configure your WorkSpaces as follows. ## Network Interfaces Each WorkSpaces in WorkSpaces Pools has the following network interfaces: + The customer network interface provides connectivity to the resources within your VPC, as well as the internet, and is used to join the WorkSpaces to your directory. + The management network interface is connected to a secure WorkSpaces Pools management network. It is used for interactive streaming of the WorkSpace to a user's device, and to allow WorkSpaces Pools to manage the WorkSpace. WorkSpaces Pools selects the IP address for the management network interface from the following private IP address range: 198.19.0.0/16. Do not use this range for your VPC CIDR or peer your VPC with another VPC with this range, as this might create a conflict and cause WorkSpaces to be unreachable. Also, do not modify or delete any of the network interfaces attached to a WorkSpace, as this might also cause the WorkSpace to become unreachable. ## Management Network Interface IP Address Range and Ports The management network interface IP address range is 198.19.0.0/16. The following ports must be open on the management network interface of all WorkSpaces: + Inbound TCP on port 8300. This is used for establishment of the streaming connection. + Outbound TCP on port 3128. This is used for management of WorkSpaces. + Inbound TCP on ports 8000 and 8443. These are used for management of the WorkSpaces. + Inbound UDP on port 8300. This is used for establishment of the streaming connection over UDP. Limit the inbound range on the management network interface to 198.19.0.0/16. **Note** For Amazon DCV BYOL Windows WorkSpaces Pools, the 10.0.0.0/8 IP address ranges are used in all AWS Regions. These IP ranges are in addition to the /16 CIDR block that you choose for management traffic in your BYOL WorkSpaces Pools. Under normal circumstances, WorkSpaces Pools correctly configures these ports for your WorkSpaces. If any security or firewall software is installed on a WorkSpace that blocks any of these ports, the WorkSpaces might not function correctly or might be unreachable. Do not disable IPv6. If you disable IPv6, WorkSpaces Pools will not function correctly. For information about configuring IPv6 for Windows, see [Guidance for configuring IPv6 in Windows for advanced users](https://support.microsoft.com/en-us/help/929852/guidance-for-configuring-ipv6-in-windows-for-advanced-users). **Note** WorkSpaces Pools relies on the DNS servers within your VPC to return a non-existent domain (NXDOMAIN) response for local domain names that don’t exist. This enables the WorkSpaces Pools-managed network interface to communicate with the management servers. When you create a directory with Simple AD, AWS Directory Service creates two domain controllers that also function as DNS servers on your behalf. Because the domain controllers don't provide the NXDOMAIN response, they can't be used with WorkSpaces Pools. ## Customer Network Interface Ports + For internet connectivity, the following ports must be open to all destinations. If you are using a modified or custom security group, you need to add the required rules manually. For more information, see [Security Group Rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC User Guide*. + TCP 80 (HTTP) + TCP 443 (HTTPS) + UDP 4195 + If you join your WorkSpaces to a directory, the following ports must be open between your WorkSpaces Pools VPC and your directory controllers. + 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 1024-65535 - Dynamic ports for RPC For a complete list of ports, see [Active Directory and Active Directory Domain Services Port Requirements](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/dd772723(v=ws.10)) in the Microsoft documentation. + All WorkSpaces require that port 80 (HTTP) be open to IP address `169.254.169.254` to allow access to the EC2 metadata service. The IP address range `169.254.0.0/16` is reserved for WorkSpaces Pools service usage for management traffic. Failure to exclude this range might result in streaming issues. # User connections to WorkSpaces Pools Users can connect to WorkSpaces in WorkSpaces Pools through the default public internet endpoint. By default, WorkSpaces Pools is configured to route streaming connections over the public internet. Internet connectivity is required to authenticate users and deliver the web assets that WorkSpaces Pools requires to function. To allow this traffic, you must allow the domains listed in [Allowed Domains](allowed-domains.md). **Note** For user authentication, WorkSpaces Pools supports Security Assertion Markup Language 2.0 (SAML 2.0). For more information, see [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md). The following topics provide information about how to enable user connections to WorkSpaces Pools. **Topics** + [Bandwidth Recommendations](bandwidth-recommendations-user-connections.md) + [IP Address and Port Requirements for WorkSpaces Pools User Devices](pools-client-application-ports.md) + [Allowed Domains](allowed-domains.md) # Bandwidth Recommendations To optimize the performance of WorkSpaces Pools, make sure that your network bandwidth and latency can sustain your users' needs. WorkSpaces Pools uses NICE Desktop Cloud Visualization (DCV) to enable your users to securely access and stream your applications over varying network conditions. To help reduce bandwidth consumption, NICE DCV uses H.264-based video compression and encoding. During streaming sessions, the visual output of applications is compressed and streamed to your users as an AES-256 encrypted pixel stream over HTTPS. After the stream is received, it is decrypted and output to your users’ local screen. When your users interact with their streaming applications, the NICE DCV protocol captures their input and sends it back to their streaming applications over HTTPS. Network conditions are constantly measured during this process and information is sent back to WorkSpaces Pools. WorkSpaces Pools dynamically responds to changing network conditions by changing the video and audio encoding in real time to produce a high-quality stream for a wide variety of applications and network conditions. The recommended bandwidth and latency for WorkSpaces Pools streaming sessions depends on the workload. For example, a user who works with graphic-intensive applications to perform computer-aided design tasks will require more bandwidth and lower latency than a user who works with business productivity applications to write documents. The following table provides guidance on the recommended network bandwidth and latency for WorkSpaces Pools streaming sessions based on common workloads. For each workload, the bandwidth recommendation is based on what an individual user might require at a specific point in time. The recommendation does not reflect the bandwidth required for sustained throughput. When only a few pixels change on the screen during a streaming session, the sustained throughput is much lower. Although users who have less bandwidth available can still stream their applications, the frame rate or image quality may not be optimal. | Workload | Description | Bandwidth recommended per user | Recommended maximum roundtrip latency | | --- | --- | --- | --- | | Line of business applications | Document writing applications, database analysis utilities | 2 Mbps | < 150 ms | | Graphics applications | Computer-aided design and modeling applications, photo and video editing | 5 Mbps | < 100 ms | | High fidelity | High-fidelity datasets or maps across multiple monitors | 10 Mbps | < 50 ms | # IP Address and Port Requirements for WorkSpaces Pools User Devices WorkSpaces Pools users' devices require outbound access on port 443 (TCP) and port 4195 (UDP) when using the internet endpoints, and if you are using DNS servers for domain name resolution, port 53 (UDP). + Port 443 is used for HTTPS communication between WorkSpaces Pools users' devices and WorkSpaces when using the internet endpoints. Typically, when end users browse the web during streaming sessions, the web browser randomly selects a source port in the high range for streaming traffic. You must ensure that return traffic to this port is allowed. + Port 4195 is used for UDP HTTPS communication between WorkSpaces Pools users' devices and WorkSpaces when using the internet endpoints. This is currently only supported in the Windows native client. UDP is not supported if you are using VPC endpoints. + Port 53 is used for communication between WorkSpaces Pools users' devices and your DNS servers. The port must be open to the IP addresses for your DNS servers so that public domain names can be resolved. This port is optional if you are not using DNS servers for domain name resolution. # Allowed Domains For WorkSpaces Pools users to access WorkSpaces, you must allow various domains on the network from which users initiate access to the WorkSpaces. For more information, see [IP address and port requirements for WorkSpaces Personal](workspaces-port-requirements.md). Note that the page specifies that it applies to WorkSpaces Personal but it also applies to WorkSpaces Pools. **Note** If your S3 bucket has a “.” character in the name, the domain used is `https://s3..amazonaws.com`. If your S3 bucket does not have a “.” character in the name, the domain used is `https://.s3..amazonaws.com`. # Create a WorkSpaces Pool Set up and create a pool from which user applications are launched and streamed. **Note** You should create a directory before you create a WorkSpaces Pool. For more information, see [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md). **To set up and create a pool** 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**, **Pool**. 1. Choose **Create WorkSpaces Pools**. 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 WorkSpaces Pools. 1. Under ** Configure WorkSpaces**, enter the following details: + For **Name**, enter a unique name identifier for the pool. Special characters aren't allowed. + For **Description**, enter a description for the pool (maximum of 256 characters). + 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 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). + For **Running mode**, choose from the following to configure the pool’s immediate availability and how you pay for it: + **AutoStop** — Pools instances are billed an hourly usage fee, based on the bundle chosen, only for the instances that are connected to users. Instances within the pool that are not connected to users are billed a low stopped-instance hourly fee. When users initiate their session, they start streaming after a 1-2 minute wait. + **AlwaysOn** — All pools instances that are running are billed the applicable hourly usage fee, even when users aren't connected. This mode is best for users who don’t want to wait for their streaming to start. + For **Maximum session duration in minutes**, choose the maximum amount of time that a streaming session can remain active. If users are still connected to a streaming instance five minutes before this limit is reached, they are prompted to save any open documents before being disconnected. After this time elapses, the instance is terminated and replaced by a new instance. The maximum session duration that you can set in the WorkSpaces Pools console is 5760 minutes (96 hours). The maximum session duration that you can set using the WorkSpaces Pools API and CLI is 432000 seconds (120 hours). + For **Disconnect timeout in minutes**, choose the amount of time that a streaming session remains active after users disconnect. If users try to reconnect to the streaming session after a disconnection or network interruption within this time interval, they are connected to their previous session. Otherwise, they are connected to a new session with a new streaming instance. + If a user ends the session by choosing **End Session** or **Logout** on the pools toolbar, the disconnect timeout doesn’t apply. Instead, the user is prompted to save any open documents, and then immediately disconnected from the streaming instance. The instance the user was using is then terminated. + For **Idle disconnect timeout in minutes**, choose the amount of time that users can be idle (inactive) before they are disconnected from their streaming session and the **Disconnect timeout in minutes** time interval begins. Users are notified before they are disconnected due to inactivity. If they try to reconnect to the streaming session before the time interval specified in **Disconnect timeout in minutes** has elapsed, they are connected to their previous session. Otherwise, they are connected to a new session with a new streaming instance. Setting this value to 0 disables it. When this value is disabled, users are not disconnected due to inactivity. **Note** Users are considered idle when they stop providing keyboard or mouse input during their streaming session. For domain-joined pools, the countdown for the idle disconnect timeout doesn't begin until users log in with their Active Directory domain password or with a smart card. File uploads and downloads, audio in, audio out, and pixels changing do not qualify as user activity. If users continue to be idle after the time interval in **Idle disconnect timeout in minutes** elapses, they are disconnected. + For **Scheduled capacity policies** (optional), choose **Add new schedule capacity**. Indicate the start and end date and time for when to provision the minimum and maximum number of instances for your pool based on the minimum number of expected concurrent users. + For **Manual scaling policies** (optional), specify the scaling policies for pools to use to increase and decrease the capacity of your pool. Expand **Manual scaling policies** to add new scaling policies. **Note** The size of your pool is limited by the minimum and maximum capacity that you specified. + Choose **Add new scale out policies** and enter the values for adding specified instances if the specified capacity utilization is less or more than the specified threshold value. + Choose **Add new scale in policies** and enter the values for removing specified instances if the specified capacity utilization is less or more than the specified threshold value. + 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. On the **Select directory page**, choose the directory that you created. To create a directory, choose **Create directory**. For more information, see [Manage directories for WorkSpaces Pools](manage-workspaces-pools-directory.md). 1. Choose **Create WorkSpace Pool**. # Administer WorkSpaces Pools A WorkSpaces Pool consists of WorkSpaces that run the image that you specify. **Topics** + [Running mode](running-mode-pools.md) + [Bundles](instance-types.md) + [Modify a pool](modify-pool.md) + [Delete a pool](set-up-pools-finish.md) + [Auto Scaling for WorkSpaces Pools](autoscaling.md) # Running mode for WorkSpaces Pools The running mode of a WorkSpaces Pool determines its immediate availability and how you pay for it. You can choose between the following running modes when you create a WorkSpaces Pool: + **AutoStop** — Instances of a WorkSpaces Pool are billed an hourly usage fee based on the bundle chosen, only for the instances that are connected to users. Instances within a WorkSpaces Pool that are not connected to users are billed a low stopped-instance hourly fee. When users initiate their session, they start streaming after 1-2 minutes. + **AlwaysOn** — Running instances of a WorkSpaces Pool are billed the applicable hourly usage fee, even when users aren't connected. This mode is best for users who don’t want to wait for their streaming to start. For more information, see [WorkSpaces Pricing](https://aws.amazon.com/workspaces/pricing/). **Topics** + [Modify the running mode](modify-running-mode-pool.md) # Modify the running mode You can switch between running modes when a WorkSpaces Pool is in stopped state. **To modify the running mode of a WorkSpaces Pool** 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** and **Pools**. 1. Select the WorkSpaces Pool to modify and cofirm it’s in stopped state. Then, choose **Actions** and **Modify running mode**. 1. Select the new running mode, **AlwaysOn** or **AutoStop**, and then choose **Save**. **To modify the running mode of a WorkSpaces Pool using the AWS CLI** + Use the [update-workspaces-pool](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/workspaces/update-workspaces-pool.html) command. # WorkSpaces Pools Bundles 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). 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 | | --- | --- | --- | --- | | Windows Server 2019 | Included | DCV | Value, Standard, Performance, Power, PowerPro | | Windows Server 2022 | Included | DCV | Standard, Performance, Power, PowerPro, Graphics.G4dn, GraphicsPro.G4dn | **Note** Operating system versions that are no longer supported by the vender are not guaranteed to work and are not supported by AWS support. # Modify a pool After creating a WorkSpaces Pool, you can modify the following: + Directory ID (if the WorkSpaces Pool is stopped) + Basic details + Bundle and hardware + Session disconnect settings + Capacity and scaling + Scaling activities + Tags **To modify a WorkSpaces Pool** 1. In the navigation pane, choose **WorkSpaces**, **Pools**. 1. Select the pool you want to modify. 1. Go to the section that you want to modify and choose **Edit**. 1. Make the modifications that you want to make and choose **Save**. # Delete a pool You can delete pools to free up resources and to avoid unintended charges to your account. We recommend stopping any unused, running pools. **To delete a pool** 1. In the navigation pane, choose **WorkSpaces**, **Pools**. 1. Select the pool that you want to stop, and then choose **Stop**. It takes about 5 minutes to stop a pool. 1. When the status of the pool is **Stopped**, choose **Delete**. # Auto scaling for WorkSpaces Pools Auto Scaling lets you change the size of your pools automatically to match the supply of available instances to user demand. The size of your pool determines the number of users who can stream concurrently. One instance is required for each user session. You can specify your pool capacity in terms of instances. Based on your pool configurations and auto scaling policies, the required number of instances will be made available. You can define scaling policies that adjust the size of your pool automatically based on a variety of utilization metrics, and optimize the number of available instances to match user demand. You can also choose to turn off automatic scaling and make the pool run at a fixed size. **Note** As you develop your plan for WorkSpaces Pools scaling, make sure that your network configuration meets your requirements. When you use scaling, you work with the Application Auto Scaling API. For Auto Scaling to work correctly with WorkSpaces Pools, Application Auto Scaling requires permission to describe and update your pools and describe your Amazon CloudWatch alarms, and permissions to modify your pool capacity on your behalf. The following topics provide information to help you understand and use Auto Scaling for WorkSpaces Pools. **Topics** + [Scaling concepts](#autoscaling-concepts) + [Managing pool scaling using the console](#autoscaling-console) + [Managing pool scaling using the AWS CLI](#autoscaling-cli) + [Additional resources](#autoscaling-additional-resources) ## Scaling concepts WorkSpaces Pools scaling is provided by Application Auto Scaling. For more information, see the [Application Auto Scaling API Reference](https://docs.aws.amazon.com/autoscaling/application/APIReference/). To use Auto Scaling with WorkSpaces Pools effectively, you must understand the following terms and concepts. **Minimum capacity/minimum user sessions for the pool** The minimum number of instances. The number of instances can't be below this value, and scaling policies will not scale your pool below this value. For example, if you set the minimum capacity for a pool to 2, your pool will never have less than 2 instances. **Maximum capacity/maximum user sessions for the pool** The maximum number of instances. The number of instances can't be above this value, and scaling policies will not scale your pool above this value. For example, if you set the maximum capacity for a pool to 10, your pool will never have more than 10 instances. **Desired user session capacity** The total number of sessions that are either running or pending. This represents the total number of concurrent streaming sessions your pool can support in a steady state. **Scaling policy action** The action that scaling policies perform on your pool when the **Scaling Policy Condition** is met. You can choose an action based on **% capacity** or **number of instance(s)**. For example, if **Desired user session capacity** is 4 and **Scaling Policy Action** is set to "Add 25% capacity", **Desired user session capacity** is increased by 25% to 5 when **Scaling Policy Condition** is met. **Scaling policy condition** The condition that triggers the action set in **Scaling Policy Action**. This condition includes a scaling policy metric, a comparison operator, and a threshold. For example, to scale a pool if the utilization of the pool is greater than 50%, your scaling policy condition should be "If Capacity Utilization > 50%". **Scaling policy metric** Your scaling policy is based on this metric. The following metrics are available for scaling policies: **Capacity Utilization** The percentage of instances in a pool that are being used. You can use this metric to scale your pool based on usage of the pool. For example, **Scaling Policy Condition**: "If Capacity Utilization < 25%" perform **Scaling Policy Action**: "Remove 25 % capacity". **Available capacity** The number of instances in your pool that are available for users. You can use this metric to maintain a buffer in your capacity available for users to start streaming sessions. For example, **Scaling Policy Condition**: "If Available Capacity < 5" perform **Scaling Policy Action**: "Add 5 instance(s)". **Insufficient capacity error** The number of session requests rejected due to lack of capacity. You can use this metric to provision new instances for users who can't start streaming sessions due to lack of capacity. For example, **Scaling Policy Condition**: "If Insufficient Capacity Error > 0" perform **Scaling Policy Action**: "Add 1 instance(s)". ## Managing pool scaling using the console You can set up and manage scaling by using the WorkSpaces console in either of the following two ways: During pool creation, or any time, by using the **Pools** tab. After you create pools, go to the **Scaling Policies** tab to add new scaling policies for your pool. For more information, see [Create a WorkSpaces Pool](set-up-pools-create.md). For user environments that vary in number, define scaling policies to control how scaling responds to demand. If you expect a fixed number of users or have other reasons for disabling scaling, you can set your pool with a fixed number of instances for user sessions. To do this, set the minimum capacity to your desired number of instances. Adjust the maximum capacity to be at least the value of the minimum capacity. This avoids validation errors, but the maximum capacity will ultimately be ignored since the pool will not be scaled. Then, delete all scaling policies for that pool. **To set a pool scaling policy 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 **Pools**. 1. Select the pool. 1. On that pool's page, scroll down to capacity and scaling. 1. Choose **Edit**. 1. Edit existing policies and set the desired values in their field and choose **Save**. The policy changes go into effect within a few minutes. 1. You can also add new capacity and scaling policies by choosing **Add new schedule capacity**, **Add new scale out policy**, or **Add new scale in policy**. The following is an example usage graph of scaling activity when five users connect to the pool and then disconnect. This example is from a pool using the following scaling policy values: + Minimum capacity = 10 + Maximum capacity = 50 + Scale out = If my pool Capacity Utilization is Greater than 75% then add 5 instances + Scale in = If my pool Capacity Utilization is Less than 25% then remove 6 instances **Note** During the session, 5 new instances will be launched during a scale out event. During a scale in event, 6 instances will be reclaimed, if there are enough instances without active user sessions, and the total number of instances does not drop below the minimum capacity of 10 instances. Instances with running user sessions will not be reclaimed. Only instances with no user sessions running will be reclaimed. ## Managing pool scaling using the AWS CLI You can set up and manage pool scaling by using the AWS Command Line Interface (AWS CLI). For more advanced features such as setting scale-in and scale-out cooldown times, use the AWS CLI. Before running scaling policy commands, you must register your pool as a scalable target. To do so, use the following [register-scalable-target](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/register-scalable-target.html) command: ``` aws application-autoscaling register-scalable-target --service-namespace workspaces \ --resource-id workspacespool/PoolId \ --scalable-dimension workspaces:workspacespool:DesiredUserSessions \ --min-capacity 1 --max-capacity 5 ``` **Topics** + [Example 1: Applying a scaling policy based on capacity utilization](#autoscaling-cli-utilization) + [Example 2: Applying a scaling policy based on insufficient capacity errors](#autoscaling-cli-capacity) + [Example 3: Applying a scaling policy based on low capacity utilization](#autoscaling-cli-scale-in) + [Example 4: Change the pool capacity based on a schedule](#autoscaling-cli-schedule) + [Example 5: Applying a target tracking scaling policy](#autoscaling-target-tracking) ### Example 1: Applying a scaling policy based on capacity utilization This AWS CLI example sets up a scaling policy that scales out a pool by 25% if Utilization >= 75%. The following [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html) command defines a utilization-based scaling policy: ``` aws application-autoscaling put-scaling-policy -- cli-input-json file://scale-out-utilization.json ``` The contents of the file `scale-out-utilization.json` are as follows: ``` { "PolicyName": "policyname", "ServiceNamespace": "workspaces", "ResourceId": "workspacespool/PoolId", "ScalableDimension": "workspaces:workspacespool:DesiredUserSessions", "PolicyType": "StepScaling", "StepScalingPolicyConfiguration": { "AdjustmentType": "PercentChangeInCapacity", "StepAdjustments": [ { "MetricIntervalLowerBound": 0, "ScalingAdjustment": 25 } ], "Cooldown": 120 } } ``` If the command is successful, the output is similar to the following, although some details are unique to your account and Region. In this example, the policy identifier is `e3425d21-16f0-d701-89fb-12f98dac64af`. ``` {"PolicyARN": "arn:aws:autoscaling:us-west-2:123456789012:scalingPolicy:e3425d21-16f0-d701-89fb-12f98dac64af:resource/workspaces/workspacespool/PoolId:policyName/scale-out-utilization-policy"} ``` Now, set up a CloudWatch alarm for this policy. Use the names, Region, account number, and policy identifier that apply to you. You can use the policy ARN returned by the previous command for the `-- alarm-actions` parameter. ``` aws cloudwatch put-metric-alarm --alarm-name alarmname \ --alarm-description "Alarm when Available User Session Capacity exceeds 75 percent" \ --metric-name AvailableUserSessionCapacity \ --namespace AWS/WorkSpaces \ --statistic Average \ --period 300 \ --threshold 75 \ --comparison-operator GreaterThanOrEqualToThreshold \ --dimensions "Name=WorkSpaces pool ID,Value=PoolId" \ --evaluation-periods 1 --unit Percent \ --alarm-actions "arn:aws:autoscaling:your-region-code:account-number-without-hyphens:scalingPolicy:policyid:resource/workspaces/workspacespool/PoolId:policyName/policyname" ``` ### Example 2: Applying a scaling policy based on insufficient capacity errors This AWS CLI example sets up a scaling policy that scales out the pool by 1 if the pool returns an `InsufficientCapacityError` error. The following command defines a insufficient capacity-based scaling policy: ``` aws application-autoscaling put-scaling-policy -- cli-input-json file://scale-out-capacity.json ``` The contents of the file `scale-out-capacity.json` are as follows: ``` { "PolicyName": "policyname", "ServiceNamespace": "workspaces", "ResourceId": "workspacespool/PoolId", "ScalableDimension": "workspaces:workspacespool:DesiredUserSessions", "PolicyType": "StepScaling", "StepScalingPolicyConfiguration": { "AdjustmentType": "ChangeInCapacity", "StepAdjustments": [ { "MetricIntervalLowerBound": 0, "ScalingAdjustment": 1 } ], "Cooldown": 120 } } ``` If the command is successful, the output is similar to the following, although some details are unique to your account and Region. In this example, the policy identifier is `f4495f21-0650-470c-88e6-0f393adb64fc`. ``` {"PolicyARN": "arn:aws:autoscaling:us-west-2:123456789012:scalingPolicy:f4495f21-0650-470c-88e6-0f393adb64fc:resource/workspaces/workspacespool/PoolId:policyName/scale-out-insufficient-capacity-policy"} ``` Now, set up a CloudWatch alarm for this policy. Use the names, Region, account number, and policy identifier that apply to you. You can use the policy ARN returned by the previous command for the `--alarm-actions` parameter. ``` aws cloudwatch put-metric-alarm --alarm-name alarmname \ --alarm-description "Alarm when out of capacity is > 0" \ --metric-name InsufficientCapacityError \ --namespace AWS/WorkSpaces \ --statistic Maximum \ --period 300 \ --threshold 0 \ --comparison-operator GreaterThanThreshold \ --dimensions "Name=Pool,Value=PoolId" \ --evaluation-periods 1 --unit Count \ --alarm-actions "arn:aws:autoscaling:your-region-code:account-number-without-hyphens:scalingPolicy:policyid:resource/workspaces/workspacespool/PoolId:policyName/policyname" ``` ### Example 3: Applying a scaling policy based on low capacity utilization This AWS CLI example sets up a scaling policy that scales in the pool to reduce actual capacity when `UserSessionsCapacityUtilization` is low. The following command defines an excess capacity-based scaling policy: ``` aws application-autoscaling put-scaling-policy -- cli-input-json file://scale-in-capacity.json ``` The contents of the file `scale-in-capacity.json` are as follows: ``` { "PolicyName": "policyname", "ServiceNamespace": "workspaces", "ResourceId": "workspacespool/PoolId", "ScalableDimension": "workspaces:workspacespool:DesiredUserSessions", "PolicyType": "StepScaling", "StepScalingPolicyConfiguration": { "AdjustmentType": "PercentChangeInCapacity", "StepAdjustments": [ { "MetricIntervalUpperBound": 0, "ScalingAdjustment": -25 } ], "Cooldown": 360 } } ``` If the command is successful, the output is similar to the following, although some details are unique to your account and Region. In this example, the policy identifier is `12ab3c4d-56789-0ef1-2345-6ghi7jk8lm90`. ``` {"PolicyARN": "arn:aws:autoscaling:us-west-2:123456789012:scalingPolicy:12ab3c4d-56789-0ef1-2345-6ghi7jk8lm90:resource/workspaces/workspacespool/PoolId:policyName/scale-in-utilization-policy"} ``` Now, set up a CloudWatch alarm for this policy. Use the names, Region, account number, and policy identifier that apply to you. You can use the policy ARN returned by the previous command for the `--alarm-actions` parameter. ``` aws cloudwatch put-metric-alarm --alarm-name alarmname \ --alarm-description "Alarm when Capacity Utilization is less than or equal to 25 percent" \ --metric-name UserSessionsCapacityUtilization \ --namespace AWS/WorkSpaces \ --statistic Average \ --period 120 \ --threshold 25 \ --comparison-operator LessThanOrEqualToThreshold \ --dimensions "Name=Pool,Value=PoolId" \ --evaluation-periods 10 --unit Percent \ --alarm-actions "arn:aws:autoscaling:your-region-code:account-number-without-hyphens:scalingPolicy:policyid:resource/workspaces/workspacespool/PoolId:policyName/policyname" ``` ### Example 4: Change the pool capacity based on a schedule Changing your pool capacity based on a schedule lets you scale your pool capacity in response to predictable changes in demand. For example, at the start of a work day, you might expect a certain number of users to request streaming connections at one time. To change your pool capacity based on a schedule, you can use the Application Auto Scaling [PutScheduledAction](https://docs.aws.amazon.com/autoscaling/application/APIReference/API_PutScheduledAction.html) API action or the [put-scheduled-action](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scheduled-action.html) AWS CLI command. Before changing your pool capacity, you can list your current pool capacity by using the WorkSpaces [describe-workspaces-pools](https://docs.aws.amazon.com/cli/latest/reference/workspaces/describe-workspaces-pools.html) AWS CLI command. ``` aws workspaces describe-workspaces-pools --name PoolId ``` The current pool capacity will appear similar to the following output (shown in JSON format): ``` { "CapacityStatus": { "AvailableUserSessions": 1, "DesiredUserSessions": 1, "ActualUserSessions": 1, "ActiveUserSessions": 0 }, } ``` Then, use the `put-scheduled-action` command to create a scheduled action to change your pool capacity. For example, the following command changes the minimum capacity to 3 and the maximum capacity to 5 every day at 9:00 AM UTC. **Note** For cron expressions, specify when to perform the action in UTC. For more information, see [Cron Expressions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html#CronExpressions). ``` aws application-autoscaling put-scheduled-action --service-namespace workspaces \ --resource-id workspacespool/PoolId \ --schedule="cron(0 9 * * ? *)" \ --scalable-target-action MinCapacity=3,MaxCapacity=5 \ --scheduled-action-name ExampleScheduledAction \ --scalable-dimension workspaces:workspacespool:DesiredUserSessions ``` To confirm that the scheduled action to change your pool capacity was successfully created, run the [describe-scheduled-actions](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/describe-scheduled-actions.html) command. ``` aws application-autoscaling describe-scheduled-actions --service-namespace workspaces --resource-id workspacespool/PoolId ``` If the scheduled action was successfully created, the output appears similar to the following. ``` { "ScheduledActions": [ { "ScalableDimension": "workspaces:workspacespool:DesiredUserSessions", "Schedule": "cron(0 9 * * ? *)", "ResourceId": "workspacespool/ExamplePool", "CreationTime": 1518651232.886, "ScheduledActionARN": "", "ScalableTargetAction": { "MinCapacity": 3, "MaxCapacity": 5 }, "ScheduledActionName": "ExampleScheduledAction", "ServiceNamespace": "workspaces" } ] } ``` For more information, see [Scheduled Scaling](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-scheduled-scaling.html) in the *Application Auto Scaling User Guide*. ### Example 5: Applying a target tracking scaling policy With target tracking scaling, you can specify a capacity utilization level for your pool. When you create a target tracking scaling policy, Application Auto Scaling automatically creates and manages CloudWatch alarms that trigger the scaling policy. The scaling policy adds or removes capacity as required to keep capacity utilization at, or close to, the specified target value. To ensure application availability, your pool scales out proportionally to the metric as fast as it can but scales in more gradually. The following [put-scaling-policy](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scaling-policy.html) command defines a target tracking scaling policy that attempts to maintain 75% capacity utilization for a WorkSpaces pool. ``` aws application-autoscaling put-scaling-policy -- cli-input-json file://config.json ``` The contents of the file `config.json` are as follows: ``` { "PolicyName":"target-tracking-scaling-policy", "ServiceNamespace":"workspaces", "ResourceId":"workspacespool/PoolId", "ScalableDimension":"workspaces:workspacespool:DesiredUserSessions", "PolicyType":"TargetTrackingScaling", "TargetTrackingScalingPolicyConfiguration":{ "TargetValue":75.0, "PredefinedMetricSpecification":{ "PredefinedMetricType":"WorkSpacesAverageUserSessionsCapacityUtilization" }, "ScaleOutCooldown":300, "ScaleInCooldown":300 } } ``` If the command is successful, the output is similar to the following, although some details are unique to your account and Region. In this example, the policy identifier is 6d8972f3-efc8-437c-92d1-6270f29a66e7. ``` { "PolicyARN": "arn:aws:autoscaling:us-west-2:123456789012:scalingPolicy:6d8972f3-efc8-437c-92d1-6270f29a66e7:resource/workspaces/workspacespool/PoolId:policyName/target-tracking-scaling-policy", "Alarms": [ { "AlarmARN": "arn:aws:cloudwatch:us-west-2:123456789012:alarm:TargetTracking-workspacespool/PoolId-AlarmHigh-d4f0770c-b46e-434a-a60f-3b36d653feca", "AlarmName": "TargetTracking-workspacespool/PoolId-AlarmHigh-d4f0770c-b46e-434a-a60f-3b36d653feca" }, { "AlarmARN": "arn:aws:cloudwatch:us-west-2:123456789012:alarm:TargetTracking-workspacespool/PoolId-AlarmLow-1b437334-d19b-4a63-a812-6c67aaf2910d", "AlarmName": "TargetTracking-workspacespool/PoolId-AlarmLow-1b437334-d19b-4a63-a812-6c67aaf2910d" } ] } ``` For more information, see [Target Tracking Scaling Policies](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-target-tracking.html) in the *Application Auto Scaling User Guide*. ## Additional resources To learn more about using the Application Auto Scaling AWS CLI commands or API actions, see the following resources: + [application-autoscaling](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling) section of the *AWS CLI Command Reference* + [Application Auto Scaling API Reference](https://docs.aws.amazon.com/autoscaling/application/APIReference/) + [Application Auto Scaling User Guide](https://docs.aws.amazon.com/autoscaling/application/userguide/) # Using Active Directory with WorkSpaces Pools You can join your Windows WorkSpaces in WorkSpaces Pools to domains in Microsoft Active Directory and use your existing Active Directory domains, either cloud-based or on-premises, to launch domain-joined streaming instances. You can also use AWS Directory Service for Microsoft Active Directory, also known as AWS Managed Microsoft AD, to create an Active Directory domain and use that to support your WorkSpaces Pools resources. For more information about using AWS Managed Microsoft AD, see [Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html) in the *AWS Directory Service Administration Guide*. By joining WorkSpaces Pools to your Active Directory domain, you can: + Allow your users and applications to access Active Directory resources such as printers and file shares from streaming sessions. + Use Group Policy settings that are available in the Group Policy Management Console (GPMC) to define the end user experience. + Stream applications that require users to be authenticated using their Active Directory login credentials. + Apply your enterprise compliance and security policies to your WorkSpaces in WorkSpaces Pools. **Topics** + [Overview of Active Directory Domains](active-directory-overview.md) + [Before You Begin Using Active Directory with WorkSpaces Pools](active-directory-prerequisites.md) + [Certificate-Based Authentication](pools-certificate-based-authentication.md) + [WorkSpaces Pools Active Directory Administration](active-directory-admin.md) + [More Info](active-directory-more-info.md) # Overview of Active Directory Domains Using Active Directory domains with WorkSpaces Pools requires an understanding of how they work together and the configuration tasks that you'll need to complete. You'll need to complete the following tasks: 1. Configure Group Policy settings as needed to define the end user experience and security requirements for applications. 1. Create the domain-joined directory in WorkSpaces Pools. 1. Create the WorkSpaces Pools application in the SAML 2.0 identity provider and assign it to end users either directly or through Active Directory groups. **User Authentication Flow** 1. The user browses to `https://applications.exampleco.com`. The sign-on page requests authentication for the user. 1. The federation service requests authentication from the organization's identity store. 1. The identity store authenticates the user and returns the authentication response to the federation service. 1. On successful authentication, the federation service posts the SAML assertion to the user's browser. 1. The user's browser posts the SAML assertion to the AWS Sign-In SAML endpoint (`https://signin.aws.amazon.com/saml`). AWS Sign-In receives the SAML request, processes the request, authenticates the user, and forwards the authentication token to the WorkSpaces Pools service. 1. Using the authentication token from AWS, WorkSpaces Pools authorizes the user and presents applications to the browser. 1. The user chooses an application and, depending on the Windows login authentication method that is enabled on the WorkSpaces Pools directory, they're prompted to enter their Active Directory domain password or choose a smart card. If both authentication methods are enabled, the user can choose whether to enter their domain password or use their smart card. Certificate-based authentication can also be used to authenticate users, removing the prompt. 1. The domain controller is contacted for user authentication. 1. After being authenticated with the domain, the user's session starts with domain connectivity. From the user's perspective, this process is transparent. The user starts by navigating to your organization's internal portal and is redirected to a WorkSpaces Pools portal, without having to enter AWS credentials. Only an Active Directory domain password or smart card credentials are required. Before a user can initiate this process, you must configure Active Directory with the required entitlements and Group Policy settings and create a domain-joined WorkSpaces Pools directory. # Before You Begin Using Active Directory with WorkSpaces Pools Before you use Microsoft Active Directory domains with WorkSpaces Pools, be aware of the following requirements and considerations. **Topics** + [Active Directory Domain Environment](#active-directory-prerequisites-domain-environment) + [Domain-Joined WorkSpaces in WorkSpaces Pools](#active-directory-prerequisites-streaming-instances) + [Group Policy Settings](#active-directory-prerequisites-group-policy-settings) + [Smart Card Authentication](#active-directory-prerequisites-smart-card-authentication) ## Active Directory Domain Environment + You must have a Microsoft Active Directory domain to which to join your WorkSpaces. If you don't have an Active Directory domain or you want to use your on-premises Active Directory environment, see [Active Directory Domain Services on the AWS Cloud: Quick Start Reference Deployment](https://docs.aws.amazon.com/quickstart/latest/active-directory-ds/). + You must have a domain service account with permissions to create and manage computer objects in the domain that you intend to use with WorkSpaces Pools. For information, see [How to Create a Domain Account in Active Directory](https://msdn.microsoft.com/en-us/library/aa545262(v=cs.70).aspx) in the Microsoft documentation. When you associate this Active Directory domain with WorkSpaces Pools, provide the service account name and password. WorkSpaces Pools uses this account to create and manage computer objects in the directory. For more information, see [Granting Permissions to Create and Manage Active Directory Computer Objects](active-directory-admin.md#active-directory-permissions). + When you register your Active Directory domain with WorkSpaces Pools, you must provide an organizational unit (OU) distinguished name. Create an OU for this purpose. The default Computers container is not an OU and cannot be used by WorkSpaces Pools. For more information, see [Finding the Organizational Unit Distinguished Name](active-directory-admin.md#active-directory-oudn). + The directories that you plan to use with WorkSpaces Pools must be accessible through their fully qualified domain names (FQDNs) through the virtual private cloud (VPC) in which your WorkSpaces are launched. For more information, see [Active Directory and Active Directory Domain Services Port Requirements](https://technet.microsoft.com/en-us/library/dd772723.aspx) in the Microsoft documentation. ## Domain-Joined WorkSpaces in WorkSpaces Pools SAML 2.0-based user federation is required for application streaming from domain-joined WorkSpaces. Also, you must use a Windows image that supports joining to an Active Directory domain. All public images published on or after July 24, 2017 support joining an Active Directory domain. ## Group Policy Settings Verify your configuration for the following Group Policy settings. If required, update the settings as described in this section so that they don't block WorkSpaces Pools from authenticating and logging in your domain users. Otherwise, when your users try to log in to WorkSpaces the login may not succeed. Instead, a message displays, notifying users that "An unknown error occurred." + **Computer Configuration > Administrative Templates > Windows Components > Windows Logon Options > Disable or Enable software Secure Attention Sequence** — Set this to **Enabled** for **Services**. + **Computer Configuration > Administrative Templates > System > Logon > Exclude credential providers** — Ensure that the following CLSID is *not* listed: `e7c1bab5-4b49-4e64-a966-8d99686f8c7c` + **Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Security Options > Interactive Logon > Interactive Logon: Message text for users attempting to log on** — Set this to **Not defined**. + **Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Security Options > Interactive Logon > Interactive Logon: Message title for users attempting to log on** — Set this to **Not defined**. ## Smart Card Authentication WorkSpaces Pools supports the use of Active Directory domain passwords or smart cards such as [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card) and [Personal Identity Verification (PIV)](https://piv.idmanagement.gov/) smart cards for Windows sign in to WorkSpaces in WorkSpaces Pools. For information about how to configure your Active Directory environment to enable smart card sign in by using third-party certification authorities (CAs), see [Guidelines for enabling smart card logon with third-party certification authorities](https://docs.microsoft.com/en-us/troubleshoot/windows-server/windows-security/enabling-smart-card-logon-third-party-certification-authorities) in the Microsoft documentation. # Certificate-Based Authentication You can use certificate-based authentication with WorkSpaces Pools joined to Microsoft Active Directory. This removes the user prompt for the Active Directory domain password when a user logs in. 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. + Create 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 Certificate Authority (AWS Private CA) resources in your AWS account. With AWS Private CA, you can create private certificate authority (CA) hierarchies, including root and subordinate CAs. You can also create your own CA hierarchy and issue certificates from it that authenticate internal users. For more information, see [What is AWS Private CA](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html). When you use AWS Private CA for certificate-based authentication, WorkSpaces Pools requests certificates for your users automatically at session reservation for each WorkSpace in a WorkSpaces Pool. It authenticates users to Active Directory with a virtual smart card provisioned with the certificates. Certificate-based authentication is supported on domain-joined WorkSpaces Pools that run Windows instances. **Topics** + [Prerequisites](certificate-based-authentication-prereq.md) + [Enable Certificate-based Authentication](certificate-based-authentication-enable.md) + [Manage Certificate-based Authentication](certificate-based-authentication-manage.md) + [Enable Cross-account PCA Sharing](pca-sharing.md) # Prerequisites Complete the following steps before you use certificate-based authentication. 1. Configure your WorkSpaces Pools directory with SAML 2.0 integration to use certificate-based authentication. For more information, see [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md). **Note** Don't enable **Smart card sign in** in your pool directory if you want to use certificate-based authentication. 1. Configure the `userPrincipalName` attribute in your SAML assertion. For more information, see [Step 7: Create assertions for the SAML authentication response](create-directory-pools.md#saml-directory-create-assertions). 1. Configure the `ObjectSid` attribute in your SAML assertion. You can use this attribute to perform strong mapping with the Active Directory user. Certificate-based authentication fails if the `ObjectSid` attribute doesn't match the Active Directory security identifier (SID) for the user specified in the SAML\$1Subject `NameID`. For more information, see [Step 7: Create assertions for the SAML authentication response](create-directory-pools.md#saml-directory-create-assertions). **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` permission to the IAM role trust policy that you use with your SAML 2.0 configuration. For more information, see [Passing session tags in AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html.html) in the *AWS Identity and Access Management User Guide*. This permission is required to use certificate-based authentication. For more information, see [Step 5: Create a SAML 2.0 federation IAM role](create-directory-pools.md#saml-directory-saml-federation-role-in-iam). 1. Create a private certificate authority (CA) using AWS Private CA, if you don't 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) in the *AWS Private Certificate Authority User Guide*. The following AWS Private CA settings are common for many certificate-based authentication use cases: + **CA type options** + **Short-lived certificate CA usage mode** – Recommended if the CA only issues end user certificates for certificate-based authentication. + **Single level hierarchy with a Root CA** – Choose a subordinate CA to integrate it with an existing CA hierarchy. + **Key algorithm options** – RSA 2048 + **Subject distinguished name options** – Use the most appropriate options to identify this CA in your Active Directory Trusted Root Certification Authorities store. + **Certificate revocation options** – CRL distribution **Note** Certificate-based authentication requires an online CRL distribution point accessible from both the WorkSpaces in WorkSpaces Pools and the domain controller. This requires unauthenticated access to the Amazon S3 bucket configured for AWS Private CA CRL entries, or a CloudFront distribution with access to the Amazon S3 bucket if it blocks public access. For more information about these options, see [Planning a certificate revocation list (CRL)](https://docs.aws.amazon.com/privateca/latest/userguide/crl-planning.html) in the *AWS Private Certificate Authority User Guide*. 1. Tag your private CA with a key entitled `euc-private-ca` to designate the CA for use with WorkSpaces Pools certificate-based authentication. This key doesn't require a value. For more information, see [Managing tags for your private CA](https://docs.aws.amazon.com/privateca/latest/userguide/PcaCaTagging.html) in the *AWS Private Certificate Authority User Guide*.. 1. Certificate-based authentication uses virtual smart cards to log on. For more information, see [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). Follow these steps: 1. 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, it automatically enrolls domain controllers with certificates that 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 use AWS Managed Microsoft AD, you can configure Certificate Services on an Amazon EC2 instance that satisfies the requirement for domain controller certificates. See [Deploy Active Directory to a new Amazon Virtual Private Cloud](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. With AWS Managed Microsoft AD and Active Directory Certificate Services, you must also create outbound rules from the controller's VPC security group to the Amazon EC2 instance running Certificate Services. You must provide the security group access to TCP port 135, and ports 49152 through 65535 to enable certificate auto-enrollment. The Amazon EC2 instance must also allow inbound access on these 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). 1. On the AWS Private CA console, or with the SDK or CLI, export the private CA certificate. For more information, see [Exporting a private certificate](https://docs.aws.amazon.com/acm/latest/userguide/export-private.html). 1. Publish the private CA to Active Directory. Log on to a domain controller or a domain-joined machine. Copy the private CA certificate to any `\` and run the following commands as a domain administrator. You can also use Group Policy and the Microsoft PKI Health Tool (PKIView) 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 \ RootCA ``` ``` certutil -dspublish -f \ NTAuthCA ``` Make sure that the commands complete successfully, then remove the private CA certificate file. Depending on your Active Directory replication settings, it can take several minutes for the CA to publish to your domain controllers and WorkSpaces in WorkSpaces Pools. **Note** Active Directory must distribute the CA to the Trusted Root Certification Authorities and Enterprise NTAuth stores automatically for WorkSpaces in WorkSpaces Pools when they join the domain. **Note** Active Directory domain controllers must be in Compatibility mode for certificate strong enforcement to support certificate-based authentication. For more information, see [KB5014754—Certificate-based authentication changes on Windows domain controllers](https://support.microsoft.com/en-us/topic/kb5014754-certificate-based-authentication-changes-on-windows-domain-controllers-ad2c23b0-15d8-4340-a468-4d4f3b188f16) in the Microsoft Support documentation. If you are using AWS Managed Microsoft AD, see [Configure directory security settings](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_directory_settings.html) for more information. # Enable Certificate-based Authentication Complete the following steps to enable certificate-based authentication. **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. Choose **Directories** in the navigation pane. 1. Choose the **Pools directories** tab. 1. Choose the directory you want to configure. 1. Choose **Edit** in the **Authentication** section of the page. 1. Choose **Edit Certificate-Based Authentication** in the **Certificate-Based Authentication** section of the page. 1. Choose **Enable Certificate-Based Authentication**. 1. Choose the certificate in the **AWS Certificate Manager (ACM) Private Certificate Authority (CA)** drop-down. To appear in the drop-down, you should store the private CA in the same AWS account and AWS Region. You must also tag the private CA with a key named `euc-private-ca`. 1. Configure directory log in fallback. With Fallback, users can log in with their AD domain password if certificate-based authentication is unsuccessful. This is recommended only in cases where users know their domain passwords. When fallback is turned off, a session can disconnect the user if a lock screen or Windows log off occurs. If fallback is turned on, the session prompts the user for their AD domain password. 1. Choose **Save**. Certificate-based authentication is now enabled. When users authenticate with SAML 2.0 to an WorkSpaces Pools directory using the domain-joined WorkSpaces, they will no longer receive a prompt for the domain password. Users will see a **Connecting with certificate-based authentication** message when connecting to a session enabled for certificate-based authentication. # Manage Certificate-based Authentication After you enable certificate-based authentication, review the following tasks. ## Private CA Certificate In a typical configuration, the private CA certificate has a validity period of 10 years. For more information about replacing a private CA with an expired certificate, or reissuing the private CA with a new validity period, see [Managing the private CA lifecycle ](https://docs.aws.amazon.com/privateca/latest/userguide/ca-lifecycle.html) ## End User Certificates End user certificates issued by AWS Private Certificate Authority for WorkSpaces Pools certificate-based authentication don't require renewal or revocation. These certificates are short-lived. WorkSpaces Pools automatically issues a new certificate for each new session, or every 24 hours for sessions with a long duration. The WorkSpaces Pools session governs the use of these end user certificates. If you end a session, WorkSpaces Pools stops using that certificate. These end user certificates have a shorter validity period than a typical AWS Private Certificate Authority 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 CloudTrail to record API calls to a private CA by WorkSpaces Pools. For more information see [What Is AWS CloudTrail?](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) in the *AWS CloudTrail User Guide*, and [Using CloudTrail](https://docs.aws.amazon.com/privateca/latest/userguide/PcaCtIntro.html) in the *AWS Private Certificate Authority User Guide*. In CloudTrail Event history you can view **GetCertificate** and **IssueCertificate** event names from **acm-pca.amazonaws.com** event source made by the WorkSpaces Pools **EcmAssumeRoleSession** user name. These events will be recorded for every WorkSpaces Pools certificate-based authentication request. For more information, see [Viewing events with CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*. # Enable Cross-account PCA Sharing Private CA (PCA) cross-account sharing offers the ability to grant permissions for other accounts to use a centralized CA. The CA can generate and issue certificates by using [AWS Resource Access Manager](https://aws.amazon.com/ram/) (RAM) to manage the permissions. This removes the need for a Private CA in every account. Private CA cross-account sharing can be used with WorkSpaces Applications certificate-based Authentication (CBA) within the same AWS Region. To use a shared Private CA resource with WorkSpaces Pools CBA, complete the following steps: 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.md). 1. Share the Private CA with the resource AWS accounts where WorkSpaces Pools resources utilize CBA. To do this, follow 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 do not 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. If you share with individual accounts, you need to accept the shared Private CA in your resource account by using the AWS Resource Access Manager console or APIs. When configuring the share, confirm that the AWS Resource Access Manager 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 Pools service role when issuing CBA certificates. 1. After the share is successful, 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 Pools directory. At this time, the WorkSpaces Pools console does not support selection of shared Private CA ARNs. For more information, see the [Amazon WorkSpaces Service API Reference](https://docs.aws.amazon.com/workspaces/latest/api/welcome.html). # WorkSpaces Pools Active Directory Administration Setting up and using Active Directory with WorkSpaces Pools involves the following administrative tasks. **Topics** + [Granting Permissions to Create and Manage Active Directory Computer Objects](#active-directory-permissions) + [Finding the Organizational Unit Distinguished Name](#active-directory-oudn) + [Granting Local Administrator Rights on custom images](#active-directory-image-builder-local-admin) + [Locking the Streaming Session When the User is Idle](#active-directory-session-lock) + [Configuring WorkSpaces Pools to Use Domain Trusts](#active-directory-domain-trusts) ## Granting Permissions to Create and Manage Active Directory Computer Objects To allow WorkSpaces Pools to perform Active Directory computer object operations, you need an account with sufficient permissions. As a best practice, use an account that has only the minimum privileges necessary. The minimum Active Directory organizational unit (OU) permissions are as follows: + Create Computer Object + Change Password + Reset Password + Write Description Before setting up permissions, you'll need to do the following first: + Obtain access to a computer or an EC2 instance that is joined to your domain. + Install the Active Directory User and Computers MMC snap-in. For more information, see [Installing or Removing Remote Server Administration Tools for Windows 7](https://technet.microsoft.com/en-us/library/ee449483.aspx) in the Microsoft documentation. + Log in as a domain user with appropriate permissions to modify the OU security settings. + Create or identify the user, service account, or group for which to delegate permissions. **To set up minimum permissions** 1. Open **Active Directory Users and Computers** in your domain or on your domain controller. 1. In the left navigation pane, select the first OU on which to provide domain join privileges, open the context (right-click) menu , and then choose **Delegate Control**. 1. On the **Delegation of Control Wizard** page, choose **Next**, **Add**. 1. For **Select Users, Computers, or Groups**, select the pre-created user, service account, or group, and then choose **OK**. 1. On the **Tasks to Delegate** page, choose **Create a custom task to delegate**, and then choose **Next**. 1. Choose **Only the following objects in the folder**, **Computer objects**. 1. Choose **Create selected objects in this folder**, **Next**. 1. For **Permissions**, choose **Read**, **Write**, **Change Password**, **Reset Password**, **Next**. 1. On the **Completing the Delegation of Control Wizard** page, verify the information and choose **Finish**. 1. Repeat steps 2-9 for any additional OUs that require these permissions. If you delegated permissions to a group, create a user or service account with a strong password and add that account to the group. This account will then have sufficient privileges to connect your WorkSpaces to the directory. Use this account when creating your WorkSpaces Pools directory configuration. ## Finding the Organizational Unit Distinguished Name When you register your Active Directory domain with WorkSpaces Pools, you must provide an organizational unit (OU) distinguished name. Create an OU for this purpose. The default Computers container is not an OU and cannot be used by WorkSpaces Pools. The following procedure shows how to obtain this name. **Note** The distinguished name must start with **OU=** or it cannot be used for computer objects. Before you complete this procedure, you'll need to do the following first: + Obtain access to a computer or an EC2 instance that is joined to your domain. + Install the Active Directory User and Computers MMC snap-in. For more information, see [Installing or Removing Remote Server Administration Tools for Windows 7](https://technet.microsoft.com/en-us/library/ee449483.aspx) in the Microsoft documentation. + Log in as a domain user with appropriate permissions to read the OU security properties. **To find the distinguished name of an OU** 1. Open **Active Directory Users and Computers** in your domain or on your domain controller. 1. Under **View**, ensure that **Advanced Features** is enabled. 1. In the left navigation pane, select the first OU to use for WorkSpaces computer objects, open the context (right-click) menu, and then choose **Properties**. 1. Choose **Attribute Editor**. 1. Under **Attributes**, for **distinguishedName**, choose **View**. 1. For **Value**, select the distinguished name, open the context menu, and then choose **Copy**. ## Granting Local Administrator Rights on custom images By default, Active Directory domain users do not have local administrator rights on images. You can grant these rights by using Group Policy preferences in your directory, or manually, by using the local administrator account on an image. Granting local administrator rights to a domain user allows that user to install applications on and create custom images in WorkSpaces Pools. **Topics** + [Using Group Policy preferences](#group-policy) + [Using the local Administrators group on the WorkSpace to create images](#manual-procedure) ### Using Group Policy preferences You can use Group Policy preferences to grant local administrator rights to Active Directory users or groups and to all computer objects in the specified OU. The Active Directory users or groups to which you want to grant local administrator permissions must already exist. To use Group Policy preferences, you'll need to do the following first: + Obtain access to a computer or an EC2 instance that is joined to your domain. + Install the Group Policy Management Console (GPMC) MMC snap-in. For more information, see [Installing or Removing Remote Server Administration Tools for Windows 7](https://technet.microsoft.com/en-us/library/ee449483.aspx) in the Microsoft documentation. + Log in as a domain user with permissions to create Group Policy objects (GPOs). Link GPOs to the appropriate OUs. **To use Group Policy preferences to grant local administrator permissions** 1. In your directory or on a domain controller, open the command prompt as an administrator, type `gpmc.msc`, and then press ENTER. 1. In the left console tree, select the OU where you will create a new GPO or use an existing GPO, and then do either of the following: + Create a new GPO by opening the context (right-click) menu and choosing **Create a GPO in this domain, Link it here**. For **Name**, provide a descriptive name for this GPO. + Select an existing GPO. 1. Open the context menu for the GPO, and choose **Edit**. 1. In the console tree, choose **Computer Configuration**, **Preferences**, **Windows Settings**, **Control Panel Settings**, and **Local Users and Groups**. 1. Select **Local Users and Groups** selected, open the context menu , and choose **New**, **Local Group**. 1. For **Action**, choose **Update**. 1. For **Group name**, choose **Administrators (built-in)**. 1. Under **Members**, choose **Add…** and specify the Active Directory users or groups to which to assign local administrator rights on the streaming instance. For **Action**, choose **Add to this group**, and choose **OK**. 1. To apply this GPO to other OUs, select the additional OU, open the context menu and choose **Link an Existing GPO**. 1. Using the new or existing GPO name that you specified in step 2, scroll to find the GPO, and then choose **OK**. 1. Repeat steps 9 and 10 for additional OUs that should have this preference. 1. Choose **OK** to close the **New Local Group Properties** dialog box. 1. Choose **OK** again to close the GPMC. To apply the new preference to the GPO, you must stop and restart any running image builders or fleets. The Active Directory users and groups that you specified in step 8 are automatically granted local administrator rights on the image builders and fleets in the OU to which the GPO is linked. ### Using the local Administrators group on the WorkSpace to create images To grant Active Directory users or groups local administrator rights on an image, you can manually add these users or groups to the local Administrators group on the image. The Active Directory users or groups to which to grant local administrator rights must already exist. 1. Connect to the WorkSpace you use to build images. The WorkSpace must be running and domain-joined. 1. Choose **Start**, **Administrative Tools**, and then double-click **Computer Management**. 1. In the left navigation pane, choose **Local Users and Groups** and open the **Groups** folder. 1. Open the **Administrators** group and choose **Add...**. 1. Select all Active Directory users or groups to which to assign local administrator rights and choose **OK**. Choose **OK** again to close the **Administrator Properties** dialog box. 1. Close Computer Management. 1. To log in as an Active Directory user and test whether that user has local administrator rights on the WorkSpaces, choose **Admin Commands**, **Switch user**, and then enter the credentials of the relevant user. ## Locking the Streaming Session When the User is Idle WorkSpaces Pools relies on a setting that you configure in the GPMC to lock the streaming session after your user is idle for specified amount of time. To use the GPMC, you'll need to do the following first: + Obtain access to a computer or an EC2 instance that is joined to your domain. + Install the GPMC. For more information, see [Installing or Removing Remote Server Administration Tools for Windows 7](https://technet.microsoft.com/en-us/library/ee449483.aspx) in the Microsoft documentation. + Log in as a domain user with permissions to create GPOs. Link GPOs to the appropriate OUs. **To automatically lock the streaming instance when your user is idle** 1. In your directory or on a domain controller, open the command prompt as an administrator, type `gpmc.msc`, and then press ENTER. 1. In the left console tree, select the OU where you will create a new GPO or use an existing GPO, and then do either of the following: + Create a new GPO by opening the context (right-click) menu and choosing **Create a GPO in this domain, Link it here**. For **Name**, provide a descriptive name for this GPO. + Select an existing GPO. 1. Open the context menu for the GPO, and choose **Edit**. 1. Under **User Configuration**, expand **Policies**, **Administrative Templates**, **Control Panel**, and then choose **Personalization**. 1. Double-click **Enable screen saver**. 1. In the **Enable screen saver** policy setting, choose **Enabled**. 1. Choose **Apply**, and then choose **OK**. 1. Double-click **Force specific screen saver**. 1. In the **Force specific screen saver** policy setting, choose **Enabled**. 1. Under **Screen saver executable name**, enter **scrnsave.scr**. When this setting is enabled, the system displays a black screen saver on the user's desktop. 1. Choose **Apply**, and then choose **OK**. 1. Double-click **Password protect the screen saver**. 1. In the **Password protect the screen saver** policy setting, choose **Enabled**. 1. Choose **Apply**, and then choose **OK**. 1. Double-click **Screen saver timeout**. 1. In the **Screen saver timeout** policy setting, choose **Enabled**. 1. For **Seconds**, specify the length of time that users must be idle before the screen saver is applied. To set the idle time to 10 minutes, specify 600 seconds. 1. Choose **Apply**, and then choose **OK**. 1. In the console tree, under **User Configuration**, expand **Policies**, **Administrative Templates**, **System**, and then choose **Ctrl\$1Alt\$1Del Options**. 1. Double-click **Remove Lock Computer**. 1. In the **Remove Lock Computer** policy setting, choose **Disabled**. 1. Choose **Apply**, and then choose **OK**. ## Configuring WorkSpaces Pools to Use Domain Trusts WorkSpaces Pools supports Active Directory domain environments where network resources such as file servers, applications, and computer objects reside in one domain, and the user objects reside in another. The domain service account used for computer object operations does not need to be in the same domain as the WorkSpaces Pools computer objects. When creating the directory configuration, specify a service account that has the appropriate permissions to manage computer objects in the Active Directory domain where the file servers, applications, computer objects and other network resources reside. Your end user Active Directory accounts must have the "Allowed to Authenticate" permissions for the following: + WorkSpaces Pools computer objects + Domain controllers for the domain For more information, see [Granting Permissions to Create and Manage Active Directory Computer Objects](#active-directory-permissions). # More Info For more information related to this topic, see the following resources: + [Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html)—Information about using Directory Service. # Bundles and images for WorkSpaces Pools 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 WorkSpace and have customized it, you can create a custom image from that WorkSpace for use with WorkSpaces Pool. Linux are not supported in WorkSpaces Pool. 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 create new WorkSpaces Pools to ensure that the new WorkSpaces in the pool 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 Pools 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 2019 | Included | DCV | Value, Standard, Performance, Power, PowerPro | [January 9, 2029](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2019) | | Windows Server 2022 | Included | DCV | Standard, Performance, Power, PowerPro, Graphics.G4dn, GraphicsPro.G4dn | [October 14, 2031](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2022) | **Note** Operating system versions that are no longer supported by the vender are not guaranteed to work and are not supported by AWS support. **Topics** + [Bundle options for WorkSpaces Pools](pools-custom-images-bundles.md) + [Create a custom image and bundle for WorkSpaces Pools](pools-images-custom-image.md) + [Manage custom images and bundles for WorkSpaces Pools](pools-images-managing.md) + [Use session scripts to manage your users' streaming experience](pools-images-session-scripts.md) # Bundle options for WorkSpaces Pools Before selecting a bundle to use with WorkSpaces Pool, ensure the bundle you want to select is compatible with your WorkSpaces' protocol, operating system, network, and compute type. 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. For more information about protocols, see [Protocols for WorkSpaces Personal](amazon-workspaces-networking.md#amazon-workspaces-protocols). For more information about networks, see [Client network requirements for WorkSpaces Personal](workspaces-network-requirements.md). The following public bundles can be used with WorkSpaces Pool. For information about bundles in WorkSpaces, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles). Value, Standard, Performance, Power, PowerPro ## Value bundle 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 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 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 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 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 ## Graphics.g4dn bundle 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 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 image and bundle for WorkSpaces Pools WorkSpaces Pool supports Windows images and bundles only. If you've launched a Windows or 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. 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. **Important** Custom bundle storage volumes can't be smaller than image storage volumes. 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](#pools-windows_custom_image_requirements) + [Best practices](#pools-custom_image_best_practices) + [Step 1: Run the Image Checker](#pools-run_image_checker) + [Step 2: Create a custom image and custom bundle](#pools-create_custom_image_bundle) + [What's included with Windows WorkSpaces custom images](#pools-image_creation_windows) ## Requirements to create Windows custom images **Note** Windows currently defines 1 GB as 1,073,741,824 bytes. You must 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. + 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 + WorkSpaces Pools only supports a maximum bundle / image root volume size of 200 GB. When you create a Windows custom image, ensure it is under the root volume size of 200 GB. ## Best practices 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. + 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. + 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). ## Step 1: Run the Image Checker To confirm that your Windows WorkSpace meets the requirements for image creation, we recommend running the Image Checker application. 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. The Image Checker is available only for Windows WorkSpaces. **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](#pools-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`. Don't 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 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`. #### PowerShell version 3.0 or later must be installed 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. #### Only the C and D drives can be present Only the `C` and `D` drives can be present on a WorkSpace that's used for imaging. Remove all other drives, including virtual drives. #### No pending reboot due to Windows Updates can be detected + 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. #### The Sysprep file must exist and can't be blank 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. #### The user profile size must be less than 10 GB 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. #### Drive C must have enough free space 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. #### No services can be running under a domain account 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**. #### The WorkSpace must be configured to use DHCP 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. #### Remote Desktop Services must be enabled 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 user profile must exist 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. #### The environment variable path must be properly configured 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. #### Windows Modules Installer must be enabled 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**. #### Amazon SSM Agent must be disabled 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**. #### SSL3 and TLS version 1.2 must be enabled 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. #### Only one user profile can exist on the WorkSpace 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. #### No AppX packages can be in a staged state 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 ``` #### Windows must not have been upgraded from a previous version 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. #### The Windows rearm count must not be 0 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 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*" } ``` + 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 2: Create a custom image and custom bundle After you have validated your WorkSpace image, complete the following procedure to create your custom image and custom bundle using the WorkSpaces console. 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*. 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*. **To create a custom image and custom bundle using the WorkSpaces console** 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 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**. 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](create-custom-bundle.md#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. Don't use a dash (`-`) special character in the description. It will cause 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**. 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. + The default available size combinations for the root volume is 200 GB per WorkSpace. 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 When you create an image from a Windows WorkSpace, the entire contents of the `C` drive are included. + 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 # Manage custom images and bundles for WorkSpaces Pools The process to manage custom images and bundles is the same between WorkSpaces Personal and WorkSpaces Pool. For more information about how to manage images and bundles, refer to the following documentation within the WorkSpaces Personal section of this guide: **Note** The primary difference between custom bundles that you can use for WorkSpaces Personal and ones that you can use for WorkSpaces Pool is the operating system and base public bundle that can be used. For the operating systems and bundles that are supported in WorkSpaces Pool, see [ WorkSpaces Pools BundlesBundles Learn about WorkSpaces Pools bundles. 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). 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 | | --- | --- | --- | --- | | Windows Server 2019 | Included | DCV | Value, Standard, Performance, Power, PowerPro | | Windows Server 2022 | Included | DCV | Standard, Performance, Power, PowerPro, Graphics.G4dn, GraphicsPro.G4dn | Operating system versions that are no longer supported by the vender are not guaranteed to work and are not supported by AWS support. ](instance-types.md#instance-types.title). + [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). # Use session scripts to manage your users' streaming experience WorkSpaces Pool provides on-instance session scripts. You can use these scripts to run your own custom scripts when specific events occur in users' streaming sessions. For example, you can use custom scripts to prepare your WorkSpaces Pools environment before your users' streaming sessions begin. You can also use custom scripts to clean up streaming instances after users complete their streaming sessions. Session scripts are specified within a WorkSpace image. These scripts are run within the user context or the system context. If your session scripts use the standard out to write information, error, or debugging messaging, these can be optionally saved to an Amazon S3 bucket within your Amazon Web Services account. **Topics** + [Run Scripts Before Streaming Sessions Begin](#run-scripts-before-streaming-sessions-begin) + [Run Scripts After Streaming Sessions End](#run-scripts-after-streaming-sessions-end) + [Create and Specify Session Scripts](#create-specify-session-scripts) + [Session Scripts Configuration File](#session-script-configuration-file) + [Using Windows PowerShell Files](#using-powershell-files-with-session-scripts) + [Logging Session Script Output](#logging-session-output) + [Use persistent storage with session scripts](#use-storage-connectors-with-session-scripts) + [Enable Amazon S3 Bucket Storage for Session Script Logs](#enable-S3-bucket-storage-session-script-logs) ## Run Scripts Before Streaming Sessions Begin You can configure your scripts to run for a maximum of 60 seconds before your users' applications launch and their streaming sessions begin. Doing so enables you to customize the WorkSpaces Pools environment before users start streaming their applications. When the session scripts run, a loading spinner displays for your users. When your scripts complete successfully or the maximum waiting time elapses, your users' streaming session will begin. If your scripts don't complete successfully, an error message displays for your users. However, your users are not prevented from using their streaming session. When you specify a file name on a Windows instance, you must use a double backslash. For example: ``` C:\\Scripts\\Myscript.bat ``` If you don't use a double backslash, an error displays to notify you that the `.json` file is incorrectly formatted. **Note** When your scripts complete successfully, they must return a value of 0. If your scripts return a value other than 0, WorkSpaces displays the error message to the user. When you run scripts before streaming sessions begin, the following process occurs: 1. Your users connect to a WorkSpace in a WorkSpaces Pool that is not domain-joined. They connect by using SAML 2.0. 1. One of the following occurs: + If application settings persistence is enabled for your users, the application settings Virtual Hard Disk (VHD) file that stores your users' customizations and Windows settings is downloaded and mounted. Windows user login is required in this case. For information about application settings persistence, see [Enable application settings persistence for your WorkSpaces Pools users](app-settings-persistence.md). + If application settings persistence is not enabled, the Windows user is already logged in. 1. Your session scripts start. If persistent storage is enabled for your users, storage connector mounting also starts. For information about persistent storage, see [Enable and Administer Persistent Storage for WorkSpaces Pools](persistent-storage.md). **Note** The storage connector mount doesn't need to complete for the streaming session to start. If the session scripts complete before the storage connector mount completes, the streaming session starts. For information about monitoring the mount status of storage connectors, see [Use persistent storage with session scripts](#use-storage-connectors-with-session-scripts). 1. Your session scripts complete or time out. 1. The users' streaming session starts. ## Run Scripts After Streaming Sessions End You can also configure your scripts to run after users' streaming sessions end. For example, you can run a script when users select **End Session** from the WorkSpaces client toolbar, or when they reach the maximum allowed duration for the session. You can also use these session scripts to clean up your WorkSpaces environment before a streaming instance is terminated. For example, you can use scripts to release file locks or upload log files. When you run scripts after streaming sessions end, the following process occurs: 1. Your users' WorkSpaces streaming session ends. 1. Your session termination scripts start. 1. The session termination scripts complete or time out. 1. Windows user logout occurs. 1. One or both of the following occur in parallel, if applicable: + If application settings persistence is enabled for your users, the application settings VHD file that stores your users' customizations and Windows settings is unmounted and uploaded to an Amazon S3 bucket in your account. + If persistent storage is enabled for your users, the storage connector completes a final synchronization and is unmounted. 1. The WorkSpace is terminated. ## Create and Specify Session Scripts Complete the following procedure to create and specify session scripts for your WorkSpaces in a WorkSpaces Pool. 1. Connect to the Windows WorkSpaces from which you are creating a custom image. 1. Create the directory `/AWSEUC/SessionScripts` if it does not already exist. 1. Create a configuration file `/AWSEUC/SessionScripts/config.json` if it does not already exist, using the [Session Script Configuration template](https://docs.aws.amazon.com/workspaces/latest/adminguide/pools-images-session-scripts.html#session-script-configuration-file). 1. Navigate to `C:\AWSEUC\SessionScripts`, and open the `config.json` configuration file. For information about session script parameters, see [Session Scripts Configuration File](#session-script-configuration-file). 1. After you finish making your changes, save and close the `config.json` file. 1. Complete the steps to create an image from the WorkSpace. For more information, see [Create a custom image and bundle for WorkSpaces Pools](pools-images-custom-image.md). ## Session Scripts Configuration File To locate the session scripts configuration file in a Windows instance, navigate to `C:\AWSEUC\SessionScripts\config.json`. The file is formatted as follows. **Note** The configuration file is in JSON format. Verify that any text you type in this file is in valid JSON format. ``` { "SessionStart": { "executables": [ { "context": "system", "filename": "", "arguments": "", "s3LogEnabled": true }, { "context": "user", "filename": "", "arguments": "", "s3LogEnabled": true } ], "waitingTime": 30 }, "SessionTermination": { "executables": [ { "context": "system", "filename": "", "arguments": "", "s3LogEnabled": true }, { "context": "user", "filename": "", "arguments": "", "s3LogEnabled": true } ], "waitingTime": 30 } } ``` You can use the following parameters in the session scripts configuration file. **`SessionStart/SessionTermination `** The session scripts to run in the appropriate session event based on the name of the object. **Type**: String **Required**: No **Allowed values:** **SessionStart**, **SessionTermination** **`WaitingTime`** The maximum duration of the session scripts in seconds. **Type**: Integer **Required**: No **Constraints:** The maximum duration is 60 seconds. If the session scripts don't complete within this duration, they will be stopped. If you require a script to continue running, launch it as a separate process. **`Executables`** The details for the session scripts to run. **Type**: String **Required**: Yes **Constraints:** The maximum number of scripts that can run per session event is 2 (one for the user context, one for the system context). **`Context`** The context in which to run the session script. **Type**: String **Required**: Yes **Allowed values:** **user**, **system** **`Filename`** The full path to the session script to run. If this parameter is not specified, the session script is not run. **Type**: String **Required**: No **Constraints:** The maximum length for the file name and full path is 1,000 characters. **Allowed values:** **.bat**, **.exe**, **.sh** You can also use Windows PowerShell files. For more information, see [Using Windows PowerShell Files](#using-powershell-files-with-session-scripts). **`Arguments`** The arguments for your session script or executable file. **Type**: String **Required**: No **Length constraints:** The maximum length is 1,000 characters. **`S3LogEnabled`** When the value for this parameter is set to **True**, an S3 bucket is created within your Amazon Web Services account to store the logs created by the session script. By default, this value is set to **True**. For more information, see the *Logging Session Script Output* section later in this topic. **Type**: Boolean **Required**: No **Allowed values:** **True**, **False** ## Using Windows PowerShell Files To use Windows PowerShell files, specify the full path to the PowerShell file in the `filename` parameter: ``` "filename": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", ``` Then specify your session script in the **arguments** parameter: ``` "arguments": "-File \"C:\\path\\to\\session\\script.ps1\"", ``` Finally, verify that the PowerShell Execution Policy allows your PowerShell file to run. ## Logging Session Script Output When this option is enabled in the configuration file, WorkSpaces Pool automatically captures the output from the session script that is written to the standard out. This output is uploaded to an Amazon S3 bucket in your account. You can review the log files for troubleshooting or debugging purposes. **Note** The log files are uploaded when the session script returns a value, or the value set in **WaitingTime** has elapsed, whichever comes first. ## Use persistent storage with session scripts When WorkSpaces persistent storage is enabled, the storage begins mounting when the session start scripts run. If your script relies on persistent storage being mounted, you can wait for the connectors to be available. WorkSpaces maintains the mount status of the storage connectors in the Windows registry on Windows WorkSpaces, at the following key: ``` HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\AWSEUC\Storage\\ ``` The registry key values are as follows: + Provided user name — The user ID provided through the access mode. The access modes and value for each mode are as follows: + User Pool — The email address for the user + Streaming URL — The UserID + SAML — The NameID. If the user name includes a slash (for example, a domain user’s SAMAccountName), the slash is replaced by a "-" character. + Storage connector — The connector for the persistent storage option that is enabled for the user. The storage connector values are as follows: + HomeFolder Each storage connector registry key contains a **MountStatus** DWORD value. The following table lists the possible values for **MountStatus**. **Note** To view these registry keys, you must have Microsoft .NET Framework version 4.7.2 or later installed on your image. | Value | Description | | --- | --- | | 0 | Storage connector not be enabled for this user | | 1 | Storage connector mounting is in progress | | 2 | Storage connector mounted successfully | | 3 | Storage connector mounting failed | | 4 | Storage connector mounting is enabled, but not mounted yet | ## Enable Amazon S3 Bucket Storage for Session Script Logs When you enable Amazon S3 logging in your session script configuration, WorkSpaces Pool captures standard output from your session script. The output is periodically uploaded to an S3 bucket within your Amazon Web Services account. For every AWS Region, WorkSpaces Pool creates a bucket in your account that is unique to your account and the Region. You do not need to perform any configuration tasks to manage these S3 buckets. They are fully managed by the WorkSpaces service. The log files that are stored in each bucket are encrypted in transit using Amazon S3's SSL endpoints and at rest using Amazon S3-managed encryption keys. The buckets are named in a specific format as follows: ``` wspool-logs---random-identifier ``` **``** This is the AWS Region code in which the WorkSpaces Pool is created with Amazon S3 bucket storage enabled for session script logs. **``** Your Amazon Web Services account identifier. The random ID ensures that there is no conflict with other buckets in that Region. The first part of the bucket name, `wspool-logs`, does not change across accounts or Regions. For example, if you specify session scripts in an image in the US West (Oregon) Region (`us-west-2`) on account number `123456789012`, WorkSpaces Pool creates an Amazon S3 bucket within your account in that Region with the name shown. Only an administrator with sufficient permissions can delete this bucket. ``` wspool-logs-us-west-2-1234567890123-abcdefg ``` Disabling session scripts does not delete log files stored in the S3 bucket. To permanently delete log files, you or another administrator with adequate permissions must do so by using the Amazon S3 console or API. WorkSpaces Pools adds a bucket policy that prevents accidental deletion of the bucket. When session scripts are enabled, a unique folder is created for each streaming session that is started. The path for the folder where the log files are stored in the S3 bucket in your account uses the following structure: ``` //////SessionScriptsLogs/ ``` ****** The name of the S3 bucket in which the session scripts are stored. The name format is described earlier in this section. ****** The name of the stack the session came from. ****** The name of the WorkSpaces Pool the session script is running on. ****** The identity method of the user: `custom` for the WorkSpaces API or CLI, `federated` for SAML, and `userpool` for users in the user pool. ****** The user-specific folder name. This name is created using a lowercase SHA-256 hash hexadecimal string generated from the user identifier. ****** The identifier of the user's streaming session. Each user streaming session generates a unique ID. ****** The event that generated the session script log. The event values are: `SessionStart` and `SessionTermination`. The following example folder structure applies to a streaming session started from the test-stack and test-fleet. The session uses the API of user ID `testuser@mydomain.com`, from an AWS account ID of `123456789012`, and the settings group `test-stack` in the US West (Oregon) Region (`us-west-2`): ``` wspool-logs-us-west-2-1234567890123-abcdefg/test-stack/test-fleet/custom/a0bcb1da11f480d9b5b3e90f91243143eac04cfccfbdc777e740fab628a1cd13/05yd1391-4805-3da6-f498-76f5x6746016/SessionScriptsLogs/SessionStart/ ``` This example folder structure contains one log file for a user context session start script, and one log file for a system context session start script, if applicable. # Monitoring WorkSpaces Pools Monitoring is an important part of maintaining the reliability, availability, and performance of your WorkSpaces Pools. **Topics** + [WorkSpaces Pools metrics and dimensions](monitoring-with-cloudwatch.md) # WorkSpaces Pools metrics and dimensions Amazon WorkSpaces sends the following WorkSpaces Pools metrics and dimension information to Amazon CloudWatch. WorkSpaces Pools sends metrics to CloudWatch one time every minute. The `AWS/Workspaces` namespace includes the following metrics. ## Pools usage metrics | Metric | Description | | --- | --- | | ActiveUserSessionCapacity | The number of user sessions currently being used for streaming sessions. Units: Count Valid statistics: Average, Minimum, Maximum | | ActualUserSessionCapacity | The total number of pool sessions that are available for streaming or are currently streaming. 
ActualUserSessionCapacity = AvailableUserSessionCapacity + ActiveUserSessionCapacity
Units: Count Valid statistics: Average, Minimum, Maximum | | AvailableUserSessionCapacity | The number of idle pool sessions currently available for user streaming. 
AvailableUserSessionCapacity = ActualUserSessionCapacity - ActiveUserSessionCapacity
Units: Count Valid statistics: Average, Minimum, Maximum | | PendingUserSessionCapacity | The number of sessions being provisioned for your pool. Represents the additional number of streaming sessions the pool can support after provisioning is complete. Units: Count Valid statistics: Average, Minimum, Maximum | | UserSessionsCapacityUtilization | The percentage of sessions in a pool that are being used, using the following formula. 
UserSessionCapacityUtilization = (ActiveUserSessionCapacity / ActualUserSessionCapacity) * 100
Monitoring this metric helps with decisions about increasing or decreasing the value of a pool's desired capacity. Units: Percent Valid statistics: Average, Minimum, Maximum | | DesiredUserSessionCapacity | The total number of sessions that are either running or pending. This represents the total number of concurrent streaming sessions your pool can support in a steady state. 
DesiredUserSessionCapacity = ActualUserSessionCapacity + PendingUserSessionCapacity
Units: Count Valid statistics: Average, Minimum, Maximum | | InsufficientCapacityError | The number of session requests rejected due to lack of capacity. You can set alarms to use this metric to be notified of users waiting for streaming sessions. Units: Count Valid statistics: Average, Minimum, Maximum, Sum | # Enable and Administer Persistent Storage for WorkSpaces Pools WorkSpaces Pools supports home folders for persistent storage. As a WorkSpaces Pools administrator, you must understand how to perform the following tasks to enable and administer persistent storage for your users. **Topics** + [Enable and Administer Home Folders for Your WorkSpaces Pools Users](#home-folders) ## Enable and Administer Home Folders for Your WorkSpaces Pools Users When you enable home folders for WorkSpaces Pools, users can access a persistent storage folder during their streaming sessions. No further configuration is required for your users to access their home folder. Data stored by users in their home folder is automatically backed up to an Amazon Simple Storage Service bucket in your Amazon Web Services account and is made available to those users in subsequent sessions. Files and folders are encrypted in transit using Amazon S3's SSL endpoints. Files and folders are encrypted at rest using Amazon S3-managed encryption keys. Home folders are stored on WorkSpaces in WorkSpaces Pools in the following default locations: + For single-session, non-domain-joined Windows WorkSpaces: `C:\Users\PhotonUser\My Files\Home Folder` + Domain-joined Windows WorkSpaces: `C:\Users\%username%\My Files\Home Folder` As an administrator, use the applicable path if you configure your applications to save to the home folder. In some cases, your users may not be able to find their home folder because some applications do not recognize the redirect that displays the home folder as a top-level folder in File Explorer. If this is the case, your users can access their home folder by browsing to the same directory in File Explorer. **Topics** + [Files and Directories Associated with Compute-Intensive Applications](#storage-solutions-files-directories-associated-with-compute-intensive-applications) + [Enable Home Folders for Your WorkSpaces Pools Users](#enable-home-folders) + [Administer Your Home Folders](#home-folders-admin) ### Files and Directories Associated with Compute-Intensive Applications During WorkSpaces Pools streaming sessions, saving large files and directories associated with compute-intensive applications to persistent storage can take longer than saving files and directories required for basic productivity applications. For example, it might take longer for applications to save a large amount of data or frequently modify the same files than it would to save files created by applications that perform a single write action. It might also take longer to save many small files. If your users save files and directories associated with compute-intensive applications and WorkSpaces Pools persistent storage options aren't performing as expected, we recommend that you use a Server Message Block (SMB) solution such as Amazon FSx for Windows File Server or an AWS Storage Gateway file gateway. Following are examples of files and directories associated with compute-intensive applications that are more suitable for use with these SMB solutions: + Workspace folders for integrated development environments (IDEs) + Local database files + Scratch space folders created by graphics simulation applications For more information, see [File gateways](https://docs.aws.amazon.com/storagegateway/latest/userguide/StorageGatewayConcepts.html#file-gateway-concepts) in the *AWS Storage Gateway User Guide*. ### Enable Home Folders for Your WorkSpaces Pools Users Before enabling home folders, you must do the following: + Check that you have the correct AWS Identity and Access Management (IAM) permissions for Amazon S3 actions. + Use an image that was created from an AWS base image released on or after May 18, 2017. + Enable network connectivity to Amazon S3 from your virtual private cloud (VPC) by configuring internet access or a VPC endpoint for Amazon S3. For more information, see [Networking and Access for WorkSpaces Pools](managing-network.md) and [Using Amazon S3 VPC Endpoints for WorkSpaces Pools Features](managing-network-vpce-iam-policy.md). You can enable or disable home folders while creating a directory (see [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md)), or after the directory is created by using the AWS Management Console for WorkSpaces Pools. For each AWS Region, home folders are backed up by an Amazon S3 bucket. The first time you enable home folders for an WorkSpaces Pools directory in an AWS Region, the service creates an Amazon S3 bucket in your account in that same Region. The same bucket is used to store the content of home folders for all users and all directories in that Region. For more information, see [Amazon S3 Bucket Storage](#home-folders-s3). **To enable home folders while creating a directory** + Follow the steps in [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md), and make sure that **Enable Home Folders** is selected. **To enable home folders for an existing 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 left navigation pane, choose **Directories**, and select the directory for which to enable home folders. 1. Below the directories list, choose **Storage** and select **Enable Home Folders**. 1. In the **Enable Home Folders** dialog box, choose **Enable**. ### Administer Your Home Folders **Topics** + [Disable Home Folders](#home-folders-admin-disabling) + [Amazon S3 Bucket Storage](#home-folders-s3) + [Home Folder Content Synchronization](#home-folders-content-synchronization) + [Home Folder Formats](#home-folders-admin-folders) + [Additional Resources](#home-folders-admin-additional) #### Disable Home Folders You can disable home folders for a directory without losing user content already stored in home folders. Disabling home folders for a directory has the following effects: + Users who are connected to active streaming sessions for the directory receive an error message. They are informed that they can no longer store content in their home folder. + Home folders do not appear for any new sessions that use the directory with home folders disabled. + Disabling home folders for one directory does not disable it for other directories. + Even if home folders are disabled for all directories, WorkSpaces Pools does not delete the user content. To restore access to home folders for the directory, enable home folders again by following the steps described earlier in this topic. **To disable home folders while creating a directory** + Follow the steps in [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md) and make sure that the **Enable Home Folders** option is cleared. **To disable home folders for an existing 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 left navigation pane, choose **Directories**, and select the directory for which to enable home folders. 1. Below the directories list, choose **Storage** and clear **Enable Home Folders**. 1. In the **Disable Home Folders** dialog box, type `CONFIRM` (case-sensitive) to confirm your choice, then choose **Disable**. #### Amazon S3 Bucket Storage WorkSpaces Pools manages user content stored in home folders by using Amazon S3 buckets created in your account. For every AWS Region, WorkSpaces Pools creates a bucket in your account. All user content generated from streaming sessions of directories in that Region is stored in that bucket. The buckets are fully managed by the service without any input or configuration from an administrator. The buckets are named in a specific format as follows: ``` wspool-home-folder--- ``` Where `` is the AWS Region code in which the directory is created and `` is your Amazon Web Services account ID, and *>random-identifier<* is a random identifier number generated by the WorkSpaces service. The first part of the bucket name, `wspool-home-folder-`, does not change across accounts or Regions. For example, if you enable home folders for directories in the US West (Oregon) Region (us-west-2) on account number 123456789012, the service creates an Amazon S3 bucket in that Region with the name shown. Only an administrator with sufficient permissions can delete this bucket. ``` wspool-home-folder-us-west-2-123456789012 ``` As mentioned earlier, disabling home folders for directories does not delete any user content stored in the Amazon S3 bucket. To permanently delete user content, an administrator with adequate access must do so from the Amazon S3 console. WorkSpaces Pools adds a bucket policy that prevents accidental deletion of the bucket. #### Home Folder Content Synchronization When home folders are enabled, WorkSpaces Pools creates a unique folder for each user in which to store their content. The folder is created as a unique Amazon S3 prefix that uses a hash of the user name within an S3 bucket for your Amazon Web Services account and Region. After WorkSpaces Pools creates the home folder in Amazon S3, it copies the accessed content in that folder from the S3 bucket to the WorkSpace. This enables the user to access their home folder content quickly, from the WorkSpace in the WorkSpace Pool, during their streaming session. Changes that you make to a user’s home folder content in an S3 bucket and that the user makes to their home folder content on a WorkSpace in the WorkSpace Pool are synchronized between Amazon S3 and WorkSpaces Pools as follows. 1. At the beginning of a user’s WorkSpaces Pools streaming session, WorkSpaces Pools catalogs the home folder files that are stored for that user in the Amazon S3 bucket for your Amazon Web Services account and Region. 1. A user’s home folder content is also stored on the WorkSpace in WorkSpaces Pools from which they stream. When a user accesses their home folder on the WorkSpace, the list of cataloged files is displayed. 1. WorkSpaces Pools downloads a file from the S3 bucket to the WorkSpace only after the user uses a streaming application to open the file during their streaming session. 1. After WorkSpaces Pools downloads the file to the WorkSpace, synchronization occurs after the file is accessed 1. If the user changes the file during their streaming session, WorkSpaces Pools uploads the new version of the file from the WorkSpace to the S3 bucket periodically or at the end of the streaming session. However, the file is not downloaded from the S3 bucket again during the streaming session. The following sections describe synchronization behavior when you add, replace, or remove a user's home folder file in Amazon S3. **Topics** + [Synchronization of files that you add to a user’s home folder in Amazon S3](#home-folders-content-synchronization-content-added-to-user-home-folder-in-S3) + [Synchronization of files that you replace in a user’s home folder in Amazon S3](#home-folders-content-synchronization-content-replaced-in-user-home-folder-S3) + [Synchronization of files that you remove from a user’s home folder in Amazon S3](#home-folders-content-synchronization-content-removed-from-user-home-folder-S3) ##### Synchronization of files that you add to a user’s home folder in Amazon S3 If you add a new file to a user’s home folder in an S3 bucket, WorkSpaces Pools catalogs the file and displays it in the list of files in the user’s home folder within a few minutes. However, the file isn’t downloaded from the S3 bucket to the WorkSpace until the user opens the file with an application during their streaming session. ##### Synchronization of files that you replace in a user’s home folder in Amazon S3 If a user opens a file in their home folder on the WorkSpace in the WorkSpace Pool during their streaming session, and you replace the same file in their home folder in an S3 bucket with a new version during that user’s active streaming session, the new version of the file is not immediately downloaded to the WorkSpace. The new version is downloaded from the S3 bucket to the WorkSpace only after the user starts a new streaming session and opens the file again. ##### Synchronization of files that you remove from a user’s home folder in Amazon S3 If a user opens a file in their home folder on the WorkSpace in the WorkSpace Pool during their streaming session, and you remove the file from their home folder in an S3 bucket during that user’s active streaming session, the file is removed from the WorkSpace after the user does either of the following: + Opens the home folder again + Refreshes the home folder #### Home Folder Formats The hierarchy of a user folder depends on how a user launches a streaming session, as described in the following section. ##### SAML 2.0 For sessions created using SAML federation, the user folder structure is as follows: ``` bucket-name/user/federated/user-id-SHA-256-hash/ ``` In this case, `user-id-SHA-256-hash` is the folder name created using a lowercase SHA-256 hash hexadecimal string generated from the `NameID` SAML attribute value passed in the SAML federation request. To differentiate users who have the same name but belong to two different domains, send the SAML request with `NameID` in the format `domainname\username`. For more information, see [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md). The following example folder structure applies to session access using SAML federation with `NameID` SAMPLEDOMAIN\$1testuser, account ID 123456789012 in the US West (Oregon) Region: ``` wspool-home-folder-us-west-2-123456789012/user/federated/8dd9a642f511609454d344d53cb861a71190e44fed2B8aF9fde0C507012a9901 ``` When part or all of the NameID string is capitalized (as the domain name *SAMPLEDOMAIN* is in the example), WorkSpaces Pools generates the hash value based on the capitalization used in the string. Using this example, the hash value for SAMPLEDOMAIN\$1testuser is 8DD9A642F511609454D344D53CB861A71190E44FED2B8AF9FDE0C507012A9901. In the folder for that user, this value is displayed in lowercase, as follows: 8dd9a642f511609454d344d53cb861a71190e44fed2B8aF9fde0C507012a9901. You can identify the folder for a user by generating the SHA-256 hash value of the `NameID` using websites or open source coding libraries available online. #### Additional Resources For more information about managing Amazon S3 buckets and best practices, see the following topics in the *Amazon Simple Storage Service User Guide*: + You can provide offline access to user data for your users with Amazon S3 policies. For more information, see [Amazon S3: Allows IAM Users Access to Their S3 Home Directory, Programmatically and In the Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_s3_home-directory-console.html) in the *IAM User Guide*. + You can enable file versioning for content stored in Amazon S3 buckets used by WorkSpaces Pools. For more information, see [Using Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html). # Enable application settings persistence for your WorkSpaces Pools users WorkSpaces Pools supports persistent application settings for Windows-based directories. This means that your users' application customizations and Windows settings are automatically saved after each streaming session and applied during the next session. Examples of persistent application settings that your users can configure include, but are not limited to, browser favorites, settings, webpage sessions, application connection profiles, plugins, and UI customizations. These settings are saved to an Amazon Simple Storage Service (Amazon S3) bucket in your account, within the AWS Region in which application settings persistence is enabled. They are available in each WorkSpaces Pools streaming session. **Note** Standard Amazon S3 charges may apply to data that is stored in your S3 bucket. For more information, see [Amazon S3 Pricing](https://aws.amazon.com/s3/pricing/). **Topics** + [How application settings persistence works](how-it-works-app-settings-persistence.md) + [Enabling application settings persistence](enabling-app-settings-persistence.md) + [Administer the VHDs for your users' application settings](administer-app-settings-vhds.md) # How application settings persistence works Persistent application settings are saved to a Virtual Hard Disk (VHD) file. This file is created the first time a user streams an application from a directory on which application settings persistence is enabled. If the WorkSpace Pool associated with the directory is based on an image that contains default application and Windows settings, the default settings are used for the user's first streaming session. When the streaming session ends, the VHD is unmounted and uploaded to an Amazon S3 bucket within your account. The bucket is created when you enable persistent application settings for the first time for a directory in an AWS Region. The bucket is unique to your AWS account and the Region. The VHD is encrypted in transit using Amazon S3 SSL endpoints, and at rest using [AWS Managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk). The VHD is mounted to the WorkSpace in both `C:\Users\%username%` and `D:\%username%`. If your WorkSpace is not joined to an Active Directory domain, the Windows user name is PhotonUser. If your WorkSpace is joined to an Active Directory domain, the Windows user name is that of the logged in user. Application settings persistence does not work across different operating system versions. For example, if you enable application settings persistence for a WorkSpace Pool that uses a Windows Server 2019 image, if you update the WorkSpace Pool to use an image that runs a different operating system (such as Windows Server 2022), settings from previous streaming sessions are not saved for users of the directory. Instead, after you update the WorkSpace Pool to use the new image, when users launch a streaming session from a WorkSpace, a new Windows user profile is created. However, if you apply an update to the same operating system on the image, users' customizations and settings from previous streaming sessions are saved. When updates to the same operating system are applied to an image, the same Windows user profile is used when users launch a streaming session from the WorkSpace. **Important** WorkSpaces Pools supports applications that rely on the [Microsoft Data Protection API](https://docs.microsoft.com/en-us/windows/desktop/seccng/cng-dpapi) only when the WorkSpace is joined to a Microsoft Active Directory domain. In cases where a WorkSpace is not joined to an Active Directory domain, the Windows user, PhotonUser, is different on each WorkSpace. Due to the way in which the DPAPI security model works, users' passwords don’t persist for applications that use DPAPI in this scenario. In cases where WorkSpaces are joined to an Active Directory domain and the user is a domain user, the Windows user name is that of the logged in user, and users’ passwords persist for applications that use DPAPI. WorkSpaces Pools automatically saves all files and folders in this path, except for the following folders: + Contacts + Desktop + Documents + Downloads + Links + Pictures + Saved Games + Searches + Videos Files and folders created outside of these folders are saved within the VHD and synced to Amazon S3. The default VHD maximum size is 5 GB for Pools. The size of the saved VHD is the total size of the files and folders that it contains. WorkSpaces Pools automatically saves the `HKEY_CURRENT_USER` registry hive for the user. For new users (users whose profiles don't exist in Amazon S3), WorkSpaces Pools creates the initial profile by using the default profile. This profile is created in the following location on the image builder: `C:\users\default`. **Note** The entire VHD must be downloaded to the WorkSpace before a streaming session can begin. For this reason, a VHD that contains a large amount of data can delay the start of the streaming session. For more information, see [Best practices for enabling application settings persistence](enabling-app-settings-persistence.md#best-practices-app-settings-persistence). When you enable application settings persistence, you must specify a settings group. The settings group determines which saved application settings are used for a streaming session from this directory. WorkSpaces Pools creates a new VHD file for the settings group that is stored separately within the S3 bucket in your AWS account. If the settings group is shared between directories, the same application settings are used in each directory. If a directory requires its own application settings, specify a unique settings group for the directory. # Enabling application settings persistence **Topics** + [Prerequisites for enabling application settings persistence](#prerequisites-app-settings-persistence) + [Best practices for enabling application settings persistence](#best-practices-app-settings-persistence) + [How to enable application settings persistence](#howto-enable-app-settings-persistence) ## Prerequisites for enabling application settings persistence To enable application settings persistence, you must first do the following: + Use an image that was created from a base image published by AWS on or after December 7, 2017. + Enable network connectivity to Amazon S3 from your virtual private cloud (VPC) by configuring internet access or a VPC endpoint for Amazon S3. For more information, see the *Home Folders and VPC Endpoints* section in [Networking and Access for WorkSpaces Pools](managing-network.md). ## Best practices for enabling application settings persistence To enable application settings persistence without providing internet access to your WorkSpaces, use a VPC endpoint. This endpoint must be in the VPC to which your WorkSpaces in WorkSpaces Pools are connected. You must attach a custom policy to enable WorkSpaces Pools access to the endpoint. For information about how to create the custom policy, see the *Home Folders and VPC Endpoints* section in [Networking and Access for WorkSpaces Pools](managing-network.md). For more information about private Amazon S3 endpoints, see [VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html) and [Endpoints for Amazon S3](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html) in the *Amazon VPC User Guide*. ## How to enable application settings persistence You can enable or disable application settings persistence while creating a directory or after the directory is created by using the WorkSpaces console. For each AWS Region, persistent application settings are stored in an S3 bucket in your account. The first time you enable application settings persistence for a directory in an AWS Region, WorkSpaces Pools creates an S3 bucket in your AWS account in the same Region. The same bucket stores the application settings VHD file for all users and all directories in that AWS Region. For more information, see *Amazon S3 Bucket Storage* in [Administer the VHDs for your users' application settings](administer-app-settings-vhds.md). **To enable application settings persistence while creating a directory** + Follow the steps in [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md), and make sure that **Enable Application Settings Persistence** is selected. **To enable application settings persistence for an existing 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 left navigation pane, choose **Pools**, and select the pool for which to enable application persistence. 1. Choose **Edit** in the **Settings** section of the page. 1. In the **Application Persistence** section of the page, select **Enable Application settings persistence**. 1. Choose **Save changes**. New streaming sessions now have application settings persistence enabled. # Administer the VHDs for your users' application settings **Topics** + [Amazon S3 bucket storage](#app-persistence-s3-buckets) + [Reset a user's application settings](#app-persistence-s3-reset) + [Enable Amazon S3 object versioning and revert a user's application settings](#app-persistence-enable-versions-revert-settings) + [Increase the size of the application settings VHD](#app-persistence-increase-VHD-size) ## Amazon S3 bucket storage When you enable application settings persistence, your users’ application customizations and Windows settings are automatically saved to a Virtual Hard Disk (VHD) file that is stored in an Amazon S3 bucket created in your AWS account. For every AWS Region, WorkSpaces Pools creates a bucket in your account that is unique to your account and the Region. All application settings configured by your users are stored in the bucket for that Region. You do not need to perform any configuration tasks to manage these S3 buckets; they are fully managed by the WorkSpaces Pools service. The VHD file that is stored in each bucket is encrypted in transit using Amazon S3's SSL endpoints and at rest using [AWS Managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk). The buckets are named in a specific format as follows: ``` wspool-app-settings--- ``` ***region-code*** This is the AWS Region code in which the directory is created with application settings persistence. ***account-id-without-hyphens*** Your AWS account ID. The random identifier ensures there is no conflict with other buckets in that Region. The first part of the bucket name, `wspool-app-settings`, does not change across accounts or Regions. For example, if you enable application settings persistence for directories in the US West (Oregon) Region (us-west-2) on account number 123456789012, WorkSpaces Pools creates an Amazon S3 bucket within your account in that Region with the name shown. Only an administrator with sufficient permissions can delete this bucket. ``` wspool-app-settings-us-west-2-1234567890123-abcdefg ``` Disabling application settings persistence does not delete any VHDs stored in the S3 bucket. To permanently delete settings VHDs, you or another administrator with adequate permissions must do so by using the Amazon S3 console or API. WorkSpaces Pools adds a bucket policy that prevents accidental deletion of the bucket. When application settings persistence is enabled, a unique folder is created for each settings group to store the settings VHD. The hierarchy of the folder in the S3 bucket depends on how the user launches a streaming session, as described in the following section. The path for the folder where the settings VHD is stored in the S3 bucket in your account uses the following structure: ``` bucket-name/Windows/prefix/settings-group/access-mode/user-id-SHA-256-hash ``` ***bucket-name*** The name of the S3 bucket in which users' application settings are stored. The name format is described earlier in this section. ***prefix*** The Windows version-specific prefix. For example, v4 for Windows Server 2012 R2. ***settings-group*** The settings group value. This value is applied to one or more directories that share the same the same application settings. ***access-mode*** The identity method of the user: `custom` for the WorkSpaces Pools API or CLI, `federated` for SAML, and `userpool` for user pool users. ***user-id-SHA-256-hash*** The user-specific folder name. This name is created using a lowercase SHA-256 hash hexadecimal string generated from the user ID. The following example folder structure applies to a streaming session that is accessed using the API or CLI with a user ID of `testuser@mydomain.com`, an AWS account ID of `123456789012`, and the settings group `test-stack` in the US West (Oregon) Region (us-west-2): ``` wspool-app-settings-us-west-2-1234567890123-abcdefg/Windows/v4/test-stack/custom/a0bcb1da11f480d9b5b3e90f91243143eac04cfccfbdc777e740fab628a1cd13 ``` You can identify the folder for a user by generating the lowercase SHA-256 hash value of the user ID using websites or open source coding libraries available online. ## Reset a user's application settings To reset a user's application settings, you must find and delete the VHD and associated metadata file from the S3 bucket in your AWS account. Make sure that you do not do this during a user's active streaming session. After you delete the user's VHD and the metadata file, the next time the user launches a session from a streaming instance that has application settings persistence enabled, WorkSpaces Pools creates a new settings VHD for that user. **To reset a user's application settings** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name** list, choose the S3 bucket that contains the application settings VHD that you want to reset. 1. Locate the folder that contains the VHD. For more information about how to navigate the S3 bucket folder structure, see *Amazon S3 Bucket Storage* earlier in this topic. 1. In the **Name** list, select the check box next to the VHD and the REG, choose **More**, and then choose **Delete**. 1. In the **Delete objects** dialog box, verify that the VHD and the REG are listed, and then choose **Delete**. The next time the user streams from a pool on which application settings persistence is enabled with the applicable settings group, a new application settings VHD is created. This VHD is saved to the S3 bucket at the end of the session. ## Enable Amazon S3 object versioning and revert a user's application settings You can use Amazon S3 object versioning and lifecycle policies to manage your users’ application settings when your users change them. With Amazon S3 object versioning, you can preserve, retrieve, and restore every version of the settings VHD. This enables you to recover from both unintended user actions and application failures. When versioning is enabled, after each streaming session, a new version of the application settings VHD is synced to Amazon S3. The new version does not overwrite the previous version, so if an issue with your users' settings occurs, you can revert to a previous version of the VHD. **Note** Each version of the application settings VHD is saved to Amazon S3 as a separate object and is charged accordingly. Object versioning is not enabled by default in your S3 bucket, so you must explicitly enable it. **To enable object versioning for your application settings VHD** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name **list, choose the S3 bucket that contains the application settings VHD on which to enable object versioning. 1. Choose **Properties**. 1. Choose **Versioning**, **Enable versioning**, and then choose **Save**. To expire older versions of your application settings VHDs, you can use Amazon S3 lifecycle policies. For information, see [How Do I Create a Lifecycle Policy for an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-lifecycle.html) in the *Amazon Simple Storage Service User Guide*. **To revert a user's application settings VHD** You can revert to a previous version of a user's application settings VHD by deleting newer versions of the VHD from the applicable S3 bucket. Do not do this when the user has an active streaming session. 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name** list, choose the S3 bucket that contains the user's application settings VHD version to revert to. 1. Locate and select the folder that contains the VHD. For information about how to navigate the S3 bucket folder structure, see *Amazon S3 Bucket Storage* earlier in this topic. When you select the folder, the settings VHD and associated metadata file display. 1. To display a list of the VHD and metadata file versions, choose **Show**. 1. Locate the version of the VHD to revert to. 1. In the **Name** list, select the check boxes next to the newer versions of the VHD and associated metadata files, choose **More**, and then choose **Delete**. 1. Verify that the application settings VHD that you want to revert to and the associated metadata file are the newest versions of these files. The next time the user streams from a pool on which application settings persistence is enabled with the applicable settings group, the reverted version of the user's settings displays. ## Increase the size of the application settings VHD The default VHD maximum size is 5 GB for Pools. If a user requires additional space for application settings, you can download the applicable application settings VHD to a Windows computer to expand it. Then, replace the current VHD in the S3 bucket with the larger one. Do not do this when the user has an active streaming session. **Note** To reduce the physical size of the virtual hard disk (VHD), clear the recycle bin before ending a session. This also reduces upload and download times, and improves the overall user experience. **To increase the size of the application settings VHD** **Note** The full VHD must be downloaded before a user can stream applications. Increasing the size of an application settings VHD can increase the time it takes for users to start application streaming sessions. 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name** list, choose the S3 bucket that contains the application settings VHD to expand. 1. Locate and select the folder that contains the VHD. For information about how to navigate the S3 bucket folder structure, see [Amazon S3 bucket storage](#app-persistence-s3-buckets) earlier in this topic. When you select the folder, the settings VHD and associated metadata file display. 1. Download the `Profile.vhdx` file to a directory on your Windows computer. Do not close your browser after the download completes, because you'll use the browser again later to upload the expanded VHD. 1. To use Diskpart to increase the size of the VHD to 7 GB, open the command prompt as an administrator, and type the following commands. ``` diskpart ``` ``` select vdisk file="C:\path\to\application\settings\profile.vhdx" ``` ``` expand vdisk maximum=7000 ``` 1. Then, type the following Diskpart commands to find and attach the VHD, and display the list of volumes: ``` elect vdisk file="C:\path\to\application\settings\profile.vhdx" ``` ``` attach vdisk ``` ``` list volume ``` In the output, make note of the volume number with the label "AwsEucUsers". In the next step, you select this volume so that you can enlarge it. 1. Type the following command in which `` is the number in the list volume output. ``` select volume ``` 1. Type the following command: ``` extend ``` 1. Type the following commands to confirm that the size of the partition on the VHD increased as expected (7 GB in this example): ``` diskpart ``` ``` select vdisk file="C:\path\to\application\settings\profile.vhdx" ``` ``` list volume ``` 1. Type the following command to detach the VHD so that it can be uploaded: ``` detach vdisk ``` 1. Return to your browser with the Amazon S3 console, choose **Upload**, **Add files**, and then select the enlarged VHD. 1. Choose **Upload**. After the VHD is uploaded, the next time the user streams from a pool on which application settings persistence is enabled with the applicable settings group, the larger application settings VHD is available. # WorkSpaces Pools troubleshooting notification codes The following are notification codes and resolution steps for issues with domain join that you might encounter when you set up and use Active Directory with WorkSpaces. **DOMAIN\$1JOIN\$1ERROR\$1ACCESS\$1DENIED** **Message**: Access is denied. **Resolution**: The service account specified in the directory does not have permissions to create the computer object or reuse an existing one. Validate the permissions and start the WorkSpaces pool. **DOMAIN\$1JOIN\$1ERROR\$1LOGON\$1FAILURE** **Message**: The username or password is incorrect. **Resolution**: The service account specified in the directory has an invalid username or password. Update the credentials in the AWS Secrets Manager secret configured in the directory, and start the WorkSpaces pool again. **DOMAIN\$1JOIN\$1NERR\$1PASSWORD\$1EXPIRED** **Message**: The password of this user has expired. **Resolution**: The password for the service account in the AWS Secrets Manager secret has expired. First, stop the WorkSpaces pool. Next, change the password for the secret specified in the WorkSpaces directory. Then, start the WorkSpaces pool. **DOMAIN\$1JOIN\$1ERROR\$1DS\$1MACHINE\$1ACCOUNT\$1QUOTA\$1EXCEEDED** **Message**: Your computer could not be joined to the domain. You have exceeded the maximum number of computer accounts you are allowed to create in this domain. Contact your system administrator to have this limit reset or increased. **Resolution**: The service account specified on the directory does not have permissions to create the computer object or reuse an existing one. Validate the permissions and start the WorkSpaces pool. **DOMAIN\$1JOIN\$1ERROR\$1INVALID\$1PARAMETER** **Message**: A parameter is incorrect. This error is returned if the `LpName` parameter is NULL or the `NameType` parameter is specified as `NetSetupUnknown` or an unknown nametype. **Resolution**: This error can occur when the distinguished name for the OU is incorrect. Validate the OU and try again. If you continue to encounter this error, contact AWS Support. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). **DOMAIN\$1JOIN\$1ERROR\$1MORE\$1DATA** **Message**: More data is available. **Resolution**: This error can occur when the distinguished name for the OU is incorrect. Validate the OU and try again. If you continue to encounter this error, contact AWS Support. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). **DOMAIN\$1JOIN\$1ERROR\$1NO\$1SUCH\$1DOMAIN** **Message**: The specified domain either does not exist or could not be contacted. **Resolution**: The streaming instance was unable to contact your Active Directory domain. To ensure network connectivity, confirm your VPC, subnet, and security group settings. **DOMAIN\$1JOIN\$1NERR\$1WORKSTATION\$1NOT\$1STARTED** **Message**: The Workstation service has not been started. **Resolution**: An error occurred starting the Workstation service. Ensure that the service is enabled in your image. If you continue to encounter this error, contact AWS Support. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). **DOMAIN\$1JOIN\$1ERROR\$1NOT\$1SUPPORTED** **Message**: The request is not supported. This error is returned if a remote computer was specified in the `lpServer` parameter and this call is not supported on the remote computer. **Resolution**: Contact AWS Support for assistance. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). **DOMAIN\$1JOIN\$1ERROR\$1FILE\$1NOT\$1FOUND** **Message**: The system cannot find the file specified. **Resolution**: This error occurs when an invalid organizational unit (OU) distinguished name is provided. The distinguished name must start with **OU=**. Validate the OU distinguished name and try again. **DOMAIN\$1JOIN\$1INTERNAL\$1SERVICE\$1ERROR** **Message**: The account already exists. **Resolution**: This error can occur in the following scenarios: + If the issue isn't permissions-related, check the Netdom logs for errors and make sure that you provided the correct OU. + The service account specified in the directory does not have permissions to create the computer object or reuse an existing one. If this is the case, validate the permissions and start the WorkSpaces pool. + After WorkSpaces creates the computer object, it is moved from the OU in which it was created. In this case, the first WorkSpaces pool is created successfully, but any new WorkSpaces pool that uses the computer object fails. When Active Directory searches for the computer object in the specified OU and detects that an object with the same name exists elsewhere in the domain, the domain join is not successful. + The name of the OU specified in the WorkSpaces directory includes spaces before or after the commas in the directory. In this case, when a WorkSpaces pool attempts to rejoin the Active Directory domain, WorkSpaces cannot cycle the computer objects correctly and the domain rejoin does not succeed. To resolve this issue for a WorkSpaces pool, do the following: 1. Stop the WorkSpaces pool. 1. Edit the Active Directory domain settings for the WorkSpaces pool to remove the directory and Directory OU to which the WorkSpaces pool is joined. 1. Update the WorkSpaces directory to specify an OU that doesn't contain spaces. 1. Edit the Active Directory domain settings for the WorkSpaces pool to specify the directory with the updated Directory OU. To resolve this issue for a WorkSpaces pool, do the following: 1. Delete the WorkSpaces pool. 1. Update the WorkSpaces directory to specify an OU that doesn't contain spaces. 1. Create a new WorkSpaces pool and specify the directory with the updated Directory OU. **WORKSPACES\$1POOL\$1SESSION\$1RESERVATION\$1ERROR** **Message**: We currently do not have sufficient capacity for requested sessions in the availability zones [us-west-1] for subnets associated with your WorkSpaces Pool. Our system will be working on provisioning additional capacity. Meanwhile, please change or associate a different subnet using one of the following AZs [us-west-2, us-west-3]. **Resolution**: Wait until EC2 has enough capacity or update subnets in other AZs on the directory. **INSUFFICIENT\$1CAPACITY\$1ERROR\$1WORKSPACES\$1POOL\$1AZ** **Message**: We currently don't have sufficient capacity for requested sessions in availability zone (AZs) []. Our system will be working on provisioning additional capacity. Meanwhile please change or associate another subnet using other AZs to your WorkSpaces Pool. **Resolution**: Wait until Amazon EC2 has enough capacity or update subnets in other AZs on the directory. **INVALID\$1CUSTOMER\$1SUBNET\$1CIDR\$1BLOCK** **Message**: Your subnet includes use of an unavailable CIDR range. Please update your subnets outside of the current /18 range.”. **Resolution**: Wait until EC2 has enough capacity or update subnets in other AZs on the directory.