TeamViewer DEX Platform configuration

TeamViewer DEX Platform adheres to two widely used industry standards for authorization: Basic Authentication and OAuth 2.0.

In Basic Authentication, users are required to provide their username and password when making a request to access user accounts. In contrast, Open Authorization (OAuth) eliminates the need to share passwords; instead, OAuth uses authorization tokens to verify a user's authenticity.

It is important to configure your Platform for your specific authentication type before implementing the TeamViewer DEX Core application.

The tasks listed below may take some time to complete, depending on how your organization works. For a more complete checklist of tasks, refer to Prerequisites.

Follow the steps below for Platform configuration and adding ServiceNow Consumer:

  1. Install Platform

    For information on installing the Platform (on-premises), refer to Requirements and Installing 1E.

    1. Disable two-factor authentication

      The two-factor authentication (2FA) feature must be disabled in Platform. This feature prompts users for an authentication code for each instruction request, which is not supported by Platform.

      If you have not yet installed Platform, do not enable 2FA during the 1E Server Setup, as 2FA is disabled by default.

      If you have already installed Platform with 2FA enabled, request your 1E administrator to disable the feature through the 1E Coordinator service.

    1. Check your license

      To ensure the TeamViewer DEX Core app functions properly with Platform, you must have a license that includes the ServiceNow consumer. Without this, authentication errors will occur in the TeamViewer DEX Core application.

      If you have not yet installed Platform, you will need to obtain a license file and verify it using the following steps:

      1. Open your Tachyon.lic license file using Notepad.

      2. Confirm the following consumer exists in the features section (there will also be other consumers in this section):

        Copy 
        <Feature name="TachyonPlatform">
         ...         
               <Consumer name="1EServiceNowCore" enable="on"> </Consumer>        
         ...        
         </Feature>

      3. If the above is not there, then you should contact TeamViewer Support Portal to get an updated license file.

      If you have already installed Platform, check your license as follows:

      1. Log in to the Platform as an Administrator using the Settings app and navigate to Configuration > License information.

      2. Check that a feature with the name ServiceNow-Integration exists and whether it has the 1EServiceNowCore consumer.

      3. If it is not there, contact TeamViewer Support Portal to get your license updated.

      4. If your Platform instance has access to the Licensing service via the internet, then your license will be updated automatically.

  1. Enable basic authentication

    All access to the Platform by third-party applications goes through 1E's Consumer API. To allow the ServiceNow proxy user account to access Platform, you must enable basic authentication on the Consumer API in IIS. This is done in two steps:

    1. Ensure that the Basic Authentication role is installed for IIS.

    2. Enable Basic Authentication on the Consumer and Experience Analytics web applications on the 1E website.

    The following PowerShell script ensures that the basic authentication role is installed, enabled, and then applied to the 1E Consumer API:

    Copy 
    <# 1E Ltd Copyright 2022
    Disclaimer: 
    Your use of this script is at your sole risk. This script is provided "as-is", without any warranty, whether expressor implied, of accuracy, completeness, 
    fitness for a particular purpose, title or non-infringement, and is notsupported or guaranteed by 1E. 1E shall not be liable for any damages you may 
    sustain by using this script, whetherdirect, indirect, special, incidental or consequential, even if it has been advised of the possibility of such damages.
    #>

    Import-Module ServerManager
    Write-Host 'Install Basic Authentication'
    Get-WindowsFeature | Out-file $PSScriptRoot\ServerManager-3.txt -Append
    Install-WindowsFeature Web-Basic-Auth
    Get-WindowsFeature | Out-file $PSScriptRoot\ServerManager-4.txt -Append

    Write-Host ''
    Write-Host 'Enable Basic Authentication'
    Set-WebConfigurationProperty -filter "/system.webServer/security/authentication/BasicAuthentication" -name Enabled -value True -PSPath "IIS:\" -location "Tachyon/Consumer"
    Set-WebConfigurationProperty -filter "/system.webServer/security/authentication/BasicAuthentication" -name Enabled -value True -PSPath "IIS:\" -location "Tachyon/Experience"
    Write-Host 'Done'

    Instead of running the script above, you can also follow these steps:

    1. Ensure that the Basic Authentication IIS role is installed on the server hosting the 1E website. If it is not, add the role to the server.

    1. Open Internet Information Services (IIS) Manager.

      You need to perform the following steps for both the Consumer and Experience Analytics web applications. The following shows the steps for Consumer.

    2. Before enabling Basic authentication on the 1E Consumer site, ensure that it is configured to use HTTPS.

      1. Navigate to the Sites > Tachyon > Consumer node.

      2. Double-click SSL Settings.

      • Confirm that the Require SSL checkbox is checked.

      • Navigate back to the Sites > Tachyon > Consumer node.

    3. Having checked that the site is configured to use HTTPS, we can now enable Basic Authentication.

      1. Double-click Authentication.

      1. Right-click Basic Authentication and select the Enable option from the context menu.

      2. The Basic Authentication Status should now display Enabled. An alert may appear that can safely be ignored.

        Repeat the above steps for the Experience Analytics web application.

  1. Adding the ServiceNow consumer

    The TeamViewer DEX Core application is a 1E consumer that interacts with Platform using the REST services provided in the API. The consumer for the TeamViewer DEX Core application is called 1EServiceNowCore, which must be added to 1E using the following steps after Platform is installed:

    1. Log in to the Settings app using a user account that has at least a Consumer Administrators role.
    2. Navigate to Configuration > Consumers.
    3. Click Add.
    1. The new consumer should be configured with the default values, except for the following:

      Parameter

      Value

      Name

      1EServiceNowCore

      Consumer URL

      This can be left blank.

      Maximum simultaneous instructions

      This number should be more than the number of simultaneous instructions you expect to execute in your organization.

      Offload target URL

      This can be left blank.

      Offload timeout sections

      This can be left blank.

      Use Windows Authentication

      This must be checked.

      Enabled

      This must be checked.

    1. Click Add to save the new consumer.

  1. Edit the ServiceNow consumer workflow

    The 1E consumer page does not provide an option to specify the workflow for the TeamViewer DEX Core consumer. This configuration must be performed using SQL Server Management Studio.

    1. Open SQL Server Management Studio and connect to the SQL instance that hosts the 1E Master database.

    2. Open a New Query and paste the below SQL query as given below. No edits are required.

      Copy 
      /* Script to change TachyonMaster Consumer setting */
      USE [TachyonMaster]
      GO
      DECLARE @setting nvarchar(max), @oldvalue nvarchar(max), @newvalue nvarchar(max)
      SET @setting = '1EServiceNowCore'
      SET @newvalue = '[{"ReferenceType":0,"InstructionWorkflow":[{"InstructionType":1,"Workflow":{"StateMachine":"State"}}]}]'
      SET @oldvalue = (SELECT [Workflow] FROM [dbo].[Consumer] WHERE [Name]= @setting)
      UPDATE [dbo].[Consumer] SET [Workflow]=@newvalue WHERE [Name]=@setting
      SELECT @setting AS 'Setting', @oldvalue AS 'Before', [Workflow] AS 'After' FROM [dbo].[Consumer]
      WHERE [Name]=@setting
      GO

    3. Execute the SQL query and confirm the 1EServiceNowCore setting is changed from NULL to the following:

      [{"ReferenceType":0,"InstructionWorkflow":[{"InstructionType":1,"Workflow":{"StateMachine":"State"}}]}]

    1. Close SQL Server Management Studio.

