Configure WorkSpaces Manager

While WorkSpaces Manager is pre-configured in the appliance deployed via CloudFormation, some additional configurations are required to ensure optimal performance.

Join WorkSpaces Manager EC2 instance to Active Directory Domain. This is recommended for full functionaility.

Before proceeding with the upgrade procedure, ensure the following prerequisites are met:

1. Access to the EC2 Instance: You have access to the EC2 instance where WorkSpaces Manager (WSM) is configured.

2. AWS CLI v2: It is recommended to have AWS CLI v2 installed for interacting with AWS services from the command line.

3. Access to MS-SQL Instance and Database: Ensure valid access to the MS-SQL instance and the associated database.

4. EC2 Instance Role Permissions: The EC2 instance role must have sufficient permissions to read from AWS Secrets Manager.

5. Administrative Privileges: Administrative privileges on the EC2 instance are available, to perform tasks such as joining the domain, configuring IIS, and creating environment variables.

6. Secret Creation: A secret must be created in AWS Secrets Manager to enable the application to securely connect to the database.

Connect to Windows instance via RDP or Session Manager Fleet Manager

To connect to a WorkSpaces Manager Windows instance using RDP or Session Manager Fleet Manager, follow these steps:

Connect via RDP

1. Retrieve the Private IP Address:

   • Copy the private IP if you’re connecting through a VPN, a direct connection, a Jumpbox or a WorkSpace.

2. Use Remote Desktop (RDP):

   • Open the Remote Desktop Connection application on your computer.

   • Enter the IP address of the instance.

   • Use the Administrator username and password to log in.

   • Click Connect to access the instance.

Connect via AWS Fleet Manager

1. Open Systems Manager:

   • In the AWS Management Console, navigate to Systems Manager > Fleet Manager.

2. Locate the Instance:

   • In Fleet Manager, find the WorkSpaces Manager instance you want to access.

   • Select the instance and click Node Actions, then choose Connect with RDP client if RDP access is configured.

3. Session Manager Connection (if using an SSM agent and permissions):

   • If Session Manager is enabled, click Connect within Fleet Manager, and you’ll be able to manage the instance directly without needing an IP address or RDP client.

These options allow you to access and manage the WorkSpaces Manager instance depending on your network setup and access preferences.

Join WorkSpaces Manager instance to the Active Directory Domain

Before configuring WorkSpaces Manager, it is required to join it to an Active Directory Forest. This integration ensures that the manager can interact with user accounts, groups, and other resources within the directory, enabling full functionality and proper access control.

To join WorkSpaces Manager to an Active Directory (AD) domain, you have several options. Joining it to AD requires a service account with appropriate permissions. Here are some common methods:

System Properties on Windows

• Open System Properties on the WorkSpaces Manager instance (right-click on This PC > Properties > Change settings).

• Under the Computer Name tab, click Change to join a domain.

• Enter the domain name and provide the service account credentials with permissions to add computers to the domain.

• Restart the instance to apply changes.

PowerShell Commands

• Run PowerShell as an administrator on the WorkSpaces Manager instance.

• Use the Add-Computer cmdlet to join the instance to the AD domain:

  Add-Computer -DomainName "yourdomain.com" -Credential (Get-Credential)

• Enter the service account credentials when prompted.

• Restart the instance after joining the domain.

AWS Systems Manager (SSM)

• If AWS Systems Manager is enabled, go to Run Command in the AWS Console.

• Use the AWS-JoinDirectoryServiceDomain document to join the WorkSpaces Manager instance to an AD domain managed by AWS Directory Service.

• Provide the domain name, organizational unit (OU), and service account credentials.

• Systems Manager will handle the domain join and restart if needed.

Required Permissions for the Service Account

The service account should have:

• Permissions to join computers to the AD domain.

• Read and write permissions within the Organizational Unit (OU) where the WorkSpaces Manager will reside.

• Access to create computer objects in AD, if necessary.

These methods allow you to join WorkSpaces Manager to your Active Directory domain, ensuring it can integrate with your existing user and resource structures.

Connect to SQL Server Management Studio (SSMS)

To connect to the PortalCore database using SQL Server Management Studio (SSMS), ensure you are logged in as a Windows Administrator, as the BUILTIN\Administrators group is enabled.

• For the Server name, leave the default hostname or use: localhost\SQLEXPRESS.

This configuration enables direct access to the SQL Server instance on the local machine, allowing you to manage the PortalCore database and its users effectively.

By default, an account is available for connecting to the database to begin initial configuration. Use the following details to connect:

• Server name: use the local hostname by default.

• Authentication: Windows Authentication.

Because the group BUILTIN\Administrators is part of the management setting of MS SQL, a local administrator will have access to the SQL Instance.

New Microsoft Connection Security requires to set an encryption level. Depending on the choise, this requires to have certificates installed, so if this issue is shown:

Make sure that Encryption is set to Optional:

Once connected to SQL Server Management Studio (SSMS):

1. In the Object Explorer panel on the left, locate the connected server instance.

2. Expand the Databases node by clicking the plus sign (+) next to it.

3. Scroll through the list to ensure the PortalCore database is present.

If the PortalCore database is not listed, it may require additional steps may be required to set it up.

Recommended: change password for Database administrator

To change the password for the NuvensDBA account in the PortalCore database in SQL Server Management Studio (SSMS), follow these steps:

1. Open SQL Server Management Studio (SSMS) and connect to your SQL Server instance.

2. Navigate to Security:

   • In Object Explorer, expand the Security folder under the server level.

   • Select Logins.

3. Locate NuvensDBA:

   • Right-click on NuvensDBA and select Properties.

4. Change Password:

   • In the Login Properties window, go to the General page.

   • Enter the new password in the Password and Confirm Password fields.

5. Click OK to save the changes.

This updates the password for the NuvensDBA account in the PortalCore database.

Optional: Download and Install AWS CLI v2

The AWS CLI is a valuable tool for ensuring that WorkSpaces Manager has access to essential AWS endpoints. Nuvens recommends installing it on the same appliance.

To download and install AWS CLI v2 on Windows, follow these steps:

1. Download AWS CLI v2:

   • Download and install AWS CLI v2 for Windows from the official AWS CLI v2 installation page: Install AWS CLI v2 for Windows.

2. Run the Installer:

   • Locate the downloaded AWSCLIV2.msi file and double-click it to start the installation.

   • Follow the on-screen prompts in the setup wizard to complete the installation.

3. Verify the Installation:

   • After installation, open Command Prompt or PowerShell.

   • Run the following command to verify the AWS CLI version:

   aws --version

This should return the installed version of AWS CLI v2, confirming that it's successfully installed. You can now use the AWS CLI to manage your AWS resources from the command line.

Configure Secrets for Database Access

To securely store your database credentials in AWS Secrets Manager in the same AWS region in which your WorkSpaces Manager appliance is running, follow these steps:

1. Log in to your AWS Account and open Secrets Manager.

2. Click Store a New Secret.

3. Set the Secret Type to Other type of secret.

4. Choose the Key/Value pairs as Key/Value instead of Plaintext.

5. Enter the database credentials:

   • username: Your database username (e.g., NuvensDBA).

   • password: The password assigned to the username.

6. For the database configuration, enter the following details:

   • engine: sqlserver

   • dbname: PortalCore

   • port: 1433

   • host: Enter the IP address of the EC2 instance and the SQL instance name (e.g., localhost\SQLEXPRESS if SQL is running locally).

7. Complete the secret storage process by following the remaining prompts to securely save the credentials in AWS Secrets Manager.

8. Click next, set the Secret name i.e. prod/WSMv6 click Next and Store.

After entering the database credentials and configuration details, follow these steps to complete the process:

1. Click Next.

2. Set the Secret Name (e.g., prod/WSMv6).

3. Click Next to review your settings.

4. Once everything is verified, click Store to save the secret securely in AWS Secrets Manager.

Your database credentials are now securely stored and ready for use in WorkSpaces Manager.

Ensure that the role attached to the instance has the necessary permissions to read secrets from AWS Secrets Manager. You can verify this using AWS CLI v2.

To create a secret via command-line using AWS CLI v2, execute the following commands:

Microsoft Powershell

aws secretsmanager create-secret `
    --name "prod/WSMv6" `
    --description "prod/WSMv6" `
    --region "eu-central-1" `
    --secret-string '{\"username\":\"NuvensDBA\",\"password\":\"strongpassword123\",\"engine\":\"sqlserver\",\"port\":\"1433\",\"dbname\":\"PortalCore\",\"host\":\"localhost\\SQLEXPRESS\"}'

Please note, to properly store multiple key/value pairs instead of plaintext data, the backslash character (\) is used as an escape character. Since there is a backslash in the "host" key (localhost\SQLEXPRESS), you will need to use two backslashes (\\) to represent a single one.

Linux Bash

aws secretsmanager create-secret --name prod/WSMv603 --description "prod/WSMv6" --region eu-central-1 --secret-string "{\"username\":\"NuvensDBA\",\"password\":\"strongpassword123\",\"engine\":\"sqlserver\",\"port\":\"1433\",\"dbname\":\"PortalCore\",\"host\":\"localhost\\\\SQLEXPRESS\"}"

Please note, to properly store multiple key/value pairs instead of plaintext data, the backslash character (\) is used as an escape character. Since there is a backslash in the "host" key (localhost\SQLEXPRESS), you will need to use four backslashes (\\\\) to represent a single one.

This will securely store your database credentials in AWS Secrets Manager. After executing the command, you can verify that the secret was created by visiting AWS Secrets Manager in the AWS Management Console or by using the following AWS CLI command:

aws secretsmanager get-secret-value --secret-id prod/WSMv6 --query SecretString --output text

