Troubleshooting Active Directory

The following are issues that might occur when you set up and use Active Directory with Amazon AppStream 2.0. For help troubleshooting notification codes, see Troubleshooting Notification Codes.

My image builders and fleet instances are stuck in the PENDING state.

Image builders and fleet instances can take up to 25 minutes to move into a ready state and become available. If your instances are taking longer than 25 minutes to become available, in Active Directory, verify whether new computer objects were created in the correct organizational units (OUs). If there are new objects, the streaming instances will be available soon. If the objects aren't there, check the directory configuration details in your AppStream 2.0 Directory Config: Directory name (the fully qualified domain name of the directory, service account sign-in credentials, and the OU distinguished name.

Image builder and fleet errors are displayed in the AppStream 2.0 console on the Notifications tab for the fleet or image builder. Fleet errors are also available using the AppStream 2.0 API through the DescribeFleets operation or the CLI command describe-fleets.

My users aren't able to log in with the SAML application.

AppStream 2.0 relies on the SAML_Subject "NameID" attribute from your identity provider to populate the username field to log in your user. The username can either be formatted as "domain\username", or "[e-mail]". If you are using "domain\username" format, domain can either be the NetBIOS name or the fully qualified domain name. If using "[e-mail]" format, the UserPrincipalName attribute can be used. If you've verified your SAML_Subject attribute is configured correctly and the problem persists, contact AWS Support. For more information, see AWS Support Center.

My fleet instances work for one user but don't cycle correctly.

Fleet instances are cycled after a user completes a session, ensuring that each user has a new instance. When the cycled fleet instance is brought online, it joins the domain using the computer name of the previous instance. To ensure that this operation happens successfully, the service account requires Change Password and Reset Password permissions on the organizational unit (OU) to which the computer object is joining. Check the service account permissions and try again. If the problem persists, contact AWS Support. For more information, see AWS Support Center.

My user Group Policy objects aren't being successfully applied.

By default, computer objects apply computer-level policies based on the OU in which the computer object resides, while applying user-level policies based on the OU in which the user resides. If your user-level policies aren't being applied, you can do one of the following:

• Move the user-level policies to the OU in which the user Active Directory object resides

• Enable computer-level loopback processing, which applies the user-level policies in the computer object OU.

For more information, see Loopback processing of Group Policy at Microsoft Support.

My AppStream 2.0 streaming instances aren't joining the Active Directory domain.

The Active Directory domain to use with AppStream 2.0 must be accessible through its fully qualified domain name (FQDN) through the VPC in which your streaming instances are launched.

To test that your domain is accessible

1. Launch an Amazon EC2 instance in the same VPC, subnet, and security groups that you use with AppStream 2.0.

2. Manually join the EC2 instance to your Active Directory domain by using the FQDN (for example, yourdomain.example.com) with the service account that you intend to use with AppStream 2.0. Use the following command in a Windows PowerShell console:

   netdom join computer /domain:FQDN /OU:path /ud:user /pd:password

   If this manual join fails, go to the next step.

3. If you cannot manually join to your domain, open a command prompt and verify that you can resolve the FQDN using the nslookup command. For example:

   nslookup yourdomain.exampleco.com

   Successful name resolution returns a valid IP address. If you are unable to resolve your FQDN, you might need to update your VPC DNS servers by using a DHCP option set for your domain. Then, come back to this step. For more information, see DHCP Options Sets in the Amazon VPC User Guide.

4. If the FQDN resolves, use the telnet command to validate connectivity.

   telnet yourdomain.exampleco.com 389

   A successful connection shows a blank command prompt window without any connection errors. You might need to install the Telnet Client feature on your EC2 instance. For more information, see Install Telnet Client in the Microsoft documentation.

If you were not able to manually join the EC2 instance to your domain, but were successful in resolving the FQDN and testing connectivity with the Telnet Client, your VPC security groups might be preventing access. Active Directory requires certain network port settings. For more information, see Active Directory and Active Directory Domain Services Port Requirements in the Microsoft documentation.

User login is taking a long time to complete on a domain-joined streaming session.

AppStream 2.0 performs a Windows login action after users provide their domain password. After successful authentication, AppStream 2.0 launches the application. The login and launch times are impacted by many variables, such as network contention for the domain controllers or the time it takes to apply Group Policy settings to the streaming instance. If domain authentication takes too long to complete, try performing the following actions.

• Minimize the network latency from your AppStream 2.0 Region to your domain controllers by choosing the correct domain controllers. For example, if your fleet is in us-east-1, use domain controllers with high bandwidth and low latency to us-east-1 through Active Directory Sites and Services zone mappings. For more information, see Active Directory Sites and Services in the Microsoft documentation.

• Ensure that your Group Policy settings and user login scripts don't take prohibitively long to apply or run.

If your domain users' login to AppStream 2.0 fails with the message "An unknown error occurred," you might need to update the Group Policy settings described in Before You Begin Using Active Directory with AppStream 2.0. Otherwise, these settings might prevent AppStream 2.0 from authenticating and logging in your domain users.

My users can't access a domain resource in a domain-joined streaming session, but they can access the resource from a domain-joined image builder.

Confirm that your fleet is created in the same VPC, subnets, and security groups as your image builder, and that your user has the permissions required to access and use the domain resource.

My users receive the error “Certificate-Based Authentication not available” and are prompted to enter their domain password. Or users receive the error “Disconnected from session” when they are starting a session enabled with certificate-based authentication.

These errors occur if certificate-based authentication was unsuccessful for the session. The “Certificate-Based Authentication not available” error is displayed when certificate-based authentication is enabled to allow fallback to password logon. The “Disconnected from session” error is displayed when certificate-based authentication is enabled without fallback.

The user can refresh the page on the web client or reconnect from the client for Windows, as this may be an intermittent issue with certificate-based authentication. If the problem continues, certificate-based authentication failure can result from one of the following issues:

• AppStream 2.0 could not communicate with AWS Private CA, or AWS Private CA did not issue the certificate. Check CloudTrail to determine if a certificate was issued. For more information, see What Is AWS CloudTrail? and Manage Certificate-based Authentication.

• The domain controller has no domain controller certificate for smart card logon, or it is expired. For more information, see step 7.a in Prerequisites.

• The certificate is not trusted. For more information, see step 7.c in Prerequisites.

• The userPrincipalName format for the SAML_Subject NameID is not formatted properly, or does not resolve to the actual domain for the user. For more information, see step 1 in Prerequisites.

• The (optional) ObjectSid attribute in your SAML assertion does not match the Active Directory security identifier (SID) for the user specified in the SAML_Subject NameID. Confirm that the attribute mapping is correct in your SAML federation, and that your SAML identity provider is synchronizing the SID attribute for the Active Directory user.

• The AppStream 2.0 agent does not support certificate-based authentication. Use AppStream 2.0 agent version 10-13-2022 or later.

• There are Group Policy settings that are modifying the default Active Directory settings for smart card logon, or taking action if a smart card is removed from a smart card reader. These settings may cause additional unexpected behavior other than the errors listed above. Certificate-based authentication presents a virtual smart card to the instance operating system, and removes it after logon is complete. For more information, see Primary Group Policy settings for smart cards and Additional smart card Group Policy settings and registry keys. Do not enable Smart card sign in for Active Directory in your stack if you want to use certificate-based authentication. For more information, see Smart Cards.

• The CRL distribution point for the private CA is not online or accessible from either the AppStream 2.0 fleet instance or the domain controller. For more information, see step 5 in Prerequisites.

Additional troubleshooting steps involve reviewing the AppStream 2.0 instance Windows event logs. A common event to review for logon failure is 4625(F): An account failed to log on. For more information about capturing log information, see Persisting application and Windows event logs. Alternatively, to troubleshoot an active AppStream 2.0 session as an administrator, you can connect to the logs using an Event Viewer on another computer. For more information, see How to Select Computers in Event Viewer. Or ,you can connect by using Remote Desktop to connect to the instance private IP address from another computer that can connect to Remote Desktop Services in your AppStream 2.0virtual private cloud (VPC). Use the AWS CLI to determine the IP address for the session based on the AWS Region, AppStream 2.0 stack name, fleet name, user ID, and authentication type. For more information, see the AWS Command Line Interface.

If the problem persists, contact AWS Support. For more information, see AWS Support Center.

I'm experiencing domain join failures after changing the Active Directory (AD) service account.

If you have an existing fleet with an image based on the August 2024 Microsoft Windows Server operating system update, and if you change your Active Directory (AD) service account for that fleet, your fleet instances might encounter domain join failures during provisioning.

Microsoft has released a patch KB5020276, which modifies the behavior of domain join operations. AppStream 2.0 reuses existing computer objects when joining your streaming instances to your AD domains. This computer object is generated using the AD service account that you provide when you create a fleet or Directory Config with AppStream 2.0. Prior to this Microsoft patch, new AD service accounts could reuse existing computer objects created by AppStream 2.0, as long as they had "Create Computer Object" permissions configured in the organizational unit (OU).

When the Microsoft patch is enforced, starting on August 13, 2024, and if you change your AD service account for an existing AppStream 2.0 fleet, the new service account will no longer be able to reuse the existing computer objects in the AD. This results in domain join failures on AppStream 2.0 fleets, with one of the following error messages under fleet notifications:

• DOMAIN_JOIN_INTERNAL_SERVICE_ERROR "The group name could not be found."

• An account with the same name exists in Active Directory. Re-using the account was blocked by security policy

To control which account can reuse the existing computer objects, Microsoft has implemented a new Group Policy setting called Domain controller: Allow computer account re-use during domain join. This setting allows you to specify a list of trusted service accounts that bypass the check during the domain join operation. For your self-managed AD configuration, we recommend following the Microsoft documented steps to add your AD service account to the new allow list policy, using Group Policies on a domain controller.

For Managed Active Directory (MAD), you must restart your AppStream 2.0 fleet after you make changes to your AppStream 2.0 domain join service account.

If the problem persists, contact AWS Support. For more information, see AWS Support Center.