R&S® TrustedGate System Management Tool

General

What is the R&S®Trusted Gate System Management Tool?

The R&S®Trusted Gate System Management Tool is designed to make the deployment and initial configuration of any R&S®Trusted Gate setup as easy as possible. This includes also the deployment of the cloud resources needed for the setup.

The tool supports the deployment on Linux (RHEL) and Windows Server VMs.

Currently supported solutions:

  • R&S®Trusted Gate Solution for Teams (Standard and Enterprise Edition, click here to see differences)
  • R&S®Trusted Gate Solution for Microsoft 365
How does the tool work?

The R&S®Trusted Gate System Management Tool is based on Ansible. Therefore, the machine running the tool must be able to connect to your VMs on which the installation should be performed via the internet. To secure this connection, you need to enable SSH access on your machines with certificate authentication.

On VMs running Windows Server, the tool uses WinRM secured over https.

How can I use this tool?

The R&S®Trusted Gate System Management Tool is completely integrated into the Azure Marketplace. After the deployment of one of our solutions to your subscription, you get a single VM with the preinstalled tool and preconfigured RDP access. The credentials for the RDP connection are set by yourself during the deployment.

The VM serves the System Management Tool. You can connect to the tool via your favourite browser by simply accessing the VM’s configured hostname.

How do I prepare Windows Server VMs?

Windows Server VMs need to have WinRM enabled in order to work with this tool. Please note that currently only WinRM secured via HTTPS (Port: 5986)  and username/password authentication is supported.

For the automatic configuration of WinRM, you can use the powershell script you can find here.

 

Installation of the tool out of Azure Marketplace

You can deploy the System Management directly out of the Azure Marketplace. During the deployment, you set a hostname and a password for the tool.

After the deployment has succeeded, you can connect to it via https://<CONFIGURED_HOSTNAME> .The login credentials are “admin” with the password you have entered during deployment.

Installation of the tool directly via Docker

You can run the System Management tool directly on your own computer or laptop. The only prerequisite to be fulfilled here is a working Docker setup.

After you have executed the installation of the container, it takes approximately 5 minutes to start. Afterwards you can connect to https://localhost and login with the username ‘admin’ and the password you have configured in the command.

You need to ignore the https security warning, as the tool is delivered with a self-signed certificate.

Windows setup:

  • Install Docker according to this manual
  • Create the folders C:\smt\conf, C:\smt\database, C:\smt\projects, C:\smt\nginx
  • Replace <INSERT-PASSWORD-HERE> with a password of your choice and run the following command:
docker container run --name awx_web -e updated_password=<INSERT-PASSWORD-HERE> -e cert_hostname=localhost -d -h awx_web -u root -p 80:8052 -p 443:8053 -v C:\smt\conf:/etc/tower -v C:\smt\nginx:/etc/nginx -v C:\smt\database:/var/lib/pgsql/data -v C:\smt\projects:/var/lib/awx/projects --restart unless-stopped systemmanagementtool.azurecr.io/tool/smt-container

Linux setup:

  • Chose your distribution here and install docker accordingly
  • Create the folders /etc/smt/conf, /etc/smt/database, /etc/smt/projects and /etc/smt/nginx
  • Replace <INSERT-PASSWORD-HERE> with a password of your choice and run the following command:
docker container run --name awx_web -e updated_password=<INSERT-PASSWORD-HERE> -e cert_hostname=localhost -d -h awx_web -u root -p 80:8052 -p 443:8053 -v /etc/smt/conf:/etc/tower -v /etc/smt/nginx:/etc/nginx -v /etc/smt/database:/var/lib/pgsql/data -v /etc/smt/projects:/var/lib/awx/projects --restart unless-stopped systemmanagementtool.azurecr.io/tool/smt-container;
Requirements for target VMs

The System Management Tool allows you to choose between installing Trusted Gate on either newly created Azure VMs or provide your own. If you choose the latter, please make sure the provided VMs fulfill the following requirements:

  • At least 4 CPU cores
  • At least 8 GB of RAM
  • Working network connection from the machine running the System Management Tool to the VM

Windows-specific requirements:

  • Windows Server 2016 or 2019
  • WinRM installed and activated (manual can be found here)

Linux-specific requirements:

  • Enterprise Linux (ideally CentOS) with yum as package manager
  • sudo user access
  • SSH key to access the VM

Installation steps

Upload license file

To start with the installation process, you need to get a license file and upload it in this step.

You can get in contact with our sales team to obtain such a license via https://hub.trustedgate.de.

With this step, the System Management Tool validates your uploaded license and sends an access request to our resources server where the installation files for Trusted Gate are stored. After we processed this request you will receive a confirmation along with a set of credentials to use in the next step from our sales team.

Connect to resources storage

This step verifies whether your System Management Tool is able to connect to our resource storage, yet. It can only succeed after your access request issued during the first step has been granted by our staff.

Please enter the credentials you received with the confirmation and click “Continue” to move on to the next step.

Download installation material

In this step you need to select the Trusted Gate solution and the version to be installed.

Please select only the solution for which you have received your license. Other solutions will fail the installation, eventually.

Based on your selection, the System Management Tool will download the required installation material from our servers.

Configure VM setup

In this step you need to enter general information about your desired setup.

First, please enter the number of VMs to install your selected Trusted Gate solution to. This can be one single VM but we recommend to at least separate the Administration server from the other microservices.

Then, please enter a username to access the target VMs with. If you choose to provide your own VMs the entered user needs to have root privileges.

Based on your input, the System Management Tool will then generate the next installation step.

Configure target VMs

In this step you are asked to further specify your desired VM setup.

For the number of VMs selected in the previous step, please enter:

  • whether the System Management Tool should automatically create a new Azure VM for you or if you will provide it yourself
  • the operating system that is running or should be running on the VMs of your choice
  • (Windows or self-provided CentOS VMs only) a password to use with the username provided in the previous step
  • (self-provided VMs only) the VM’s fully qualified domain name

If you want to create one or more VMs automatically in Azure, you need to choose the region and the size for this VM. Please note, the VM(s) will be deployed to your subscription and thus may induce additional costs.

Finally, you will need to enter a DNS prefix that will be used for the VM. The tool will check afterwards whether the prefix is available.

Based on your input, the System Management Tool will then generate the next installation step.

Upload SSH keys

This step is only required if at least one of your VMs chosen in the previous step will run CentOS.

The System Management Tool requires a SSH key pair to connect with CentOS VMs.

For self-provided VMs, you will need to set up SSH on each of them yourself and provide the System Management Tool with the matching access key.

For VMs to be automatically created in Azure, the uploaded key pair will be copied to the deployed VMs automatically.

Please note, all input to this form is completely optional. If you leave all fields blank the System Management Tool will automatically generate a key pair for you to download in the following step.

Please keep this key pair secure as it is needed to access your VMs.

Download generated SSH keys

This step is only required if you chose to have the System Management Tool generate a SSH key pair for you in the previous step.

Please download and save the zipped key pair in a secure location. Without it, you might not be able to access your VMs in the future. Likewise, any attackers might be able to penetrate your setup with access to this key pair.

Afterwards, please click “Continue”. The System Management Tool will then prepare the next installation step.

(Azure) Enter Azure account data

This step is only required if you chose to have at least one VM automatically created in Azure by the System Management Tool.

To create the VMs on your behalf the installer needs you to provide a set of valid Azure credentials. This account must have permission to create new VMs and storage accounts under your Azure subscription.

The System Management Tool will then try to access Azure with the provided credentials and request the available subscriptions for you to select in the following installation step.

Please note, the System Management Tool will not save your Azure credentials. Once the chosen VMs have been created they will be deleted automatically.

(Azure) Create Azure VMs

This step is only required if you chose to have at least one VM automatically created in Azure by the System Management Tool.

Please select the Azure subscription and enter the name of the resource group you want to use for the VM deployment. Azure will then automatically append a region identifier to the resource group name you provide (e.g. “TrustedGate-Solution-A-westeurope” for the given resource group name “TrustedGate-Solution-A”).

The System Management Tool will then issue the creation of the Azure VMs based on your input in this and any previous step.

Assign components to VM

Depending on your selected Trusted Gate solution, there are multiple components to be installed. This step asks you to assign these components to the availabe VMs.