Follow the steps below to configure your Platform and ServiceNow instance for OAuth (both single and multi-tenant):

  1. Download and install the TeamViewer DEX Core application

  2. Carry out the prerequisites

  3. Configure Microsoft Entra ID/Okta and TeamViewer DEX

  4. Prepare the certificates for ServiceNow

  5. ServiceNow OAuth steps:

    • Upload PEM and JKS certificates

    • Configure a JWT signing key

    • Create a JWT provider

For more information on how to configure, refer to Platform provisioning and upgrading guide.

Get the application

To get the latest version of the TeamViewer DEX Core application, choose one of the following options:

  • If you are a new customer, you can get the TeamViewer DEX Core application from the ServiceNow app store. To install the application, refer to App Installation.

  • However, if you already have an older version of TeamViewer DEX Core application on your ServiceNow instance, then refer to Upgrading TeamViewer DEX Core.

Prerequisites

The following information is required for the preparation of certificates:

  1. .pfx certificate (containing a private key, client authentication and 2048 key)

    • This .pfx certificate is given either by your internal PKI team, sometimes by a third party. Or you can generate a self-signed certificate by yourself.

    • To create your own self-signed certificate, use the New-SelfSignedCertificate PowerShell cmdlet. This creates a certificate in the local machine personal certificate store on the device you have run the cmdlet. You can then export this certificate as a .pfx file, which includes the private key, using the CERTLM.MSC utility.

  1. The non-interactive client assertion Application ID from Microsoft Entra ID, as shown in the picture below.

You will need the following tools:

  1. OpenSSL

  2. KeyTool

  3. 1E PowerShell toolkit (available on the TeamViewer Support Portal Portal)

Configure Microsoft Entra ID and Platform

Create certificate/principal mapping in Platform

  1. Install the certificate with the private key locally to the local machine personal certificate store. Ensure that you have the required permissions to access the private key.

  2. Login to your TeamViewer DEX instance using the Set-1E Server as shown below.

  1. Get the certificate kid using:

    Get-1ECertificateThumbprint -StoreName localmachine\my | fl *

    The kid value in a certificate is a URL-safe base 64 encoded version of the certificate's thumbprint.

  1. Take note of the certificate kid and then create a mapping using:

    Add-1EJwtPrincipalMapping -Identifier <Certificate kid> -Principal <1EUser@domain.com>

    Note that the above proxy user should be a Principal with appropriate permissions in Platform.

Upload the public key PEM file to Microsoft Entra ID

  1. Export the certificate that you have imported in the above steps in .CER format.

  2. Login with the administrator principal role.

  3. Navigate to Azure Active Directory > App Registrations > 1E Client Assertion > Certificates and upload the certificate.

Preparing for ServiceNow certificates

Follow the steps below to prepare the certificates:

  1. Convert the .pfx certificate into .PEM and .JKS file types. To convert the .pfx certificate, first install OpenSSL and keytool applications on your machine.

  2. After installing the applications, copy the .pfx certificate in the same directory where these applications reside.

  3. Ensure the path for the device used to convert the certificates includes the bin directories from both Java and OpenSSL and/or that the person doing the conversion uses fully qualified paths to execute the functions.

    Copy the entire contents of the bin folder of OpenSSL into the bin folder of Java.

    The passwords for all conversions must be the same.

  4. Now open the PowerShell/CMD where the .pfx certificate resides and run the following commands:

    • To generate the .PEM file:

    • Copy 
      openssl pkcs12 -in <filename>.pfx -out <filename>.pem

    • To generate the .JKS file:

    • Copy 
      openssl pkcs12 -export -in <filename>.pem -out <filename>.p12 -name MyCert
      keytool -importkeystore -srckeystore <filename>.p12 -destkeystore <filename>.jks -srcstoretype pkcs12 -deststoretype JKS

  1. Note the JKS keystore password for future use.

  2. Upload both PEM and JKS certificates into the certificates table (sys_certificate) in ServiceNow.

ServiceNow OAuth steps

Now on your ServiceNow instance, configure the following OAuth steps:

  1. Upload PEM and JKS certificates

  2. Configure a JWT signing key

  3. Configure a JWT provider

Upload PEM and JKS certificates

To upload the certificates, navigate to System Definition > Certificates and create a new record as shown in the picture below.

To upload the PEM certificate in your ServiceNow instance:

  1. Provide the required details and attach the PEM certificate so that the identity provider can verify communications with the service provider.

  2. Select Type as Trust Store Cert.

  3. Copy the content of the PEM file and paste it into the PEM certificate field.

  4. Click Submit to save the record.

  5. Click Validate Stores/Certificates link to validate the certificate.

  6. Take a note of the SysID of the PEM certificate for future use.

To upload the JKS certificate in your ServiceNow instance:

  1. Provide the required details.

  2. Select Type as Java Key Store.

  3. Attach the JKS certificate generated in the above step to enable the JWT client authentication.

  4. Enter the Key store password.

  5. Click Submit, to save the record.

  6. Click Validate Stores/Certificates link to validate the certificate.

You can see that the certificates are now added to the Certificates table.

Configure a JWT signing key

To configure JWT signing key on your ServiceNow instance, follow the below steps:

  1. Navigate to System OAuth > JWT Keys.

  2. Create a new record for JWT Keys.

  3. Provide a descriptive Name.

  4. Select the JKS certificate uploaded earlier using the look-up list into the Signing Keystore field.

  5. Enter the Keystore password saved earlier into the Signing Key field and click Submit to save the record.

Create a JWT provider

