Vishnu-K
Mega Sage

Introduction

 

A MID Server normally logs in to its instance with a user name and password. With IPKI (private key JWT), the instance issues the MID Server a certificate, and the MID Server uses it to sign a short-lived token for each request. No password is stored on the host.

This post shows how I set it up on a Windows server, and explains how it works along the way.

 

How it works

  1. The setup wizard on the instance creates a one-time registration key. It works once and expires within 24 hours.

  2. On its first start, the MID Server creates a private key and a certificate request, and sends the request to the instance together with the registration key.

  3. The instance issues a certificate, valid for 60 days, and the MID Server stores it.

  4. From then on, every request carries a JWT signed with the MID Server's private key. The instance checks the signature, that the token is meant for it, and that it has not expired (15 minutes by default).

  5. The MID Server renews its certificate by itself, starting 15 days before it expires.

Before you start 

  1. Make sure you have admin or agent_admin role on instance.

  2. A Windows host and an empty folder for the install. I used C:\JWTDemo.

  3. A local Windows user to run the MID Server service. It needs the "Log on as a service" right

Step 1: Create the service account

The MID Server service needs its own local Windows user. Open Computer Management, go to Local Users and Groups, then Users, and create a new user. I called mine jwtdemouser.

VishnuK_0-1794985314307.png

 

Once created, the new user shows in the list.

VishnuK_1-1794985505200.png

 

Step 2: Give the account the Logon as a service right

Open Local Security Policy, then Local Policies, then User Rights Assignment.

VishnuK_2-1794985603830.png

 

Find Log on as a service in the list and double-click it.

VishnuK_3-1794985640817.png

 

Click Add User or Group, enter the user name, then click Apply and OK.

VishnuK_4-1794985690472.png

 

Step 3: Create the install folder

Create an empty folder for the MID Server. I used C:\JWTDemo.

VishnuK_5-1794985825691.png

 

Step 4: Set up the MID Server in the wizard

On the instance, open ITOM Infra Services Workspace, select MID Servers, open the MID onboarding tab and click Set up MID Server.

Set Authentication type to ServiceNow Certificate (private key JWT), select Windows, and choose Command line installer. Enter a MID Server name with no spaces or special characters. I used JWTDemo. Then continue to the installation plan.

The wizard shows "Generating command..." while it prepares the install command. Wait for it to finish before you go on.Copy the Installation command.

VishnuK_6-1794986055887.png

 

The command expires after 24 hours. If it has expired, click Regenerate key. It also contains the registration key, so keep it private until you have used it.

 

Step 5: Run the Command in PowerShell

Click Start, search for PowerShell, and choose Run as administrator.

VishnuK_7-1794986228344.png

 

Click Yes.

VishnuK_8-1794986252681.png

 

A common mistake is to paste the command into Command Prompt. It fails with "Invoke-WebRequest is not recognized". Make sure the prompt starts with PS.

 

Go to your install folder :

cd C:\JWTDemo

Paste the install command and press Enter. When asked, enter the service account name and its password. The installer runs its checks and shows a summary. Type Y to continue.

VishnuK_9-1794986525133.png

 

The installer then downloads and installs the MID Server and starts the service. The repeated "waiting for service to start" messages are normal. It ends with Service started.

VishnuK_10-1794986660970.png

 

Step 6: Check the MID Server status

On the instance, the MID Server record should show Status: Up and Validated: Yes.

VishnuK_11-1794986802998.png

 

Finally, assign capabilities, applications and IP ranges to the MID Server.

 

Certificate renewal

The MID Server renews its certificate on its own. If renewal keeps failing, it raises the Mid-CertificateRotationRequired issue when 7 days or fewer are left.

If the certificate does expire, the MID Server can no longer log in, so register it again:

  1. In the ITOM Infra Services Workspace, open MID Servers, then MID onboarding, and click Generate single-use registration key.

  2. Choose the MID Server user, generate the key, and copy the key and the user's sys_id.

  3. In config.xml on the host, set these parameters, then restart the MID Server:

<parameter name="mid.ipki.enabled" value="true"/>
<parameter name="mid.ipki.registration_key" value="<registration_key>"/>
<parameter name="mid.ipki.user" value="<user_sys_id>"/>

 

Try it out and let me know if you have any doubts.

 

Happy Learning.

Version history
Last update:
yesterday
Updated by: