Differences

This shows you the differences between two versions of the page.

--- wiki:tabulum [2022/07/26 18:34] – [Configuration file] restless
+++ wiki:tabulum [2022/07/27 16:22] (current) – removed restless
@@ Line 1: / Line 1: @@
-====== Tabulum ======
-The spiritual successor to [[kioskwatch|KioskWatch]].  Serves as the (**Cr** Edge-based) client for web kiosks and web-based tracking boards.
-\\
-{| style=“margin-left: 20px;”
-|-
-! style=“text-align:right;” | __Application name__: || Tabulum
-|-
-! style=“text-align:right;” | __Current version__: || 1.5
-|-
-! style=“text-align:right;” | __Platform__: || Windows executable
-|-
-! style=“text-align:right;” | __Use__: || Client for web kiosks and web-based tracking boards.
-|-
-! style=“border-bottom: 1px solid #999;” | ||
-|-
-! | ||
-|-
-! style=“text-align:right;” | __App owner__: || [[:user:mibowers1|Michael Bowers]]
-|-
-! style=“text-align:right;” | __App owner team__: || [[:teams:clmgmt:home|Client Management]]
-|-
-! style=“text-align:right;” | __Primary area__: || Kiosks and tracking boards
-|-
-! style=“border-bottom: 1px solid #999;” | ||
-|-
-! | ||
-|-
-! style=“text-align:right;” | __Developer__: || [[:user:mibowers1|Michael Bowers]]
-|-
-! style=“text-align:right;” | __Website for this software__: || You're looking at it.
-|-
-! style=“text-align:right;” | __Support link for this software__: || Ditto.
-|-
-! style=“border-bottom: 1px solid #999;” | ||
-|-
-! | ||
-|-
-! style=“text-align:right;” | __Path to package__: || [[\\imagecast\msi$\T\Tabulum]]
-|-
-! style=“text-align:right;” | __Packager__: || [[:user:mibowers1|Michael Bowers]]
-|-
-! style=“border-bottom: 1px solid #999;” | ||
-|}
-==== Information about Tabulum ====
-In the Before Times™ (as I like to call them), we used KioskWatch, which handled web-based kiosks and tracking boards by automating Internet Explorer.  However, since IE has been end-of-lifed we had to have a new solution.
-After experimenting endlessly with controlling Chrome or Edge with the [[https://chromedevtools.github.io/devtools-protocol/|DevTools protocol]], automation with [[https://www.selenium.dev/|Selenium]] 3 and 4, and interacting with debug configurations of the browser I ended up writing an application that embeds [[https://docs.microsoft.com/en-us/microsoft-edge/webview2/|Microsoft Edge WebView2]].  It controls that as a single full-screen browser that can be kept on-task and even allow for some automation.
-== IE Mode is available, right?  And favorites?  And extensions? ==
-No.  IE Mode is [[https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/browser-features|not supported in MS Edge WebView2]].  Neither are favorites, or extensions, or a few other features.
-== Only kiosks and tracking boards are supported ==
-Since these are meant for kiosks and tracking boards only a //single// browser window is supported.  If a page calls for a second page to open then it is intercepted and opened in the current browser window.
-If a page opens two windows at once... well... that's not suitable for kiosks or tracking boards.  The result is open to radical interpretation.
-== Why is there no screenshot on this page? ==
-There is no screenshot because, well, don't you know what a web page looks like?  Imagine it full-screen.  Well, that's Tabulum in a nutshell.
-== What's with the name? ==
-//Tabulum// is Latin for tablet, table, or a collection of ordered figures.  Since that sounds pretty much like what a kiosk or a tracking board is, I decided to run with it.  The only regret is that it's pretty close to “Tableau”.
-== Development information ==
-Tabulum was written with [[https://www.lazarus-ide.org|Lazarus 2.2.2]] and compiled with [[https://www.freepascal.org/|Free Pascal 3.2.2]].  The WebView2 components for Lazarus are [[https://www.briskbard.com/index.php?lang=en&pageid=webview|an open source package]] available for Delphi and Lazarus.
-I picked Lazarus because I didn't have time to go through the motions of getting a new version of Delphi that had WebView2 components available because the time was short until this was being deployed, so I went with something I could write code in and not have to wait on purchase orders.
-== Changes will be necessary ==
-Tabulum, being a new product, will require changes over time.  If we can't do something with it now, it doesn't mean we can't do something with it, it might just need more development to handle certain cases.  Please allow lead time for your project.
-==== Configuration instructions ====
-First, note that Tabulum is compiled for 64-bit Windows //only// and only functions on Windows 10 or newer.  The former is to encourage people to stop using 32-bit images and the latter is because of requirements for WebView2 components.
-=== Configuration file ====
-The application's configuration is stored in a file called ''Tabulum.ini''.  If a path is specified on the command line when the program is started, it will look for that file as the configuration file.  If that is not found, it will then check the program's directory (normally ''C:\Program Files\MHHS\Tabulum''), and if not there it will check the common app data folder for the application (normally ''C:\ProgramData\MHHS\Tabulum'').  If it cannot find the configuration file it will exit after not being able to load configuration information.
-There are a number of sections in the configuration file:
-  * **''[[#configuration_section|[Configuration]]]''** holds the information about program behavior, logging, timers and timeouts, etc.
-  * **''[[#alloweddomains_section|[AllowedDomains]]]''** defines [[https://www.regular-expressions.info/tutorial.html|Perl-compatible regular expressions]] (PCRE) that determine what URLs are allowed to be browsed.  These should be broad but specific.
-  * **''[[#admingroups_section|[AdminGroups]]]''** defines users who are considered administrators and may close the program or do other administrative functions.
-  * **''[[#authentication_section|[Authentication]]]''** is a listing of sections that are added that has authentication groups for the program.  They may be named any non-reserved section name and hold the information to authenticate to whatever site the user is trying to access.
-  * [[#authentication_group_sections|A section for each authentication group.]]  They are broken into two types, basic auth (the classic popup asking for a user name and password for the associated realm) and application auth (where an application has its own login and needs information to support login).
-== [Configuration] section ==
-TODO
-== [AllowedDomains] section ==
-Allowed domains is a simple enumerated list of regular expressions that should match //any// and //every// URI that users should be allowed to browse to.  Any entry that has a valid match will work.
-This means that you can put something very narrow, but make sure you account for things like subdomains or other URL arguments that may be embedded.  Alternately, you can put something very wide, but it may let extra information in (say, you put in a catch-all entry (''.*''), but then everything will match; or perhaps you just put a domain name, but then if the domain shows up in a URI argument then it will still match, despite not being a domain).
-As an example:
-  [AllowedDomains]
-=https?://.*\.?memorialhermann\.org
-=ebay\.com
-This configuration would allow for sites like:
-  http://memorialhermann.org
-  https://memorialhermann.org
-  https://somerandomsite.memorialhermann.org/somerandompage/junk.html
-  https://ebay.com
-  https://this.isnt.ebay.com.hacker.com
-  http://malicioussite.com?fake=ebay.com
-As you can see, the last two may not actually be something we want people to be able to go to... so we have to be careful about the PCREs we write.
-== [AdminGroups] section ==
-Admin groups is a simple enumerated list of groups that are allowed to perform certain functions on the program (currently, only to close the program).  List the groups that are allowed to do this.  They may be local groups (e.g. ''Administrators''), or domain grouns (''ISD Desktop ES'').
-An example:
-  [AdminGroups]
-=Administrators   ;The local administrators group
-=ISD Desktop ES   ;The following are all domain groups, but the domain is not necessary
-=ISD Desktop FS
-=ISD Desktop SM
-== [Authentication] section ==
-The authentication section specifies groups of settings that, taken together, handle the authentication to their particular site or page.
-Each entry enumerates an authentication section, as described below.  An example is in the next section.
-== Authentication group sections ==
-Each authentication section holds the settings for one potential set of credentials for logging into a site.
-The section headers are all of the format ''[Authentication_{NAME}]'', where ''{NAME}'' is the name given in the ''[Authentication]]'' section.  For instance:
-  [Authentication]
-=LaunchICBMs
-=DoomsdayDevice
-  [Authentication_LaunchICBMs]
-  ...
-  [Authentication_DoomsdayDevice]
-  ...
-There are two different ways the section can go, depending on the authentication type in question:  **basic** or **application authentication**.
-\\ **Basic authentication** is the simpler traditional authentication built into the HTTP protocol.  For this authentication, there are the following potential settings:
-^ Name             ^ Type                 ^ Description                                                                           ^ Default   ^
-| **AuthType**     | string               | The authentication type, one of **basic** or **b**, both of which are equivalent.     | //none//  |
-| **AllowedPage**  | string (PCRE regex)  | A regular expression defining the set of pages this authentication should be sent to  | //none//  |
-| **Username**     | string               | The username for authentication                                                       | //none//  |
-| **Password**     | string               | The password for authentication                                                       | //none//  |
-| **Encrypted**    | boolean              | Are the username and password values encrypted                                        | 0         |
-If the settings are properly included, the log will reflect that they have been included as a valid basic authentication setup.  When a page that meets **AllowedPage** calls for HTTP basic authentication it will use these credentials to log in.
-\\ **Application authentication** is meant to allow users to log into pages that have their own bespoke authentication built into the application.  This one is markedly more complicated.
-For this authentication, there are the following potential settings:
-^ Name             ^ Type                 ^ Description                                                                                                                                                                                                                                                                                               ^ Default                                            ^
-| **AuthType**     | string               | The authentication type, one of **application**, **app** or **a**, all of which are equivalent.                                                                                                                                                                                                           | //none//                                           |
-| **AllowedPage**  | string (PCRE regex)  | A regular expression defining the set of pages this authentication should be sent to                                                                                                                                                                                                                      | //none//                                           |
-| **Username**     | string               | The username for authentication                                                                                                                                                                                                                                                                           | //none//                                           |
-| **Password**     | string               | The password for authentication                                                                                                                                                                                                                                                                           | //none//                                           |
-| **Encrypted**    | boolean              | Are the username and password values encrypted                                                                                                                                                                                                                                                            | 0                                                  |
-| **InjectJS**     | string               | If this value is set, then if the string is the path to a file that exists then that file will be loaded to memory and the contents will be executed as JavaScript on the **AllowedPage** target, otherwise this value is the text of the JavaScript to execute into the contents of the **AllowedPage**  | //none//                                           |
-| **TypeCreds**    | boolean              | Should we type the credentials into the browser using “send keys”                                                                                                                                                                                                                                         | 0                                                  |
-| **CredString**   | string               | The string to type into the browser to log into the application.                                                                                                                                                                                                                                          | ''%%##USERNAME##{tab}##PASSWORD##{tab}{space}%%''  |
-If the settings are properly included, the log will reflect that they have been included as a valid application authentication setup.  When a page that meets **AllowedPage** is visited, it will try to log in using the application authentication methodology.
-The order of operations is that first if an **InjectJS** script has been loaded, it will be executed against the page.  This is pretty arbitrary JavaScript; it can do things like read and modify the DOM of the page, change settings, etc.  You might be able to log into the application only using JavaScript, or you may not.  It basically depends on the application.  After the JavaScript is executed, if **TypeCreds** is true then the **CredString** is sent to the browser.  See the section below for information about **CredString** format.
-**Please note** that if a page meets the criteria for your **AllowedPage** //regardless// if there is a login on the page or not, it will try to do the login procedures, effectively injecting and running JavaScript against the page and/or sending keystrokes to the page.  You need to write the //narrowest// possible **AllowedPage** definition you can for application authentication.
-\\
-For both types of authentication, encrypted credentials are base64 strings encypted with the ''Enc2Dec.exe'' program.
-\\
-Regarding the format for **CredString**, the substitution to place the username is ''%%##USERNAME##%%'', and the substitution to place the password is ''%%##PASSWORD##%%''.  Additionally, it supports the Visual Basic ''SendKeys()'' command structure, defined below:
-  Supported modifiers:
-  + = Shift
-  ^ = Control
-  % = Alt
-  Surround sequences of characters or key names with parentheses in order to
-  modify them as a group.  For example, '+abc' shifts only 'a', while '+(abc)'
-  shifts all three characters.
-  Supported special characters
-  ~ = Enter
-  ( = Begin modifier group (see above)
-  ) = End modifier group (see above)
-  { = Begin key name text (see below)
-  } = End key name text (see below)
-  Supported characters:
-  Any character that can be typed is supported.  Surround the modifier keys listed
-  above with braces in order to send as normal text.
-  Supported key names (surround these with braces):
-  BKSP, BS, BACKSPACE
-  BREAK
-  CAPSLOCK
-  CLEAR
-  DEL
-  DELETE
-  DOWN
-  END
-  ENTER
-  ESC
-  ESCAPE
-  F1
-  F2
-  F3
-  F4
-  F5
-  F6
-  F7
-  F8
-  F9
-  F10
-  F11
-  F12
-  F13
-  F14
-  F15
-  F16
-  HELP
-  HOME
-  INS
-  LEFT
-  NUMLOCK
-  PGDN
-  PGUP
-  PRTSC
-  RIGHT
-  SCROLLLOCK
-  TAB
-  UP
-  Follow the keyname with a space and a number to send the specified key a given
-  number of times (e.g., {left 6}).
-==== Testing instructions ====
-Tabulum is pretty straightforward.  To test that Tabulum is working properly, configure it to load your favorite internal site and make sure it's an allowed site as per the configuration.  If it loads when you start Tabulum, everything must be good!
-==== Logging ====
-{{:wiki:pasted:20220726-165535.png }}There is logging found in the Windows Event Log, under **Event Viewer > Applications and Services Logs > MHHS** using the source name **Tabulum**.  You may need to filter the log to see just Tabulum entries as time goes by.
-The extensiveness of the logging is defined by the setting **DetailedLog** (see ''[Configuration]'' section above).
-If you have a problem, //please look at the logs.//  The logs are important and can help you figure out what may be going wrong.
-==== Installation summary ====
-Installation of the app requires that MS Edge WebView2 components are installed from Microsoft.
-Manual installation is not really necessary; there's a handy package that installs the files.
-^ Tabulum.exe  | The application itself.  |
-^ WebView2Loader.dll  | The wrapper that loads the WebView2 components and initializes the objects.  |
-^ EventMessages.dll  | The Windows Event Log messages content.  |
-^ EventCategories.dll  | The Windows Event Log categories.  |
-^ Tabulum.ini  | The configuration file, described above.  |
-Place all these in a single directory, configure the program as above and run it.  If properly configured, it should work fine.  The user profile directory is made automagically.
-==== Previous versions ====
-This is the first public release of Tabulum.