To configure JWT provider on your ServiceNow instance, follow the steps below:

  1. Navigate to System OAuth > JWT Providers.

  2. Create a new record for JWT Providers and fill in the claim values as shown in the picture above.

  3. Ensure that you have the required permissions.

  4. Provide a descriptive Name.

  5. Select the JWT Key created earlier using the look-up list from the Signing Configuration field.

  1. Copy the SysID of the JWT Provider's record for future use. This SysID is passed to retrieve JWT Token.

For more information on how to configure, refer to Platform provisioning and upgrading guide.

Get the TeamViewer DEX Core application

To install the latest version of the TeamViewer DEX Core application, choose from one of the following options:

  1. If you are a new customer, you can get the TeamViewer DEX Core application from ServiceNow app store. To install the application, refer to App Installation.

  2. However, if you already have an older version of TeamViewer DEX Core application on your ServiceNow instance, then refer to Upgrading TeamViewer DEX Core to upgrade your application.

Prerequisite

The following information is required for the preparation of certificates:

  1. .pfx certificate containing a private key

  2. The Client ID from Okta, as shown in the picture below.

The following tools are required:

  1. OpenSSL

  2. KeyTool

  3. 1E PowerShell toolkit (available on the TeamViewer Support Portal Portal)

Configure Okta and Platform

Create certificate/principal mapping in Platform

  1. Install the certificate with a private key locally to the local machine personal certificate store. Ensure that you have the required permissions to access the private key.

  2. Navigate to 1E PowerShell toolkit and import it to the PowerShell window using:

    PS c:\Users\administrator\Downloads\1.2.3> Import-Module .\ps1etoolkit.psd1 - force

  1. Login to your TeamViewer DEX instance using Set-1E Server as

    PS C:\Users\administrator\Download\1.2.3> Set-1EServer Platformtest.appteam.cloud.1e.com

    You will be redirected to the Okta login page where you will be prompted to enter your credentials.

  1. Get the certificate kid using:

    Get-1ECertificateThumbprint-StoreName localmachine\my|fl*.

  1. Now make a note of the kid and then create a mapping using:

    Add-1EJwtPrincipalMapping-Identifier <Certificate kid> -Principal <1EUser@domain.com>

    Note that the above proxy user should be a principal with appropriate permissions in Platform.

Upload the public key PEM file in Okta

  1. Export the certificate that you have imported in the above steps in .CER format.

  2. Login with the administrator principal and upload the certificate in your Okta instance.

Preparing the certificates for ServiceNow

Follow the steps below to prepare the certificates:

  1. Convert the .pfx certificate into .PEM and .JKS file types.

  2. To convert the .pfx certificate, first install OpenSSL and keytool applications on your machine.

  3. After installing the applications, copy the .pfx certificate in the same directory where these applications reside.

  4. Copy the entire contents of the OpenSSL bin folder into the bin folder of Java.

  5. Open the PowerShell/CMD where the .pfx certificate resides and run the following commands:

    • To generate the .PEM file:

      openssl pkcs12 -in <filename>.pfx -out <filename>.pem

    • To generate the .JKS file:

      openssl pkcs12 -export -in <filename>.pem -out <filename>.p12 -name MyCert

      keytool -importkeystore -srckeystore <filename>.p12 -destkeystore <filename>.jks -srcstoretype pkcs12 -deststoretype JKS

  1. Take a note of the JKS keystore password for future use.

  2. Upload both the PEM and the JKS certificates into the certificates table (sys_certificate) in ServiceNow.

ServiceNow OAuth steps

On your ServiceNow instance, configuration of OAuth is done by following the steps below:

  1. Upload the PEM and the JKS certificates.

  2. Configure a JWT signing key.

  3. Configure a JWT provider.

Upload PEM and JKS certificates

To upload the certificates, navigate to System Definition > Certificates and create a new record as shown in the picture below.

To upload the PEM certificate in your ServiceNow instance:

  1. Provide the required details and attach the PEM certificate so that the identity provider can verify communications with the service provider.

  2. Select Type as Trust Store Cert.

  3. Copy the content of the PEM file and paste it into the PEM certificate field.

  4. Click Submit to save the record.

  5. Click Validate Stores/Certificates link to validate the certificate.

  6. Take a note of the SysID of the PEM certificate for future use.

To upload the JKS certificate in your ServiceNow instance:

  1. Provide the required details.

  2. Select Type as Java Key Store.

  3. Attach the JKS certificate generated in the above step to enable the JWT client authentication.

  4. Enter the Key Store password.

  5. Click Submit to save the record.

  6. Click the Validate Stores/Certificates link to validate the certificate.