Verify Access to AWS Secrets Manager from WSM Appliance

To verify that the role attached to a Windows EC2 instance has permissions to read secrets from AWS Secrets Manager using AWS CLI v2, follow these steps:

1. Open PowerShell:

   • Log into the EC2 instance via RDP.

   • Open PowerShell as an administrator and run command:

   • aws secretsmanager get-secret-value --secret-id prod/WSMv6

2. Verify Role Permissions Using AWS CLI v2:

   • Run a command in PowerShell to check if the instance can retrieve the secret from AWS Secrets Manager.

3. Expected Output:

   • If the permissions are correct, the command will return the secret’s value.

   • If the permissions are not sufficient, it will display this error message.

   
4. Add IAM Policy to the Instance Role:

   • If the role attached to the instance does not have sufficient permissions, add the appropriate policy to the role via the IAM Console with the following JSON:

   • {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Action": [
             "secretsmanager:GetSecretValue",
             "secretsmanager:DescribeSecret"
           ],
           "Resource": "*"
         }
       ]
     }

5. Attach the Policy:

   • Go to IAM in the AWS Management Console.

   • Locate the role attached to your EC2 instance.

   • Attach the policy that allows access to Secrets Manager.

By running the AWS CLI v2 command on your Windows instance through PowerShell, you can confirm if the instance has the necessary permissions to access secrets.

Set Environment Variables

On the server, follow these steps to access the environment variables and add two new ones:

1. Search for "Environment Variables":

   • In the Start Menu search bar, type "Environment Variables".

2. Open System Properties:

   • From the search results, click "Edit the system environment variables" to open the System Properties window.

3. Access Environment Variables:

   • In the System Properties window, click the "Environment Variables..." button at the bottom to view and edit the environment variables.

This will allow you to view and modify system and user environment variables.

Click on Advanced, then select Environment Variables at the bottom of the window.

Under System Variables, click New.

• Variable Name: WSMCORE_SECRET_KEY

• Variable Value: Enter the name of the secret you stored (e.g., prod/WSMv6).

Click OK to save the new environment variable.

Click again New.

• Variable Name: WSMCORE_REGION

• Variable Value: Enter the code for the AWS Region where WSM is running (e.g., eu-central-1).

Click OK to save the new environment variable.

This will set the WSMCORE_SECRET_KEY and WSMCORE_REGION environment variables with the right values, which we can verify by listing all environment variables executing the command:

Powershell

Get-ChildItem Env:

Command Prompt

set

To create the system environment variable via PowerShell, use the following commands:

[System.Environment]::SetEnvironmentVariable('WSMCORE_SECRET_KEY', 'prod/WSMv6', [System.EnvironmentVariableTarget]::Machine)

[System.Environment]::SetEnvironmentVariable('WSMCORE_REGION', 'eu-central-1', [System.EnvironmentVariableTarget]::Machine)

# Verify that the environment variables were created
Get-ChildItem Env:

Reset Internet Information Service (IIS)

• Open Command Prompt:

  • Right-click Command Prompt and select Run as Administrator.

• Run the IIS Reset Command:

  • In the Command Prompt window, type the following command and press Enter:

iisreset

This will reset IIS to apply any changes made.

Configure Database for WSMv6

• Open a Web Browser:

  • Navigate to http://localhost to access the PortalCore site.

• Check for Database Connected:

  • Check to see if the database is connected if it is not you will see an option to Build Database click and wait for the process to finish.

• Complete the Setup:

  • Once the database build is complete, click Continue to proceed.

• Identify Connection Errors:

  • If you encounter any connection errors, they might be caused by misconfigured environment variables or missing roles for IIS.

• Recommended Reboot:

  • To resolve this, it's recommended to perform a healthy reboot of the system by running the following command in Command Prompt (as Administrator):

shutdown /r /f /t 0

1. Enter Administrator Account Details:

   • Fill in the necessary information to create the Administrator account (e.g., username, password, email).

   • Click the Create Account button to finalize the creation of the Administrator account and move you to the next step.

2. Click Continue:

   • Once the Administrator account is created, click Continue to proceed with the setup process.

1. Input Your License Key:

   • Enter the license key provided for Workspaces Manager.

2. Fill in the Required Information:

   • Complete all necessary fields to configure Workspaces Manager, such as server details, admin credentials, or any other settings.

3. Click "Create Configuration":

   • Once all the information is filled out, click "Create Configuration" to finalize the setup process.

1. Check for Confirmation:

   • If everything is configured correctly, a confirmation message will appear.

2. Click "Continue":

   • After the confirmation appears, click "Continue" to proceed to the next step.

1. Setup Complete:

   • The configuration process is now finished.

2. Click "Login":

   • Click the "Login" button to access the Workspaces Manager Portal and begin using the system.

On your first login navigate to Update, select WorkSpaces to push an update to retreive data quicker.