1E Platform configuration

1E 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 1E Platform for your specific authentication type before implementing the 1E Core application.

The tasks listed below may take some time to complete, depending on how your organization works. A more complete checklist of tasks is provided on the Prerequisites page.

Follow the steps below for 1E configuration and adding ServiceNow Consumer:

  1. Install 1E

    For information on installing the1E Platform (on-premises), refer to Planning for 1E.

    1. Disable two-factor authentication

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

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

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

    1. Check your 1E license

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

      If you have not yet installed 1E, you will need to obtain a 1E 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 1E Support to get an updated license file.

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

      1. Log in to the 1E 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 1E Support to get your license updated.

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

  1. Enable basic authentication

    All access to the 1E Platform by third-party applications goes through 1E's Consumer API. To allow the ServiceNow proxy user account to access 1E, 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 1E Core application is a 1E consumer that interacts with 1E using the REST services provided in the 1E API. The consumer for the 1E Core application is called 1EServiceNowCore, which must be added to 1E using the following steps after 1E is installed:

    1. Log in to the Settings app using a 1E 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 WSA upgrades you expect to do in your organization while not excessive for your environment. In a demonstration or test lab where you expect to have many incomplete WSA upgrades initiated, this number can be quite large (for example, 1,000).

      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 1E 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 TachyonMaster 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 1E Platform and ServiceNow instance for OAuth (both single and multi-tenant):

  1. Download and install the 1E Core application

  2. Carry out the prerequisites

  3. Configure Microsoft Entra ID/Okta and 1E

  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 1E Platform provisioning and upgrading guide.

Get the application

To get the latest version of the 1E Core application, choose one of the following options:

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

  • However, if you already have an older version of 1E ITSM Connect application on your ServiceNow instance, then refer to Upgrading 1E Core to upgrade your application.

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 1E Support)

Configure Microsoft Entra ID and 1E

Create certificate/principal mapping in 1E

  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 1E instance using the Set-1E Server as shown below.

  1. Get the certificate kid (key ID) using:

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

    The kid value of a certificate is a Base64-encoded version of the certificate's thumbprint.

  2. Get the AppID of the Microsoft Entra ID:

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

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

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

Upload the public key PEM file in 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. Now click on the Submit button to save the record.

  5. Click on 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. Now click on the Submit button to save the record.

  6. Click on 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 lookup list into the Signing Keystore field.

  5. Enter the Keystore password saved earlier into the Signing Key field and click on 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 lookup 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 1E Platform provisioning and upgrading guide.

Get the 1E Core application

To install the latest version of the 1E Core application, choose from one of the following options:

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

  2. However, if you already have an older version of 1E ITSM Connect application on your ServiceNow instance, then refer to Upgrading 1E 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 1E Support Portal)

Configure Okta and 1E

Create certificate/principal mapping in 1E

  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 1E 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 (key ID) using:

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

  2. You can find the AppID from the Okta portal as shown below:

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

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

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

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 on the Submit button to save the record.

  5. Click on 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. Now click on the Submit button to save the record.

  6. Click on 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 lookup list in the Signing Keystore field.

  5. Enter the Keystore password saved earlier into the Signing Key field and click on 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 lookup 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 1E 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.