Set up with Windows Desktop Access (RDP)
Overview
Running automation that requires interaction with the Windows desktop requires an active user session to Windows.
For example, running Workforce Agent as a service can perform so-called "headless" operations. Still, it cannot interact with UI applications.
The standard solution is making and maintaining "infinitely" running user sessions. Still, these are pretty brittle and can be security risks, so a better solution is needed.
The main parts of the solution are:
- A Windows Service that provides the secure connection to Robocorp Control Room to trigger robot executions.
- Local RDP connection is used to open the user session (only for the execution duration) so that the robot can interact with the complete Windows UI.
- Executor launched via Task Scheduler when the user logs in so that the robot executor is working with the target user's privileges.
Target goals, requirements and installation instructions are all on this page so check these out.
As we have seen, different enterprises can have quite varied ways of setting up Windows Group Policies, Active Directories, etc., so any feedback on the guides and tools is highly appreciated. Do not hesitate to contact us in the Robocorp Slack or Forum
Goals
- Enable full desktop access for the robot execution on the target machine that does not have a user logged in.
- Assign work to the machine from Robocorp Control Room just like any other Workforce environment.
- Make Windows Remote Desktop access as limited as possible and fully controllable by the end-user or IT managing it.
- RDP access from external networks is NOT required, only from localhost.
- Solution works after the target machine reboots.
- Make the setup as secure and straightforward as possible.
- Enable running multiple setups on one Windows Machine using different user accounts.
Prerequisites
Before starting to set up the RDP service itself, you must verify these steps. Usually, this should be done by IT, so pass this guide onto your IT.
Standard Windows Virtual Machines from AWS service do not need any special settings so one can just jump to Installation and Use. However, many different policies and settings control Remote Desktop Connection, which is highly specific to company-level IT practices.
Able to open a local RDP connection
The solution does not take any RDP connections from external networks. Still, it requires opening an RDP session locally on the machine without any confirmation pop-ups or user interactions.
The list below is a collection of settings we have seen blocking the setup:
- Windows Remote Desktop enabled on the target machine.
- The RDP session is only opened inside the target machine (localhost) and does not need to be open to external connections.
- The connections are made from
TERMSRV/127.0.0.2
using the default RDP port3389
- The target machine cannot have Windows Interactive Logon messages enabled.
- These usually come in the form of legal notices and cannot be bypassed by automation as they are designed to require human input.
- Disabling this has to be done with the permission of the IT controlling the target machine as these are usually set up for a reason.
- Group Policies can allow/block specific user groups from opening local RDP connections
- See technical guide: Group Policy: Allow local RDP connections for user groups
- Running more than two simultaneous user sessions on Windows Servers requires Microsoft RDS CAL licensing, read more behind the link.
You can test the connection as you are making the settings.
Please get in touch with us if you find any additional settings or details as company policies vary a lot, and we are trying to collect our list to be as comprehensive as possible
Users for running the automation
- Add or select the user on the target machine you want this setup to use.
- You can use this user to limit access to the machine the way you want.
- User can be a local user or from AD; you need to know the user's domain.
- You need to know the user's password when setting up the service.
- The users will be added to the group
Remote Desktop Users
unless they are already there by the helper tool. - It is highly recommended to have these users be dedicated for automation runs only
- Having humans using these user accounts should only happen for setting up and possibly debugging situations
Azure Active Directory (AAD)
-users cannot be used to run Windows services- The user for the RDP setup needs to be either a local user or from a regular Active Directory.
- Despite its name Azure Active Directory has very little in common with the regular Active Directory regarding functionalities, check out a summary of the differences here.
Installation and use
Check and test the Prerequisites first
Get Robocorp Service Helper
tool to the target machine:
- Download from:
https://downloads.robocorp.com/workforce-agent-core/tools/robocorp-service-helper.exe - Using curl:
curl -o robocorp-service-helper.exe https://downloads.robocorp.com/workforce-agent-core/tools/robocorp-service-helper.exe
The following chapters are separated for different use cases as our tooling provides different usage for the cases:
- Setting up a single environment for testing purposes
- Setting up multiple machines for production and maintenance
- Setting up multiple environments running on a single machine
Setting up a single environment for testing purposes
The Service Helper
provides a simple interactive mode to get you started to set your first test service.
Log in to the target machine with the user account that the service needs to run on
Open Command Prompt in Administrator mode
Run the command:
whoami
, you can use the value returned to verify the recommendations that the service-helper provides to you in the next step.C:\Installs>whoami ec2amaz-7ssvr8i\rpajack
Run command:
robocorp-service-helper setup-desktop
C:\Installs>robocorp-service-helper setup-desktop Input windows login domain (EC2AMAZ-7SSVR8I): Input Windows login username (RpaJack): Input Robocloud link token: FRwFlv5illkjVHMZ3kko... Input Windows login password (leave empty to set later):
- The
Service Helper
recommends values fordomain
andusername
, which you can validate against the results of thewhoami
-command, and if correct, you only need to pressEnter
- The Robocloud Link Token is requested next:
- Get the token from Control Room
Control Room > Select a Workspace > Environments > Generate link token
- Copy & paste the token to the command prompt
- Note: The link token is consumed on use and does not need to be stored anywhere.
- Get the token from Control Room
- The last question is the user's password
- You can leave the password empty here or set it
- To set the password outside the service-helper follow the guides:
- At this point,
Service Helper
will load and install all needed components for the service.- If your user is already in the group
Remote Desktop Users
, you will see one error stating that the user was already there; no need to worry about this one.
- If your user is already in the group
- If everything when fine, you should see the new environment in Control Room in the state:
Offline
- The
Start the service by running:
robocorp-service-helper start
- The tool will again recommend values for
domain
andusername
again; just pressing enter should do here.C:\Installs>robocorp-service-helper start Input windows login domain (EC2AMAZ-7SSVR8I): Input Windows login username (RpaJack): [2022-03-04T20:57:48.296] [INFO] Start - Starting service: Robocorp-WFA-EC2AMAZ-7SSVR8I-RpaJack
- If everything when fine, the service should now be running, and you should see the new environment in Control Room in
Idle
-state - You are ready to rock!
- If something went wrong, don't worry; you can just run
robocorp-service-helper remove --all
to get back to the beginning - You just need to remove the created environment from Control Room and generate a new link token on the next run.
- Note: Most common cause for an error is a typo in the password so that you can fix following the guides:
- If something went wrong, don't worry; you can just run
- The tool will again recommend values for
As the final step, you can now test if the desktop opening works:
Setting up multiple machines for production and maintenance
Setting up multiple machines using the interactive mode gets a bit clunky, so the Service Helper
has support for using config files.
Here you can define a config -file that contains all the settings needed, so you do not have to input them multiple times on the command prompt.
In this use case leveraging the Environment Groups -feature in Control Room becomes really powerful.
You can define an Environment Group first and there add a link token with expiration time.
This link token can be reused to link multiple environments, and environments are automatically added to the correct group.
Remember to keep the link token expiration time reasonable with security in mind though.
The best way to build your config file is to log in to one of your machines with the targeted user
Create the config file by following the comments in the template below:
This is just a YAML file, so any text editor will do
You can customize the values as you see fit
# --- Arguments are optional, comment to use defaults. --- # Environment name shown in Robocorp Control Room and name of the service on the machine # Defaults to `echo Robocorp-WFA-%COMPUTERNAME%-%USERNAME%` resourceName: Robocorp-WFA-MACHINE_ABC-JohnDoe # User domain: Defaults to `echo %USERDOMAIN%`. # For Active Directory (AD), use command `whoami` to check the correct domain value. domain: MACHINE-ABC # Username: Defaults to `echo %USERNAME%` username: JohnDoe # Full path to location where run content is stored # Defaults to `echo %LOCALAPPDATA%\robocorp\workforce-agent-core-service` instancePath: C:\Users\JohnDoe\AppData\Local\robocorp\workforce-agent-core-service # Full path to the location where environment caching is done (no spaces or special characters in this path) # Defaults to `echo %LOCALAPPDATA%\robocorp` robocorpHome: C:\Users\JohnDoe\AppData\Local\robocorp # Link token from Robocorp Control Room linkToken: <link token> # You can give the user password here to avoid typos, but the password can also be left empty and set separately. password: <users password>
Now that you have the config file, you can set up the service by running:
robocorp-service-helper setup-desktop -c config.yaml
- If everything when fine, you should see the new environment in Control Room in the state:
Offline
- If everything when fine, you should see the new environment in Control Room in the state:
Start the service by running:
robocorp-service-helper start -c config.yaml
- If everything when fine, the service should now be running, and you should see the new environment in Control Room in
Idle
-state - You are ready to rock!
- If something went wrong, don't worry; you can just run
robocorp-service-helper remove -c config.yaml --all
to get back to the beginning - You just need to remove the created environment from Control Room.
- Note: Most common cause for an error is a typo in the password so that you can fix following the guides:
- If something went wrong, don't worry; you can just run
- If everything when fine, the service should now be running, and you should see the new environment in Control Room in
Now, take the config file to the other machines, edit as needed and run the setups.
Setting up multiple environments running on a single machine
Running multiple RDP setups on one machine reduces the setup and maintenance cost of separate Windows machines (virtual or real). Running multiple Workforce environments on the same machine also enables parallel running, and you can use the machine's resources fully. Basically, the solution is just setting up the service on multiple separate user accounts on the same machine.
NOTE:
Running more than two simultaneous user sessions on Windows Servers requires Microsoft RDS CAL licensing, read more behind the link.
- Create/select separate user accounts on the machine or via AD.
- Note: Each user needs to have logged in at least once to generate the user-specific folders.
- Set the amount of allowed RDP connections on the machine to match your needs:
- Windows Group Policy editor:
Computer Configuration └─ Administrative Templates └─ Windows Components └─ Remote Desktop Services └─ Remote Desktop Session Host └─ Connections
- Open and enable
Limit number of connections
and set the amount od connection to for example 10
- Open and enable
- Setup the service according to: Setting up multiple machines for production and maintenance
- Here you can just log in as
administrator
> create config files for each user > run the setups from the administrator user.
- Here you can just log in as
Limitations
User account per service
You need to set up a separate user account per service. It is also highly recommended not to use any existing human-user accounts. Having automation accounts separated keeps things clear. For example, these accounts can have long, complex passwords to avoid constant recycling. After setup, it is good to note that the solution does not require Remote Desktop Connections from external networks so that too can be used to secure the solution further.
Running multiple robots on a single Windows machine can cause resource collisions
Execution in the multiple RDP case can run the robot concurrently. For example, multiple robots can easily create file locking and race-conditions by accessing a common file outside the users' folder (e.g. C:\temp\test.txt
).
Also, not all applications targeted by automation allow simultaneous use on one machine, but these are case-by-case checkups that need to be handled.
Robots need to be mindful of their resources on the machine and the boundary between user-specific and machine-wide items.
Assign work in Control Room
You can now configure steps under Workforce Process to point to the new environment and choose whether or not to Use RDP Connection
:
You can use a simple robot that takes a screenshot from the target machine to test the whole setup. Example:
*** Settings ***
Library RPA.FileSystem
Library RPA.Desktop
*** Tasks ***
Minimal task
Create Directory %{ROBOT_ARTIFACTS}
Take Screenshot %{ROBOT_ARTIFACTS}${/}screenshot.png
Technical guides
Updates and maintenance
The Workforce Agent Core
-application is getting regular updates and new features, so maintenance of the service needs to have a known cadence for updates. We consider having at least a 6-month cycle to be the minimum, but we recommend having a monthly cadence around service updates. The changelog always shows the changes made.
We follow semantic versioning, which means only the major version updates can introduce breaking changes to the functionality. Minor and patch releases can only add or fix functionalities.
Updating the Workforce Agent running in the service requires three actions, all supported by Robocorp Service Helper
:
- Download from:
https://downloads.robocorp.com/workforce-agent-core/tools/robocorp-service-helper.exe - Using curl:
curl -o robocorp-service-helper.exe https://downloads.robocorp.com/workforce-agent-core/tools/robocorp-service-helper.exe
If possible, verify from Robocorp Control Room that no automation is running or is about to start. Stopping the service will make the environment offline for the duration of the update. The update itself should only take under a minute as it only downloads the new executable,
- Stop the service
- Interactive:
robocorp-service-helper stop
- With config file:
robocorp-service-helper stop -c <config file>
- Interactive:
- Update the Workforce Agent Core
- Interactive:
robocorp-service-helper update
- With config file:
robocorp-service-helper update -c <config file>
- Interactive:
- Restart the service
- Interactive:
robocorp-service-helper start
- With config file:
robocorp-service-helper start -c <config file>
- Interactive:
You should now see the environment in Idle
-state in Control Room.
Uninstalling
If you need to remove the setup or want a clean start, the guide below helps you out.
Note: The uninstall sequence cannot at the moment remove the environment from Control Room, so it is good to identify the environment there so you can remove the correct environment once you have uninstalled the services.
- Get
Robocorp Service Helper
-tool to the target machine:- Download from:
https://downloads.robocorp.com/workforce-agent-core/tools/robocorp-service-helper.exe - Using curl:
curl -o robocorp-service-helper.exe https://downloads.robocorp.com/workforce-agent-core/tools/robocorp-service-helper.exe
- Download from:
- To remove the service and related items, first you should stop the service with command:
- Interactive:
robocorp-service-helper stop
- With config file:
robocorp-service-helper stop -c <config file>
- Interactive:
- You can remove the service with the command:
- Interactive:
robocorp-service-helper remove --all
- With config file:
robocorp-service-helper remove -c <config file> --all
- Interactive:
After this, you can check the three places where the service is visible:
Windows Services
: The service with the given name should no longer be listed.Task Scheduler > Task Scheduler Library
Schedule starting with the given service name should no longer be listed.Credential Manager > Windows Credentials > TERMSRV/127.0.0.2
: Should no longer be listed.
Set the password for the service
If you gave the correct password in the setup phase, you can start the service.
If you left the password empty or had a typo, you can set the password here.
- Open Windows Services > Find & open
Robocorp Workforce Agent
properties > Log on- The username is set, but you need to input the user password here and Apply changes.
- The username is set, but you need to input the user password here and Apply changes.
Set the password to Windows Credentials Manager
If you gave the correct password in the setup phase, you can skip this.
If you left the password empty or had a typo, you can set the password here.
To securely use the password, the local RDP connection needs the user's access credential stored in Windows Credential Manager
- Setup the RDP user and password to Windows Credential Manager:
- Open Credential Manager by typing
credential manager
in the Start via - Modify the credential:
TERMSRV/127.0.0.2
by setting the users password
- Open Credential Manager by typing
Group Policy: Add Group Policy: Allow local RDP connections for user groups
Goal: Avoid Group Policy blocking the local connection completely
- Open
Group Policy Editor
and navigate to:Computer Configuration └─ Windows Settings └─ Security Settings └─ Local Policies └─ User Rights Assignment └─ Allow log on through Remote Desktop Services
- By default,
Remote Desktop Users
should be listed here.- If you are using different user groups, list the correct one here.
Testing the desktop access
If you want to verify the desktop access functionality or you are seeing timeout errors in Control Room. This guide shows you a way to locally test opening the desktop session.
- Log into the target machine with the user that is running the service
- Test the connection with the command below:
- Note: If successful, this will kick you out of the remote desktop connection you are using.
- The command to run is:
robocorp-service-helper test-desktop
- If you get any pop-ups etc., that require user input, further actions are needed.
- Check if the technical guides for solution
- Please get in touch with Robocorp in these cases as we are trying to collect all the fringe cases in this document.
- If you were kicked out of your remote connection, everything should be working and you can start assigning work from Control Room
Service helper Command-line mode
The helper tool also has a normal arguments mode, so all the values can be given in the command line. This is valuable for CI/CD and fleet management usage (SCCM etc.) as it allows scripting and running without expecting user inputs.
To run from the CI system, use flag: --ci to ensure the tool is running in non-interactive mode.
Run:
robocorp-service-helper --help
...to get details on the arguments
Commands | Description |
---|---|
robocorp-service-helper setup-desktop | Setup the automatic Windows desktop login service when the process is executed with this agent |
robocorp-service-helper test-desktop | Test the desktop setup via local RDP connection |
robocorp-service-helper start | Start the service |
robocorp-service-helper stop | Stop the service |
robocorp-service-helper update | Update the Agent Core |
robocorp-service-helper status | Get the service status |
robocorp-service-helper setup-background | Install the Agent Core as a background service |
robocorp-service-helper remove | Remove the service |
Remote desktop configuration file
The setup creates a local config file that can be used to control how the local RDP connection behaves.
You can find the config.rdp
file under %localappdata%\robocorp\workforce-agent-core-service
Note:
In basic cases, you do not need to do anything here and we have plans the enable this control directly from Control Room.
At the moment, the only known cases for needing this have been custom RDP port setting and desktop resolution control.
By default, the file content looks like:
full address:s:127.0.0.2:3389
authentication level:i:0
autoreconnection enabled:i:1
bandwidthautodetect:i:1
networkautodetect:i:0
screen mode id:i:2
desktop size id:i:2
desktopscalefactor:i:100
The official Microsoft documentation
Microsoft RDS CAL licensing
Let's open up the acronyms first:
- Microsoft Remote Desktop Services (RDS)
- Client Access License (CAL)
The full details and documentation at Microsoft's documentation
For companies already using multi-user Windows VMs, this is "business-as-usual". You probably only need to request to your IT (or who is managing the RD server) that you need an RDS license for machine A for user accounts X, Y and Z.
If you are unfamiliar with the topic, the summary is that without the licensing, providing a fully functioning Windows PC for REALLY cheap would be quite a simple task. So this is what Microsoft is tackling with the RDS licenses.
There are many ways to buy and manage RDS licenses, so it is tough for us to give a definitive guide on how to do the setup. Microsoft documentation is the best source to get started.
For the Workforce Agent RDP solution, this limitation can be seen when you try to open a third user session on one machine. The machine will prompt: "Two users are already logged in". This prompt will block the Workforce Agent from opening the connection, and it will time out.