You can see that the certificates are now added to the Certificates table.

Configure a JWT signing key

To configure a JWT signing key on your ServiceNow instance, follow the below steps:

  1. Navigate to System OAuth > JWT Keys.

  2. Create a new record for the new JWT Keys.

  3. Provide a descriptive Name.

  4. Select the JKS certificate uploaded earlier using the look-up list in the Signing Keystore field.

  5. Enter the Keystore password saved earlier into the Signing Key field and click Submit to save the record.

Create a JWT provider

To configure the JWT provider on your ServiceNow instance, follow the below steps:

  1. Navigate to System OAuth > JWT Providers.

  2. Create a new record for JWT Providers and fill in the claim values as shown in the picture above.

  3. Ensure that you have the required permissions.

  4. Provide a descriptive Name.

  5. Select the JWT Key created earlier using the look-up list in the Signing Configuration field.

  1. Copy the SysID of the JWT Provider's record for future use. This SysID is passed to retrieve the JWT Token.

Adding the ServiceNow consumer

Follow the steps below to add the ServiceNow consumer to the Platform using the PowerShell toolkit: 

Copy the below mentioned PS script in the same folder where PS1Etoolkit is available:

Copy 
clear
Import-Module .\PS1EToolkit -Force
$baseurl = "1estg.stg.preprod.1e.com"
$apiUrl = "https://$baseurl/consumer/consumers"
# Set the server and retrieve the authentication token
Set-1Eserver $baseurl
$token = (Get-1eauthtoken).Token
# Set the headers with the authorization token
$headers = @{
    "X-Tachyon-Authenticate" = "$token"
}
try {
    # Fetch the current consumers
    $response = Invoke-WebRequest -Uri $apiUrl -Method Get -Headers $headers
    $statusCode = $response.StatusCode
    if ($statusCode -eq 200) {
        $consumers = ($response.Content | ConvertFrom-Json)
        $consumer = $consumers | Where-Object { $_.Name -eq "1EServiceNowCore" }
        if ($consumer) {
            # Update the existing consumer using PUT
            $consumer.Workflow = '[{"ReferenceType":0,"InstructionWorkflow":[{"InstructionType":1,"Workflow":{"StateMachine":"State"}}]}]'
            $consumer.IsEnabled = $true
            $consumer.MaximumSimultaneousInFlightInstructions = 50
            $putResponse = Invoke-WebRequest -Uri "$apiUrl" -Method Put -Body ($consumer | ConvertTo-Json) -ContentType "application/json" -Headers $headers
            if ($putResponse.StatusCode -eq 200 -or $putResponse.StatusCode -eq 201) {
                Write-Output "Updated 1EServiceNowCore consumer workflow."
            } else {
                Write-Output "Failed to update 1EServiceNowCore. Status code: $($putResponse.StatusCode)"
            }
        } else {
            # Create a new consumer using POST
            $newConsumer = @{
                Name = "1EServiceNowCore"
                OffloadTargetUrl = $null
                OffloadPostTimeoutSeconds = 60
                OffloadUseWindowsAuth = $null
                ApplicationUrl = $null
                IsEnabled = $true
                SystemConsumer = $false
                MaximumSimultaneousInFlightInstructions = 50
                IsLicensed = $true
                Workflow = '[{"ReferenceType":0,"InstructionWorkflow":[{"InstructionType":1,"Workflow":{"StateMachine":"State"}}]}]'
                InstructionHandlerUrl = $null
                DataSources = @()
            }
            $postResponse = Invoke-WebRequest -Uri $apiUrl -Method Post -Body ($newConsumer | ConvertTo-Json) -ContentType "application/json" -Headers $headers
            if ($postResponse.StatusCode -eq 200 -or $postResponse.StatusCode -eq 201) {
                Write-Output "Created new 1EServiceNowCore consumer."
            } else {
                Write-Output "Failed to create 1EServiceNowCore. Status code: $($postResponse.StatusCode)"
            }
        }
    } else {
        Write-Output "Failed to fetch consumers. Status code: $statusCode"
    }
} catch {
    Write-Error "An error occurred: $_"
}

Now, follow the steps below to run the PowerShell automated script:

  1. Open SetWorkflow.ps1.

  2. Update the baseurl variable.

  3. Run the script.

  4. Enter user name and password and depending on the current consumer settings, the 1EServiceNowCore consumer will be created or updated.