You can install multiple components on a single VM. However, we propose to keep the Administration service separated from any other component on its own VM.

Additionally, you need to choose whether you will provide Trusted Gate with your own server certificates or if you want the System Management Tool to obtain them for you automatically for you via Let’s Encrypt.

While the latter usually is the easiest choice, Let’s Encrypt requires the target VMs to be reachable from the internet on port 80. In our experience, this is oftentimes overseen in on-premise installations.

Based on your input the System Management Tool will then prepare the next installation step.

Download server certificate signing requests

R&S®Trusted Gate Solutions for Teams and Microsoft 365 operate a reverse proxy. Doing so, they need to pretend to client software that they are the original servers. For this, Trusted Gate needs a special certificate which contains Subject Alternate Name (SAN) entries for the network requests it intercepts.

To make the creation of the required certificates as easy as possible for you, the System Management Tool provides you with a certificate signing request (CSR) containing the necessary entries as well as the matching private key. The CSR(s) must be signed by your internal company’s certificate authority so that all clients in your network will trust your deployed Trusted Gate solution.

If you chose to import your own certificates in the previous step, the compressed archive you need to download in this step will also contain CSRs for all other VMs you have chosen to use in your setup.

On instructions how to sign the CSR with a Windows CA, click here.

On instructions how to sign with OpenSSL, click here.

Afterwards, please click “Continue”. The System Management Tool will then prepare the next installation step.

Upload signed certificates

For each of the CSRs downloaded in the previous step, you are now required to upload a certificate signed by your company’s certificate authority (CA) as well as the respective private key that matches the certificate.

Finally, the System Management Tool requires you to upload the certificate of the CA you have signed the CSRs with.

Afterwards, please click “Continue”. The System Management Tool will then prepare the next installation step.

Install Solution for Teams on VMs

With this step, the System Management Tool will perform the actual installation of your selected Trusted Gate solution.

To do so, the tool requires you to enter the hostnames of your Sharepoint Online and OneDrive instances (e.g. “yourcompany.sharepoint.com” and “yourcompany-my.sharepoint.com”).

Additionally, you are asked to enter a valid email address with which to receive any renewal information for the certificates used internally by Trusted Gate.

If your solution includes a reverse proxy that shall be installed on a CentOS VM, the System Management Tool will offer you to deploy a dedicated DNS server to be used by your client machines. This DNS server will be installed on the same VM that runs the reverse proxy and automatically overwrites all necessary entries.

Afterwards, please click “Continue”. The System Management Tool will then install your selected solution on the VM setup configured.

Install Solution for Microsoft 365 on VMs

With this step, the System Management Tool will perform the actual installation of your selected Trusted Gate solution.

To do so, the tool requires you to enter the hostname of your Sharepoint Online instance (e.g. “yourcompany.sharepoint.com”).

Additionally, you are asked to enter a valid email address with which to receive any renewal information for the certificates used internally by Trusted Gate.

If your solution includes a reverse proxy that shall be installed on a CentOS VM, the System Management Tool will offer you to deploy a dedicated DNS server to be used by your client machines. This DNS server will be installed on the same VM that runs the reverse proxy and automatically overwrites all necessary entries.

Afterwards, please click “Continue”. The System Management Tool will then install your selected solution on the VM setup configured.

Initialize Microservices

Once all components are installed, the System Management Tool can automatically initialize them for you.

To do so, please enter a password to be set for login to the Trusted Gate Administration service.

After this step has been executed successfully, your Trusted Gate solution is ready for use.

You can then connect to the Administration service by accessing https://<ADMIN-HOST>:8443/TrustedGate-admin (where <ADMIN-HOST> is the hostname of the VM on which your administration service was installed to). The default admin user is “Admin1“. The password has been set to the value you provided in this step.

Download backup package

Although you Trusted Gate solution has been installed and initialized, we recommend to use this step to download a backup of all relevant information about your setup. This includes the application and SSH keys, any certificates and a summary of all parameters you entered into the System Management Tool during this installation.

Please keep these files in a secure location. Without it, you might not be able to access your VMs in the future. Likewise, any attackers might be able to penetrate your setup with access to this backup.

Manual installation Steps

Connect to a VM via SSH from Linux client

To connect to a VM via SSH from a Linux client with a private key, simply use the command “ssh -i <path-to-private-key> <your-user>@<your-vm>”. Please note that the private key file needs to have permissions 600 (to apply these permissions, use “chmod 600 <path-to-private-key>”.

Connect to a VM via SSH from Windows client
To connect to a VM via SSH from a Windows client you need additional software like PuTTY.

After you have installed PuTTY, open it and enter the following data:

  • In tab Session:
    • Host Name of your VM
  • In tab Connection -> Data:
    • auto-login username: the name of the user as which you want to the VM
  • In tab Connection -> SSH -> Auth:
    • Private key file for authentication: Enter the path of your .ppk private key file

After you have entered this data, you should be able to connect to the VM via the button “Open”.

You need to convert your SSH key first to Putty’s .ppk format according to the instructions described here.

Convert a SSH private key to PuTTY's .ppk format

To connect to a VM via PuTTY, you need the private key as .ppk file.

After you’ve installed PuTTY, you should be able to launch PuTTYgen via the Windows programs list

  • Click “Conversions” from the PuTTY Key Generator menu and select Import key.
  • Navigate to the OpenSSH private key and click “Open”.
  • Under “Actions / Save the generated key” select “Save private key”
  • Save the private key to the desktop as “id_rsa.ppk” to a path of your choice.

You can now connect to the VM via Putty using the converted key.

Getting started

Change user credentials

You can change an user’s login credentials via the R&S®Trusted Gate security administration server.

Login to the administation server on https://<ADMIN_URL>:8443/TrustedGate-admin with your admin user (Default: Admin1, 123456). Navigate to Entities –> Users, select the user for which you want to change the password and click “Edit”.

In the following dialog, set the password and the password confirmation to a new password of your choice and click “Save”.

Add new user

You can create a new user via the R&S®Trusted Gate security administration server.

Log in to the administation server on https://<ADMIN_URL>:8443/TrustedGate-admin with your admin user (Default: Admin1, 123456). Navigate to Entities –> Users and click “Create”.

Set the following values in the opened form and click “Save”:

  • Name: Unique name for the user to be created
  • Password: Strong password for the user to be created
  • Role: User or Advanced User
    • Advanced Users are able to create project rooms and share data with externals
  • Groups: Select the groups the user should belong to – usually, this should be the DefaultDocEncGroup (If you haven’t already created new groups)
Create external user

To use the R&S®Trusted Gate Solutions for Teams, SharePoint and Microsoft 365, you need to map the external users to internal users. This can be done via the R&S®Trusted Gate security administration server.

Log in to the administation server on https://<ADMIN_URL>:8443/TrustedGate-admin with your admin user (Default: Admin1, 123456). Navigate to Entities –> External User Mappings and click “Create”.

In the form, enter the name of your external user (e.g. your-user@your-org.onmicrosoft.com) and select the internal user to which it shall be mapped. Afterwards, click “Save”.

Manipulating DNS resolving on Clients via hosts file

The client machines on which Microsoft Teams, Microsoft 365 or SharePoint are accessed need to be routed to the server running the reverse proxy instead of the official servers. Else, your files won’t be encrypted.

One way to achieve this is to manually edit the hosts file located in C:\Windows\System32\drivers\etc\hosts. Add the following lines to the file (subtitute <Reverse_Proxy_IP> with the IP of the server running your Reverse Proxy service):

For R&S®Trusted Gate Solution for Teams:

  • <Reverse_Proxy_IP> <your-server>.sharepoint.com
  • <Reverse_Proxy_IP> <your-server>-my.sharepoint.com
  • <Reverse_Proxy_IP> northeurope1-mediap.svc.ms
  • <Reverse_Proxy_IP> teams.microsoft.com
  • <Reverse_Proxy_IP> emea.ng.msg.teams.microsoft.com
  • <Reverse_Proxy_IP> ukwest-prod.notifications.teams.microsoft.com
  • <Reverse_Proxy_IP> westeurope.notifications.teams.microsoft.com
  • <Reverse_Proxy_IP> uksouth-prod.notifications.teams.microsoft.com
  • <Reverse_Proxy_IP> northeurope-prod-2.notifications.teams.microsoft.com
  • <Reverse_Proxy_IP> westeurope-prod-3.notifications.teams.microsoft.com
  • <Reverse_Proxy_IP> westeurope-prod-4.notifications.teams.microsoft.com
  • <Reverse_Proxy_IP> francecentral-prod.notifications.teams.microsoft.com
  • <Reverse_Proxy_IP> eu-prod.asyncgw.teams.microsoft.com

For R&S®Trusted Gate Solution for Microsoft 365:

  • <Reverse_Proxy_IP> <your-server>.sharepoint.com

For R&S®Trusted Gate Solution for SharePoint:

  • <Reverse_Proxy_IP> <your-sharepoint-hostname>

 

 

Manipulating DNS resolving on Clients via DNS server

The client machines on which Microsoft Teams, Microsoft 365 or SharePoint are accessed need to be routed to the server running the reverse proxy instead of the official servers. Else, your files won’t be encrypted.

One way to achieve this is to set an own DNS server for your Clients. This DNS server needs to overwrite the following DNS-entries and resolve them to the IP of your server running the reverse proxy:

For R&S®Trusted Gate Solution for Teams:

  • teams.microsoft.com
  • *.ng.msg.teams.microsoft.com
  • *.notifications.teams.microsoft.com
  • sharepoint.com
  • *.sharepoint.com
  • *.svc.ms
  • *.asyncgw.teams.microsoft.com

For R&S®Trusted Gate Solution for Microsoft 365:

  • *.sharepoint.com

For R&S®Trusted Gate Solution for SharePoint:

  • <your-sharepoint-hostname>

For your convenience, you can also choose to deploy a DNS server with the correct configuration automatically during the installation process.

Signing a certificate using OpenSSL
  • Create a folder CA and navigate to this folder. All operations are executed inside of this folder
  • Create a file ca.cnf with the following content
[ ca ]
default_ca = ca_default
[ ca_default ]
dir = ./ca
certs = $dir
new_certs_dir = $dir/ca.db.certs
database = $dir/ca.db.index
serial = $dir/ca.db.serial
RANDFILE = $dir/ca.db.rand
certificate = $dir/ca.crt
private_key = $dir/ca.key
default_days = 365
default_crl_days = 30
default_md = md5
preserve = no
policy = generic_policy
copy_extensions = copyall
[ generic_policy ]
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = optional
organizationalUnitName = optional
commonName = optional
emailAddress = optional

  • Create the CA database directory and some other necessary directories and files (it will hold information about all the certificates you issue):
mkdir ca
cd ca
mkdir ca.db.certs
touch ca.db.index
echo "1234" > ca.db.serial
  • Generate a 2048-bit RSA private key for the CA:
openssl genrsa -des3 -out ca/ca.key 2048
  • Create a self-signed X509 certificate for the CA (the CSR will be signed with it):
openssl req -new -x509 -days 10000 -key ca/ca.key -out ca/ca.crt
  • Sign each CSR:
openssl ca -config ca.conf -out <your-certificate>.crt -infiles <your-csr>.csr

Signing a certificate using Microsoft Windows CA

When you have a Windows Active Directory service running, you can use the internal CA to sign the certificate requests:

  • Connect to the server running your Windows AD
  • Open a shell and navigate to the folder where your signing requests are stored
  • Rename the file extension of your signing requests from .csr to .txt
  • Execute the following command:
certreq -attrib "CertificateTemplate:webserver" -submit .\<your-signing-request>.txt
  • Select your CA in the pop-up window and click OK
  • Your certificate is now automatically generated in the same folder as the request with the filename cert.cer
Exporting ROOT certificate from Microsoft Windows CA

To export the ROOT certificate of your Microsoft Windows Active Directory service, perform the following steps:

  • In the AD server, launch the Certificate Authority application by Start | Run | certsrv.msc.
  • Right click your CA and select Properties.
  • On the General tab, click View Certificate button.
  • On the Details tab, select Copy to File.
  • Follow through the wizard, and select the Base-64 encoded X.509 (.CER) format.
  • Click browse and specify a path and filename to save the certificate.
  • Click  Next button and click Finish.
  • The ROOT certificate is now stored in the configured location.