# ESSO # ⏰ Getting started ## Introduction Soffid ESSO is a full Enterprise Single Sign on solution, with some distinguishing features: 1. Keeps track of users sessions active on the network. 2. Automatically reconfigure user preferences and desktop behaviour according to whether or not it is connected to the corporate network. 3. And of course, as any other ESSO solution, automatically detects user identification prompts, injecting the needed credentials, pressing buttons and more. As critical success factors the following design principles are governing Soffid ESSO product: 1. It's fully integrated with Soffid IAM console. 2. It's extremely easy to install and configure. 3. It has good management and support tools. 4. It's workload on managed workstations is minimal. 5. It has been designed to minimize system vulnerabilities. 6. It's open-source. # How to install ESSO? # ESSO Installation Windows (from 3.3.3-enterprise to 3.4.3-enterprise) ## Introduction Soffid ESSO is a full Enterprise Single Sign on solution. Here you can find the details about the **ESSO from 3.3.3-enterprise to 3.4.3-enterprise** iversions nstallation. ## Supported platforms Soffid ESSO supports Windows XP or later workstations. ## Interactive installation To install Soffid ESSO, you must follow these steps: 1. Download the latest available installer version from: [Soffid Download Manager](http://www.soffid.com/download/enterprise/). 2. Run it as administrator. Once the interactive installation has finished, a message window will notice you:[![image-1647446846755.png](https://bookstack.soffid.com/uploads/images/gallery/2022-03/scaled-1680-/image-1647446846755.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-03/image-1647446846755.png) 3. Finally, the system will prompt you to configure Soffid ESSO. This prompt will not be shown on updates or silent installations. [![image-1647446894539.png](https://bookstack.soffid.com/uploads/images/gallery/2022-03/scaled-1680-/image-1647446894539.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-03/image-1647446894539.png) 4. After configuring the system, it's required to reboot the computer. ## Interactive configuration The first task to do at configuration panel is to enter the Soffid synchronization server URL and fetch its digital certificate. To do it, enter its URL on the textbox and press “Retrieve Certificate” button in order to obtain a certificate from the server. [![image-1647446909812.png](https://bookstack.soffid.com/uploads/images/gallery/2022-03/scaled-1680-/image-1647446909812.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-03/image-1647446909812.png) If the URL is correct and the synchronization server is effectively running, the digital certificate will be downloaded and stored at Soffid ESSO directory. Mind that this initial configuration step is highly insecure. Should a man be in the middle, the certificate could be tampered, compromising any further security check. It is a suitable procedure for testing and quick configuring, but a secure way to install and configure your installation certificate is preferred. “**Users can logout”** checkbox enable users to open the Soffid notifier menu and close it's Soffid session. After logging out, the user will be allowed to start a new Soffid session with the same or another user name. If the checkbox is not selected, the user will not be allowed to close Soffid session without closing Windows session. When **“Force login at startup”**, checkbox is selected, the Windows session (explorer.exe) won't start until Soffid session is completely verified and set up. Otherwise, the windows session will start regardless Soffid session is not started yet. If there is an error or denied log-on at Soffid ESSO, windows session will go on without any single sign on feature. “**Use Soffid windows logon screen**” checkbox is only available on Windows XP. It changes the default (GINA) Windows logon screen, allowing the use of self-registered SmartCard certificates or one-time-password devices. It is not needed on Vista and later. There are three ways to logon to Soffid: - **Kerberos login** will reuse the Windows credential acquired by the operating system. If they belong to a managed Active Directory, the user won't need to enter any user name or password to access Soffid. - When **manual login** is selected, the user must enter a valid user name and password in order to access Soffid. - When **both** is selected, the system will try first a Kerberos login. Whenever it is not possible (the user is not a domain user), a manual login will be prompted to the user. ## Silent installation In order to do a silent installation you can execute the installer from command line with the following parameters: **-q** or /q: Quiet installation **-server** \[url\] or /server \[url\]: to configure the synchronization server URL. **-force** or /force: force the installation even if a restart is pending. Not recommended. **-nogina** or /nogina: do not modify previos GINA. In this version, this parameter only applies in first installation. Example: ```western C:\> soffidesso.exe -q -server https://server.domain.local:760 -force -nogina ``` ## Smart update To assist in massive deployment scenarios, smart update swich can be set to prevent Soffid to reinstall componenents when the installer version matches the already installed one. This switch does not affect to new installations. **-smartupdate** or /smartupdate: Smart update installation Example: ```western C:\> soffidesso.exe -q -server https://server.domain.local:760 -force -nogina -smartupdate ``` ## MSI Package MSI Installation is also available for enterprise customers. To customaize configuration parameters, the PARAM variable can be used: Example: ```western C:\> msiexec /i soffidesso.mssi PARAM="-q -server https://server.domain.local:760 -force -nogina -smartupdate" ``` ## Registry configuration entries The system stores all its settings in the registry branch HKLM\\Software\\Soffid\\esso. The values used are as follows:
**Entry** **Default Value** **Description**
LogonEntry Logon After identifying the user, Soffid ESSO will look at the defined application tree for an application with this key, in order to execute it.
OfflineEntry Offline If synchronization servers are not reachable, an alternative script will be execute. This entry contains the key of the application entry point to execute in such a case.
LocalCardSupport 2 Indicate whether to ask for coordinates card at logon time or not. Four values are allowed. 1 – Coordinates card is required 2 – Coordinates card is required if and only if the user is the owner of one card. 3 – Coordinates card is required if the user is connecting from a not registered device. 4 – Never ask for coordinates card.
RemoteCardSupport 1 Indicate whether to ask for coordinates card when performing a remote logon. Four values are allowed. 1 – Coordinates card is required 2 – Coordinates card is required if and only if the user is the owner of one card. 3 – Coordinates card is required if the user is connecting from a not registered remote device. 4 – Never ask for coordinates card.
LocalOfflineAllowed 1 Specifies whether is it permitted to use the workstation when no Soffid synchronization servers are reachable. 1 – It's permitted. 0 – It's forbidden.
RemoteOfflineAllowed 0 Specifies whether it is permitted to open a terminal server connection against this host when no Soffid synchronization servers are reachable. 1 – It's permitted. 0 – It's forbidden.
CertificateFile root.cer Specifies the name of the file containing the Certificate Authority certificate used by the synchronization server (X509 DER format)
SSOServer stsmlin3.caib.es, sticlin2.caib.es Comma-separated list of synchronization server names
seycon.https.port 760 TCP/IP port used for connecting to SEYCON
debuglevel Indicates the level of detail of the log: 0 = not recorded anything 1 = Basic Information 2 = Detailed Information
ginalogFile Name of the file which records the actions taken by GINA. Do not enable it unless needed.
ShiroHostName Do not modify: It contains the name that the host had when it was registered at Soffid server.
startDisabled false When it contains the value “true”, Soffid ESSO will be started in disabled (or pause) state. Thus, it will not inject any user name or password on user applications.
MazingerVersion It contains the version number of Soffid ESSO.
sayaka.domain It contains the Active Directory name the workstations belongs to.
sayaka.pkcs11% (reserved) Each crypto card used by the user will have a corresponding entry indicating the name of the PKCS#11 DLL that can handle it. Do not modify.
## Startup process {{@1306}} ## Enforcing browser addons {{@1307}} # ESSO Installation Windows (+3.5.0-enterprise) ## Introduction Soffid ESSO is a full Enterprise Single Sign on solution. Here you can find the details about the **ESSO +3.5.0-enterprise** installation. ## Supported platforms Soffid ESSO supports Windows XP or later workstations. ## Windows ### Interactive installation To install Soffid ESSO, you must follow these steps: 1\. Download the latest available installer version from: [Soffid Download Manager](http://www.soffid.com/download/enterprise/). 2\. Install as administrator. Once the interactive installation has finished, a message window will notice you: [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/tLq3ZUs7BvnK7Z0o-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/tLq3ZUs7BvnK7Z0o-image.png) 3\. Finally, the system will prompt you to configure Soffid ESSO. This prompt will not be shown on updates or silent installations. [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/YLBFPE04xe4TY4tE-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/YLBFPE04xe4TY4tE-image.png) 3.1. If you click No, the process finish without configuration 3.2. If you clic Yes, you have to configure the URL of the ESSO server, for which you will have to enter the URL of the Soffid identity provider and obtain its digital certificate. [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/1kNRR6h71Kjj5W32-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/1kNRR6h71Kjj5W32-image.png) 4\. After configuring the system, it's **required to reboot the computer.**

For more information, you can visit **[the Windows user acces page](https://bookstack.soffid.com/books/esso/page/windows-administrator-access)** and [**the Windows Administrator access page**](https://bookstack.soffid.com/books/esso/page/windows-administrator-access).

### Configure the ESSO Profile 1\. Then you need to configure the ESSO profile in your Identity Provider
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/yWElBgTnW9rZpzRf-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/yWElBgTnW9rZpzRf-image.png)

For more information you can visit the following page: [https://bookstack.soffid.com/books/federation/page/esso](https://bookstack.soffid.com/books/federation/page/esso)

2\. And finally, you can configure the Adaptive authentication rules
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/aq9KrGgF8MhVsGes-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/aq9KrGgF8MhVsGes-image.png)
### Silent installation In order to do a silent installation you can execute the installer from command line with the following parameters: **-q** or /q: Quiet installation **-server** \[url\] or /server \[url\]: to configure the synchronization server URL. **-force** or /force: force the installation even if a restart is pending. Not recommended. **-nogina** or /nogina: do not modify previos GINA. In this version, this parameter only applies in first installation. **-nopm** : to avoid installing Password Manager To assist in massive deployment scenarios, smart update swich can be set to prevent Soffid to reinstall componenents when the installer version matches the already installed one. This switch does not affect to new installations. **-smartupdate** or /smartupdate: Smart update installation #### Install EXE Package EXE Installation is also available for enterprise customers. Example: ``` C:\> MazingerInstaller-3.5.3-enterprise.exe -q -server https://idp.your-soffid.com:443 -force -nogina -smartupdate -nopm ``` #### Install MSI Package MSI Installation is also available for enterprise customers. To customaize configuration parameters, the PARAM variable can be used. Example: ```western C:\> msiexec /i soffidesso.msi PARAM="-q -server https://idp.your-soffid.com:443 -force -nogina -smartupdate -nopm" ``` > **Installation problems can be reviewed in the installer log: C:\\Windows\\SysWOW64\\mazinger-install.log** ## Registry configuration entries The system stores all its settings in the registry branch **HKLM\\SOFTWARE\\Soffid\\esso**. The values used are as follows:
**Entry** **Default Value** **Description**
LogonEntry Logon After identifying the user, Soffid ESSO will look at the defined application tree for an application with this key, in order to execute it.
OfflineEntry Offline If synchronization servers are not reachable, an alternative script will be execute. This entry contains the key of the application entry point to execute in such a case.
LocalCardSupport 2 Indicate whether to ask for coordinates card at logon time or not. Four values are allowed. 1 – Coordinates card is required 2 – Coordinates card is required if and only if the user is the owner of one card. 3 – Coordinates card is required if the user is connecting from a not registered device. 4 – Never ask for coordinates card.
RemoteCardSupport 1 Indicate whether to ask for coordinates card when performing a remote logon. Four values are allowed. 1 – Coordinates card is required 2 – Coordinates card is required if and only if the user is the owner of one card. 3 – Coordinates card is required if the user is connecting from a not registered remote device. 4 – Never ask for coordinates card.
LocalOfflineAllowed 1 Specifies whether is it permitted to use the workstation when no Soffid synchronization servers are reachable. 1 – It's permitted. 0 – It's forbidden.
RemoteOfflineAllowed 0 Specifies whether it is permitted to open a terminal server connection against this host when no Soffid synchronization servers are reachable. 1 – It's permitted. 0 – It's forbidden.
CertificateFile root.cer Specifies the name of the file containing the Certificate Authority certificate used by the synchronization server (X509 DER format)
SSOServer stsmlin3.caib.es, sticlin2.caib.es Comma-separated list of synchronization server names
seycon.https.port 760 TCP/IP port used for connecting to SEYCON
debuglevel Indicates the level of detail of the log: 0 = not recorded anything 1 = Basic Information 2 = Detailed Information
ginalogFile Name of the file which records the actions taken by GINA. Do not enable it unless needed.
ShiroHostName Do not modify: It contains the name that the host had when it was registered at Soffid server.
startDisabled false When it contains the value “true”, Soffid ESSO will be started in disabled (or pause) state. Thus, it will not inject any user name or password on user applications.
MazingerVersion It contains the version number of Soffid ESSO.
sayaka.domain It contains the Active Directory name the workstations belongs to.
sayaka.pkcs11% (reserved) Each crypto card used by the user will have a corresponding entry indicating the name of the PKCS#11 DLL that can handle it. Do not modify.
## Startup process {{@1306}} ## Enforcing browser addons {{@1307}} # ESSO Installation Linux ## Introduction Here you can find the details about the ESSO installation. ## Installation ```shell sudo dpkg -i '/MazingerInstaller-3.5.2-enterprise.deb' ```
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/ynJLDiVNBD7sWhnb-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/ynJLDiVNBD7sWhnb-image.png)
## Interactive configuration 1\. To configure, you need to run the following command with your Soffid Identity Provider URL. ``` sudo configure_esso https://:443 ```
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/Fyf3H9gqJwMbqqzw-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/Fyf3H9gqJwMbqqzw-image.png)
2\. Then you need to configure the ESSO profile in your Identity Provider
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/yWElBgTnW9rZpzRf-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/yWElBgTnW9rZpzRf-image.png)

For more information you can visit the following page: [https://bookstack.soffid.com/books/federation/page/esso](https://bookstack.soffid.com/books/federation/page/esso)

3\. And finally, you can configure the Adaptive authentication rules
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/aq9KrGgF8MhVsGes-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/aq9KrGgF8MhVsGes-image.png)

For more information, you can visit [**the Linux Administrator access page**](https://bookstack.soffid.com/books/esso/page/linux-administrator-access) and [ **the Linux user acces page**.](https://bookstack.soffid.com/books/esso/page/linux-user-access)

## Enforcing browser addons {{@1307}} # Startup process ### Windows XP GINA logon Soffid GINA is an optional part of Soffid ESSO. It's features are: - Allows users to log on using smart cards. The digital certificates can be auto enrolled as long as there is a method to know which user it belongs to. - Allows authorized users to log on with Local Administrator privileges. ### Windows Vista Credential Provider Soffid Credential Provider is an optional part of Soffid ESSO. It's features are: - Allows users to log on using smart cards. The digital certificates can be auto enrolled as long as there is a method to know which user it belongs to. - Allows authorized users to run with Local Administrator privileges. ### Soffid session startup After being identified by Windows, the Soffid session startup takes place. Either sequentially or in parallel to desktop startup, the Soffid ESSO session manager (named KojiKabuto after the best ever hero) is the responsible for making the following steps. #### Update settings KojiKabuto will contact Soffid servers o update registry entries using the system configuration introduced at Soffid console (LogonEntry, OfflineEntry, SSOServer, seycon.https.port) #### Kerberos handshake If it's enabled by system administrator, Soffid Synchronization server and the user desktop will perform a Kerberos handshake. If the Credential token shown by user desktop is accepted by any managed Active Directory, Soffid will accept that credential as a prove of identity. In order to do that handshake, Soffid will create an special user named SEYCON\_xxxx for each one of the synchronization servers involved in the login process. #### Manual login If it's enabled by system administrator, or Kerberos handshake has failed, the user will have the chance to enter it's user name and passwords. They will be verified by synchronization server against its internal user database. #### Coordinates card Once logged in, KojiKabuto requested permission to log. At this time, synchronization server could issue a coordinates card challenge. If the user fails to enter the right value for the coordinates requested, the Soffid session will be canceled. #### Multiple sessions prevention At this phase, Synchronization Server will check if the user has any other, not linked, session. If there is any other active session, and the user has not been granted the capability to open more than one (at Soffid console), the system will notice it to both, the new session and the ancient one. Finally, the new session will take the decision to close the ancient one or to give up. If the user chooses to close the ancient one, the later will show a prompt, and its user will have 30 seconds to answer if he agrees to close that session. Usually the user has left the ancient session open and no user will be present at the ancient session. So, after 30 seconds the session will be closed and the new one will proceed. #### SSO Rules activation Once the session has been created, the SSO rules present at Soffid Console will be compiled and loaded into the Windows Session. Since this moment, every application launched will have its credentials automatically fullfilled. #### Startup script The workstation connects to Synchronization Server to get the session logon script (LogonEntry registry entry with deafault value "Logon"), and the session offline script (registry entry "OfflineEntry" with default value "offline"), which will be executed at next logon whether no Synchronization server is reachable. The offline script is stored at %ProgramFiles%\\SoffidESSO\\Cache\\offline.mzn file. Afterwards, the application menu is populated using the application entries configured at Sofifd Console. #### Desktop start Unless the system configuration enables the user to use the desktop before opening the Soffid Sesion, the Desktop is started right now. Otherwise, the desktop would have been started at the initial steps. #### System operation Once the session is started, Soffid ESSO has two main tasks to do: **First.** Timely keeps in touch with Synchronization server to confirm the validity of the soffid session. **Second**. Performs injection or user names and password to applications, based on the SSO rules bound to each application entry point the user is authorized to execute.\\ # Enforcing browser addons Modern browsers, apply certain restrictions to automatically enable browser addons without user intervention: ### Google chrome Google chrome extension is automatically enabled, but requires internet access, as Chrome is going to download the addon directly from Chrome store rather than using the locally installed version. This addon is compatible with Microsoft Edge. ### Mozilla Firefox There is a Mozilla firefox group policy to automatically enable any extension. Follow this link to get it: [https://github.com/mozilla/policy-templates/releases/download/v1.11/policy\_templates\_v1.11.zip](https://github.com/mozilla/policy-templates/releases/download/v1.11/policy_templates_v1.11.zip) You can alternatively, add the following registry key: HKEY\_LOCAL\_MACHINE\\Software\\Policies\\Mozilla\\Firefox\\Extensions\\Locked\\1 = "esso@soffid.com" ### Internet Explorer (deprecated) As well, there is a group policy for Internet Explorer. Please, follow this Microsoft link to get it: [https://docs.microsoft.com/es-es/internet-explorer/ie11-deploy-guide/enable-and-disable-add-ons-using-administrative-templates-and-group-policy](https://docs.microsoft.com/es-es/internet-explorer/ie11-deploy-guide/enable-and-disable-add-ons-using-administrative-templates-and-group-policy) The GUUID of Soffid ESSO group policy is {53252A52-D536-11DF-866D-5B82D67A00D1} # ESSO Configuring Rules for Single Sign On # Configuring Rules for Single Sign On ## Configuring Single Sign-on
- [User interface pattern recognition](#bkmrk-user-interface-patte-0) - [Web interfaces pattern recognition](#bkmrk-web-interfaces-patte) - [Configuring rules for basic / kerberos authentication](#bkmrk-configuring-rules-fo)
SSO system is configured based on the detection of administrator defined User Interface patterns. The system currently supports native Windows applications, Java applications and Web applications. The UI Patterns are expressed with XML files associated with each application entry point. They are composed of: - **Rules** for detecting user interfaces (defined like application attributes or elements). - **Action** to be taken on user interface recognition. (defined with the action element for the application). Complementary to the rules defined in Sofifd Console, the synchronization server manages a repository of user accounts and passwords, as well as other information generically known as **secrets**. In general, the system will handle any number of secrets as well as any number of accounts for each managed systems. Anyway, each account for a managed system will have only one password. All secrets can be used and manipulated using a scripting language fully compatible with ECMA-Script, also known as Javascript. ## User interface pattern recognition The user interface detection for Windows and Java applications is done using the **Application** tag. This tag will contain one or more Component tagged elements. Each component could have many nested components. Each component could have one or more actions to perform when the user focus is at a selected component. Next is a sample to inject the secret name “JconsolePassword” into jconsole application:
<Mazinger> <**Application** cmdLine = '.\*jconsole$'> <**Component** class = 'sun.tools.jconsole.JConsole' title = 'Java Monitoring & Management Console' name = 'frame0'> <**Component** class = 'sun.tools.jconsole.JConsole\\$FixedJRootPane'> <**Component** class = 'javax.swing.JPanel' name = 'null.glassPane' /> <**Component** class = 'javax.swing.JLayeredPane' name = 'null.layeredPane'> <**Component** class = 'javax.swing.JPanel' name = 'null.contentPane'> .... <**Component** class = 'javax.swing.JPasswordField' text ='' ref-as = 'password'> Patterns to be match
<**Action** type='script' event='onFocus'> <! \[CDATA \[ var account = secretStore.getAccount('soffid'); var password = secretStore.getPassword('soffid', account); debug ('user =' + account); debug ('password =' + password); password.setText (secretStore.getSecret ('password')); \]\]> </ **Action**> The action you want to be executed
....
Thus, when the system detects that the user is within a window that meets the XML specification and the password text box is the focus owner, Soffid will execute the script action that is bound. This one will show the user password in a jconsole application field. The Application contains in the attribute cmdLine a regular expression that is matched against the process command line. In the example, SSO will only match a running program with a command line that ends with "jconsole". It won't apply to jconsole.exe or “jconsole test”. The element **Application** accepts the following attributes:
cmdLine Regular expression to match the command line.
The **Component** element allows the following attributes:
class Regular expression to validate against the kind of visual component, either a Java class or a window class.
name Regular expression to match the name of the component. Applies only to Java components.
text Regular expression to match the content of a text component
title Regular expression to match the title of a java component.
dlgId Regular expression to match window ID dialog on Windows component.
optional If the value is true, the presence of the component is not considered critical to trigger actions associated dialogue.
check When the check attribute has the value “**partial**”, the matcher engine considers the user interface component matches the XML pattern even when it has one or more children components that are not declared at the XML pattern. If you specify the value **full** value or the attribute is missing, the component will not match the pattern if it has children are components not specified in XML descriptor. Thus, the rule will be ignored.
ref-as Specifies a name of a ECMA-Script variable that will refer to this component.
The **Action** element accepts the following attributes:
event Name of the event that will trigger the action. In the current version must be set to "onFocus"
type Indicates the type of action. Can have the following values: **setText:** Assigns a text value to the owner component. **script.** Run the specified script.
text Text to assign, for setText actions.
repeat If set to true, the action will be executed as many times as necessary. Otherwise, it will only run once per process.
delay Time (in seconds) that must be elapsed before the action is executed again.
## Web interfaces pattern recognition The detection is done using the element **WebApplication**. This tag is independent of the browser used, and is based solely on the content of web document. Thus, the same rule will work both on Mozilla Firefox, Google Chrome or Internet Explorer.
<Mazinger> <**WebApplication** url = '[https://www.caib.es](https://www.caib.es/). \*' title = 'Government of the Balearic Islands'> <**Form** action = "j\_security\_check"> <**Input** name="j\_username" ref-as="u"/> <**Input** name="j\_password" type="password" ref-as="p"/> <**Input** type="Submit" ref-as="b" /> Patterns to be match
<**Action** Type='script' event='onLoad'> <! \[CDATA \[ debug('User =' + secretStore.getAccount ('user')); debug ('password =' + secretStore.getPassword('soffid', account)); u.setAttribute ('value' secretStore.getAccount ('user')); p.setAttribute ('value' secretStore.getPassword('soffid', account)); b.click(); \]\]> </**Action**> Action you want to be executed
</**Form**> </**WebApplication**> </Mazinger>
Thus, when the system detects that the browser has loaded a page matching the XML specification (url, title, and components), it will run the actions that have been associated. Mind that despite the actions being coded in Javascript, it is not the Browser javascript engine. Thus, you cannot use browser variables or functions. The element **WebApplication** accepts the following attributes:
url Regular expression to match the page address
title Regular expression to match the title of the page
content Regular expression to match the HTML content of the page
The **Form** element will search in the HTML document for a form that matches the specified attributes. It can optionally contain one or more input elements that must be present in the HTML document. It accepts the following attributes:
id Regular expression to match the ID attribute of the element
name Regular expression to match the element name
method Regular expression to match the form element's method attribute.
action Regular expression to match the form element's action attribute.
ref-as Specifies a name of a ECMA-Script variable that will refer to this form.
optional A value of **true** indicates that its presence is not necessary for the execution of actions.
The **Input** element will search in the HTML document for an input element that matches the specified attributes. Input elements can be located within WebApplication or Form elements. In the first case, you will find there is any input into the document. In the second case, just find the type items included in the input form found.
id Regular expression to match the ID attribute of the element
name Regular expression to match the element name
type Regular expression to match the input type
value Regular expression to match the input value.
ref-as Specifies a name of a ECMA-Script variable that will refer to this form.
optional A value of **true** indicates that its presence is not necessary for the execution of actions.
The **Action** element accepts the following attributes:
event Name of the event that will trigger the action. In the current version must be set to "onFocus"
type Indicates the type of action. Can have the following values: **setText:** Not supported **script.** Run the specified script.
repeat If set to true, the action will be executed as many times as necessary. Otherwise, it will only run once per process.
delay Time (in seconds) that must be elapsed before the action is executed again.
## Configuring rules for basic / kerberos authentication Some web pages are still using basic or kerberos authentication mechanisms. These mechanisms do not present a web page to be filled in by the user. Thus, the ESSO engine cannot detect it using the method described previously. Instead, starting from Soffid ESSO version 3.0.0, there is a new tag to teach the ESSO which credentials to send in these cases. The rules will be like the next ones: ```       ```
The tag to use is WebTransport. It has three parameters:
Attribute
Value
urlThe base url to use. Include the protocol and port number when needed. Any BASIC, NTLM or Kerberos authentication requested by that server will be automatically answered with the credentials present in the password vault
systemThe ESSO will send any credential that the user has in that system. Other credentials will be ignored
domainThis is an optional attribute. It's required when trying to use Kerberos or NTLM authentication if the account name does not contain the domain name part. If the account contains the domain name, this attribute should not be present.
Due to the different ways that browsers address this kind of authentication, the user interface will be displayed according to the browser settings. For instance, Edge and Internet Explorer will display a UA dialog box. # Support and configuration tools ## Introduction **KojiKabuto.exe, the main Soffid ESSO component**, picks settings and rules automatically from Soffid synchronization server at login. This configuration can be updated by running the command "KojiKabuto update". Once run, new rules will apply to all new processes. Mind that application processes that where running before the update is done will still use the old rules set. Additionally, you can drive SSO by yourself for testing purposes. Mazinger.exe is the command line version of Soffid ESSO. It accepts the following commands: To stop SSO service: ``` mazinger stop ``` To start Mazinger services: ``` mazinger start [-trace] [-debug] [file.mzn] ``` To get a configuration file, you can download from: https://<synchronizationserver>:760/getmazingerconfig?user = ..... The -debug switch allows Mazinger to display all the single sign on events that are produced at users applications. The -trace switch is only inteded for debugging and support usage. To view all the single sign on events on a running ESSO instance, you can run: ```western mazinger debug ``` To view current SSO service status, run: ``` mazinger status ``` Mazinger can also dump XML files describing the applications user interface. This XML files can be used to describe SSO rules. To dump this XML descriptors, execute: ``` mazinger spy ``` Mazinger spy and mazinger trace are very useful when you are creating a new ESSO rule in order to see what parameters, components, atributes, ... the application are using. In order to execute this commands, you must go to the ESSO installation directory. For example, C:\\Program Files\\SoffidEsso\\mazinger.exe trace. # ESSO Scripting Language

Visit the [ESSO Scripting Language](https://bookstack.soffid.com/books/esso/chapter/esso-scripting-language "ESSO Scripting Language") chapter.

# Configuring terminal emulation SSO ## Introduction To configure SSO on terminal emulations, an HLL API bridge has been built. This bridge allows direct communication with the terminal emulator in order to create accurate SSO rules that can be triggered based on the screen display. Next, you have a sample rule for terminal emulation SSO: **HLL API rule** ``` .*SOFFID.* .*ABC.* account = secretStore.getAccount ("390host"); password = secretStore.getPassword ("390host", account); hll.setCursorLocation (22,3); hll.sendText ("HELLO "+account); hll.setCursorLocation (23, 3); hll.sendText ("YOUR PASSWORD IS "+password); hll.sendKeys("@E"); ``` The rule should contain one or more patterns that will be matched against the specified row. If the screen matches all the specified patterns, the action will be executed as usual. Nevertheless, HLL applications differ in some way from other application rules as long as the HLL engine (Sewashi) must be started separately from the ESSO engine. To active the HLL rules engine, the sewashi program must be started, specifying the HLL API used to interact with the terminal emulator, and optionally, the sessions to be managed: ``` %ProgramFiles%\SoffidESSO\Sewashi.exe --dll "%ProgramFiles%\IBM\Personal Communications\PCSHLL32.DLL" --sessions ABCDEFG ``` To stop the HLL engine, Sewashi --stop can be executed. This program can executed from Soffid login and logout scripts. # ESSO Related configuration parameters ## Introduction There are some configuration parameters that can be tuned on Soffid console.
**Parameter**
**Value**
**SSOServer**Comma separated of synchronization servers the ESSO should connect to
**seycon.https.port**TCP/IP synchronization servers are listening to. By default 760
**SSOSoffidAgent**Name of the agent used to authenticate user accounts. If none is specified, the user name entered by the user is matched against usernames. If an agent name is specified, the user name entered by the user is matched against active accounts on this agent.
**LogonEntry**Application entry point to execute after login.
**OfflineEntry**Application entry point to execute when the desktop is offline. The script belonging to this application entry point will be stored locally.
**AutoSSOSystem**Virtual agent name where to store user registered accounts
**AutoSSOPolicy**Password policy to applyfor user registered accounts
As stated at Parameter screen documentation, a single parameter can have a global default value and specific values on a subnetwork basis. This mechanism allows the administrator to setup different synchronization servers for each subnet. # ESSO Manuals Documentation about Windows user access, Linux user access and Admin access # Windows Administrator access ## How to access? For domain member hosts, ESSO will remove all existing local accounts except for those with a dependand service. So, in order to access with administrator privileges, user must use a domain account with local administrator privilege, or either an authorized Soffid user. There are three different ways to grant this kind of authorization to a user using Soffid console: 1. Grant a global authorization (host:support). In this case, user can admin any host. 2. Using a network scope authorization. This kind of authorization can be granted on network management screen. Administration authorization can be granted for any host belonging to a network or for a restricted group of them. 3. Using a host scope authorization. This kind of authorization can be granted on host management screen for specified time period. Through a workflow request. User asks for administration approval using "Request to administer a workstation" workflow. Soffid administrator can deny or approve the request. After the specified time period, the permission will be revoked. [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/zd5ziD6Pp8HbTYvW-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/zd5ziD6Pp8HbTYvW-image.png) In order to acces with administrator privileges user must log on with the soffid user code. It is not possible to do it with another account. Windows user code must match with Soffid user code. ## Other operations ### How to know the ESSO version? Windows Control Panel --> Add/Remove programs
💻 Image [![image-1665397531364.png](https://bookstack.soffid.com/uploads/images/gallery/2022-10/scaled-1680-/image-1665397531364.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-10/image-1665397531364.png)
### How to check the log? ```shell C:\Windows\System32\type mazinger-install.log ```
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/TKW7p8APrL2gWJVP-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/TKW7p8APrL2gWJVP-image.png)
### How to run the configuration? ``` C:\Program Files\SoffidESO\SoffidConfig.exe ```
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/fDP4njfpqgk2V5tz-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/fDP4njfpqgk2V5tz-image.png)
### How to check the status? ``` C:\Program Files\SoffidESSO>Shirokabuto debug ```
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-11/scaled-1680-/NXWLBxR4V1FtwsUy-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-11/NXWLBxR4V1FtwsUy-image.png)
### How to stop and start Shirokabuto? ``` C:\Program Files\SoffidESSO>net stop Shirokabuto ``` ``` C:\Program Files\SoffidESSO>net start Shirokabuto ``` # Linux Administrator access ## How to access? For domain member hosts, ESSO will remove all existing local accounts except for those with a dependand service. So, in order to access with administrator privileges, user must use a domain account with local administrator privilege, or either an authorized Soffid user. There are three different ways to grant this kind of authorization to a user using Soffid console: 1. Grant a global authorization (host:support). In this case, user can admin any host. 2. Using a network scope authorization. This kind of authorization can be granted on network management screen. Administration authorization can be granted for any host belonging to a network or for a restricted group of them. 3. Using a host scope authorization. This kind of authorization can be granted on host management screen for specified time period. Through a workflow request. User asks for administration approval using "Request to administer a workstation" workflow. Soffid administrator can deny or approve the request. After the specified time period, the permission will be revoked. In order to acces with administrator privileges user must log on with the soffid user code. It is not possible to do it with another account. Windows user code must match with Soffid user code. ## Other operations ### How to know the ESSO version? ``` dpkg -l soffidesso ```
💻 Image [![image-1665396904304.png](https://bookstack.soffid.com/uploads/images/gallery/2022-10/scaled-1680-/image-1665396904304.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-10/image-1665396904304.png)
### How to check the log? ```shell /var/log$ sudo tail syslog ``` ``` /var/log$ sudo cat syslog ``` ### How to change debug level? Edit the file /etc/mazinger/config and set debugLevel to 3 ``` nano /etc/mazinger/config ```
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/aMGl10AI9lJ7qRde-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/aMGl10AI9lJ7qRde-image.png)
### How to login using the command line? Raise permissions to super users: ```shell sudo -i ``` Login with your Soffid user ```shell login userName ```
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/djdjWmR0OJicPhr6-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/djdjWmR0OJicPhr6-image.png)
# Windows user access ## How to access? When you try to connecto to a Windows machine by using Soffid ESSO, you need to enter your user and password in the Windows login page. If the user does not exists in this machine, depending on the attribute "Create local accounts when there is no domain account" in Soffid ESSO configuration, a local user willl be created or not. - If the network is connected, depending on the Soffid ESSO configuration, a 2FA may be required, or you will be logged in directly. - If the network is not connected, also, depending on the Soffid ESSO configuration, you connect to the machine. When the network is re-established, Soffid ESSO will ask for your credentials again.

For more information about how to configure Soffid ESSO you can visit [the ESSO profile page](https://bookstack.soffid.com/books/federation/page/esso).

💻 Image ##### Credentials required [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/XCefvJwmqcK4ovLq-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/XCefvJwmqcK4ovLq-image.png) ##### 2FA required [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/2S2t6nRPrgbfVf55-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/2S2t6nRPrgbfVf55-image.png) ##### Soffid ESSO options [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/WNP7lSbXTiiimGXY-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/WNP7lSbXTiiimGXY-image.png)
## Esso Options On a host with ESSO installed an icon with the Soffid Logo will appear on the Windows taskbar. If the user clicks on the mouse's right button it will be able to do some different actions. #### Login Allows you to open an ESSO session. In order to open an ESSO session, the user must enter user code and password. In order to reopen it, the user must enter user code and password again (unless Kerberos login succeeds) #### Logout Allows you to close an ESSO session. On closing session, any SSO rules will be unloaded, so the user should enter the user and password on applications request. #### SSO Paused If the user disables ESSO, user and password will be required to execute any application, but ESSO session is still open on the server. #### SSO Enabled In order to inject ESSO rules, Soffid ESSO must be enabled. #### Update rules To update ESSO rules for the user account. ESSO will contact Soffid Synchronization server in order to get the Single Sign On rules for this account. Any granted permission or rule change will be applied immediately.
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/PUrm8Zojw4jQAEff-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/PUrm8Zojw4jQAEff-image.png)
# Linux User access ## How to access? When you try to connect to a Linux machine using Soffid ESSO, you will need to enter your username and password on the Linux login page. If the user does not exists in this machine, depending on the attribute "Create local accounts when there is no domain account" in Soffid ESSO configuration, a local user willl be created or not. - If the network is connected, depending on the Soffid ESSO configuration, a 2FA may be required, or you will be logged in directly. - If the network is not connected, also, depending on the Soffid ESSO configuration, you connect to the machine. When the network is re-established, Soffid ESSO will NOT ask for your credentials again in the Linux machine.

For more information about how to configure Soffid ESSO you can visit [the ESSO profile page](https://bookstack.soffid.com/books/federation/page/esso).

💻 Image ##### Credentials required [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/ZJLytqxNJ2drg8DK-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/ZJLytqxNJ2drg8DK-image.png) ##### 2FA required [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/GbJImQRUVqjP1rou-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/GbJImQRUVqjP1rou-image.png) ##### Soffid ESSO options [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-09/scaled-1680-/UbZHPIshtG8yGrA4-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-09/UbZHPIshtG8yGrA4-image.png)
## Esso Options On a host with ESSO installed an icon with the Soffid Logo will appear on the Windows taskbar. If the user clicks on the mouse's right button it will be able to do some different actions. #### Login Allows you to open an ESSO session. In order to open an ESSO session, the user must enter user code and password. In order to reopen it, the user must enter user code and password again (unless Kerberos login succeeds) #### Logout Allows you to close an ESSO session. On closing session, any SSO rules will be unloaded, so the user should enter the user and password on applications request. #### SSO Paused If the user disables ESSO, user and password will be required to execute any application, but ESSO session is still open on the server. #### SSO Enabled In order to inject ESSO rules, Soffid ESSO must be enabled. #### Update rules To update ESSO rules for the user account. ESSO will contact Soffid Synchronization server in order to get the Single Sign On rules for this account. Any granted permission or rule change will be applied immediately.
💻 Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2024-10/scaled-1680-/fi31clB6MmyxHTsq-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2024-10/fi31clB6MmyxHTsq-image.png)
# ESSO Scripting Language # ESSO Scripting Language ## Introduction The scripting language used is a full ECMAScript interpreter. Nevertheless, it's not a Javascript interpreter as it's used on web browsers. It only has the core elements of ECMAScript (Objects, Arrays, String, etc.) and a set of objects and functions specially designed for its purpouse. When the script is run, the elements matched, either window or HTML components, with a ref-as tag will be declared as global variable. Additionally, in the case of web applications, a global variable named document contains the reference to the full HTML document. Here are the supported functions and classes: 1. [Global functions](https://bookstack.soffid.com/books/esso/page/1-global-functions "1. Global functions") 1. [ESSO SendKeys syntax](https://bookstack.soffid.com/books/esso/page/11-esso-sendkeys-syntax "1.1. ESSO SendKeys syntax") 2. [secretStore object](https://bookstack.soffid.com/books/esso/page/2-secretstore-object "2. secretStore object") 3. [SystemInfo object](https://bookstack.soffid.com/books/esso/page/3-systeminfo-object "3. SystemInfo object") 4. [Window class](https://bookstack.soffid.com/books/esso/page/4-window-class "4. Window class") 5. [Document class](https://bookstack.soffid.com/books/esso/page/5-document-class "5. Document class") 6. [Element class](https://bookstack.soffid.com/books/esso/page/6-element-class "6. Element class") 7. [Collection class](https://bookstack.soffid.com/books/esso/page/7-collection-class "7. Collection class") 8. [File class](https://bookstack.soffid.com/books/esso/page/8-file-class "8. File class") 9. [Directory class](https://bookstack.soffid.com/books/esso/page/9-directory-class "9. Directory class") 10. [MailService class](https://bookstack.soffid.com/books/esso/page/10-mailservice-class "10. MailService class") 11. [NetworkResource class](https://bookstack.soffid.com/books/esso/page/11-networkresource-class "11. NetworkResource class") 12. [Registry class](https://bookstack.soffid.com/books/esso/page/12-registry-class "12. Registry class") 13. [ServerInfo class](https://bookstack.soffid.com/books/esso/page/13-serverinfo-class "13. ServerInfo class") 14. [Hll class (version 1.4.0)](https://bookstack.soffid.com/books/esso/page/14-hll-class-version-140 "14. Hll class (version 1.4.0)") # 1. Global functions Global functions can be used in an **action** element:
debug text: string Sends a message to the debug console.
sleep millis: int Stops script execution for the specified milliseconds. Never stops the execution of the application.
env text: string returns string Gets the value of an environment variable.
exec text: string \[Dir: string\] Run an external application. Optionally, you can specify a directory to change to.
execWait text: string \[Dir: string\] Executes external application and waits for its completion. Optionally, you can specify a directory to change to.
sendKeys text: string Simulates the pressing of the keys indicated. You can see more information on the [ESSO sendKeys syntax page](https://bookstack.soffid.com/books/esso/page/11-esso-sendkeys-syntax).
sendText text: string Simulates keystroke typed text. Unlike the SendKeys function, the text is sent, verbatim, without any interpretation.
alert text: string Displays a confirmation message to the user.
progress text: string Displays a progress message without confirmation from the user.
cancelProgress Hide progress message.
alertNoWait text: string A message, but does not expect the user confirmation.
# 1.1. ESSO SendKeys syntax ## SendKeys syntax The sendKeys function aims to perform as the user pressing keystrokes. Thus, the function SendKeys ("ABC") simulates to press those three letters. The keystrokes will be done independently of the application that generates them. Thus, it is possible to press keys that change the focused control or even the active application using sendKeys. To mimic the action of pressing to keys simultaneously, you can make use of modifiers. The available modifiers are listed at the attached table. So, to send the character ':' you can execute *sendKeys("+.")*. This combination will simulate pressing the Shift key along with '.'. In order to allow a simpler syntax, you can use parentheses to specify more than one key affected by modifiers. Thus, the function SendKeys ("+ (hello)") generates the word HELLO in upper case.
**Modifier** **Key**
@ WINDOWS
+ SHIFT
^ CTRL
% ALT
It should be noted that this method can not get accented letters as a parameter, but the combination necessary to generate the desired letter. This method has a big drawback. The combination of keys needed to get a letter can be different depending of the current keyboard layout. So, in order to send arbitrary text characters, it is recommended to use the function sendText. Additionally, the sendKeys function supports this “virtual keystrokes” that do not correspond to a specific key but an actual action do be done:
**Tag** **Action taken.**
VKEY {X} The virtual code key (VKEY) will be sent. It is useful to use non-standard keys.
XY {BEEP} A sound with a frequency X during Y time (in milliseconds).
{DELAY X} X milliseconds pause.
{DELAY = X} Make a dealy of X milliseconds between each simulated keystrokes.
{AppActivate WindowTitle} Bring foreground and activates the application with the specified title.
To send function keys, you can use the following codes:
**Key** **Tag** **Key** **Tag**
Backspace {BACKSPACE} or {BS} F1 {F1}
Break {BREAK} F2 {F2}
CapsLock {CAPSLOC} F3 {F3}
Delete {DELETE} or {DEL} F4 {F4}
Down arrow {DOWN} F5 {F5}
End {END} F6 {F6}
Enter {ENTER} or ~ F7 {F7}
Ex {ESC} F8 {F8}
Help {HELP} F9 {F9}
Home {HOME} F10 {F10}
Lnsert {INS} F11 {F11}
Left arrow {LEFT} F12 {F12}
Num Lock {NUMLOCK} F13 {F13}
Next page {PGDN} F14 {F14}
Previous page {PGUP} F15 {F15}
Print screen {PRTSC} F16 {F16}
Right Arrow {RIGHT} ^ {CARET}
Scroll Lock {SCROLL} ~ {Tilde}
Tab {TAB} { {LEFTBRACE}
Up arrow {UP} } {RIGHTBRACE}
\+ (Numeric keypad) {ADD} ( {LEFTPAREN}
\- (Numeric keypad) {SUBSTRCT} ) {RIGHTPAREN}
\* (Numeric keypad) {Multiply} windows (left) {LWIN} or {RWIN}
/ (Numeric keypad) {DIVIDE} windows (right) {RWIN}
+ {PLUS} context menu {APPS}
@ {AT}
Here are a few small examples :
**sendKeys parameter** **Effect**
{DELAY=50} 1\. Specifies a pause of 50 milliseconds between keystrokes.
@R 2\. Click Windows + R to invoke the run dialog command.
notepad~ 3\. Enter notepad and pressed enter.
hello world! 4\. Write "Hello world!".
%ua 5\. Click the button to Alt + u, to show the About dialog box ...
{Delay = 100} 1\. Specifies a pause of 100 milliseconds between keystrokes.
{AppActivate Calculator} 2\. Turn the calculator.
{ESC} 3\. Click ESC to clear the contents.
5\*7~ 4\. Write 5 \* 7 and pressed Enter.
{beep 1000 500} 5\. Makes noise.
^C 6\. Press Control-C to copy the contents.
{appactivate Notepad} 7\. Switch to notepad.
^E 8\. Click to e-control dial all.
{DEL} 9\. Click Delete to delete the contents.
Result of 5 \* 7 is: 10\. Writes "The result is 5 \* 7".
^V 11\. Click control-v hold the result..
{DELAY=500}{NUMLOCK}{CAPSLOCK}{SCROLL} 1\. Turn numbers, uppercase and scroll on in order.
{SCROLL}{CAPSLOCK}{NUMLOCK} 2\. Turn them off in the reverse order.
{DELAY=500} 1\. Specifies a pause of 500 milliseconds between keystrokes.
%? 2\. Click Alt-Space.
{DOWN 5} 3\. Click the down arrow five times.
# 2. secretStore object ## Introduction This object is always visible from any action, and provides access to the user's passwords and secrets. User passwords are always related to a system account. This is the object used to retrieve user and password in order to **inject credentials** into applications. ## Methods
getSecret text: string returns string Gets the value of a secret.
getAccounts system: string returns string \[\] Gets the list of accounts available for a given systemsecretStore object.
getAccount system: string returns string Gets the account to use a particular system. If more than one are available, the system will prompt the user for the one to use. If the user cancels the dialog box, an exception will be thrown. If no account is available, the undefined value will be returned.
getPassword system: string account: string returns string Gets the password bound to the account on the system requested.
setPasswordsystem: string account: string newPassword: string Changes the password at the password vault (version 1.4)
setSecretname: string value: string Sets the value of a secret at the password vault (version 1.4)
generatePasswordsystem: string account: string returns string Generates a random password suitable for the selected account (version 1.4)
# 3. SystemInfo object ## Introduction The SystemInfo object is always visible from any **action**, and provides access to information about the machine. ## Attributes
os string Specifies the name of the operating system: Windows / Ubuntu
oSVersion string Indicates the version of the operating system.
osDistribution string Distributor operating system: Microsoft / Ubuntu / RedHat / ....
hostName string Return the team name.
clientHostName string For remote connections, returns the name of the source host.
fileSeparator string Separator files depending on the platform: / Linux \\ For Windows
username string Operating system user name. It can be different from Soffid user name.
# 4. Window class ## Introduction When an action is bound with a user interface application, it creates an object of class Window for each component at the XML descriptor with a ref-as attribute. Those components have the following methods: ## Methods
getText returns string Gets the text value of the component.
setText text: string Change the text value of a component.
click Acts as if the user clicks on the component. It's suitable on button components.
setFocus Move the focus to the component.
# 5. Document class ## Introduction When an action is associated with a Web application, it creates a document that identifies the full HTML document. This object assigned to the document variable. Thus, scripts can access the web contents and its DOM tree in runtime. The document object implement a subset of the standard DOM HtmlDocument. ## Attributes
url string Full URL of the document.
domain string Contains the domain of the page.
title string Title of the document.
cookie string Contains cookies that are bound to this document.
anchors Collection Contains elements of type A.
forms Collection Contains items of type FORM.
images Collection Contains items from IMG.
links Collection Contains elements of type A and AREA.
documentElement Item Contains the root element.
## Methods
getElementById id: string Element returns Find the first element with the specified ID.
getElementsByTagName tag: string returns Collection Find all elements with the specified tag.
write text: string Add content to the document.
writeln text: string Add content and new line to the document.
autofilltext: stringProceed with smart auto fill engine, allowing end user to select and or save accounts. The mandatory parameter sets the domain where to look for accounts.
# 6. Element class ## Introduction The objects of type Element are created for each input element with a ref-as attribute, or are obtained from the Document itself. It implements a subset of the DOM class HtmlElement. ## Attributes
childNodes Collection Vector of children elements.
disabled bool Indicator whether the element is disabled or not.
id string Id attribute of the element.
tagName string Element's tag.
parentNode Item Parent element.
## Methods
getAttribute name: string returns string Gets the attribute value of the element.
setAttribute name: string value: string Updates the attribute value.
removeAttribute name: string Removes an attribute.
getElementsByTagName tag: string returns Collection Find all children with the specified tag.
click Acts as if the user had clicked on the button.
blur Remove focus.
focus Grants focus.
submit Send form contents.
# 7. Collection class ## Introduction The collection object implements a subset of the standard DOM HTMLCollection ## Attributes
length Long Number of items in collection.
## Methods
item id: long returns Element Find the element with id order number. The first element is 0.
namedItem id: string returns Element Search for an item with the given name. First search an element with matching Id attribute. If none is found, search for an element with matching Name attribute.
# 8. File class ## Introduction It allows easy manipulation of files using the File class. ## Constructor
File file: string mode: string Create an object of type File for the specified file. If mode is “r”, the file will be opened in read mode. If mode is “w”, the file will be opened in write mode. If the mode is “a”, the file will be open in append mode.
## Methods
read byte int (1000) returns string Reads at most the specified number of bytes. When no numer is specified, 1000 bytes will be read at most.
readLine returns string Reads untill end of line.
write text: string Writes the specified text.
WriteLine text: string Writes text with and end of line.
close Closes the file.
flush Flush all buffers to disk.
eof returns boolean Returns true if the end of file has been reached.
## (static) methods and attributes Additionally, the File object has the following (static) methods and attributes:
mkdir directory: string Creates the specified directory.
stdin File Attribute that contains a File object associated with standard input.
stdout File Attribute that contains a File object associated with standard output.
stderr File Attribute that contains a File object associated with the standard error output.
copy source: string target: string Copy selected file. This method is not able to copy directories.
delete file: string Deletes a file or directory.
move source: string target: string Moves (or renames) a file or directory.
isDirectory f: string returns boolean Returns true if the specified file is a directory.
canRead f: string returns boolean Returns true if the file can be read.
canWrite f: string returns boolean Returns true if the file can be written.
getParent f: string returns string Returns the parent directory of a file.
# 9. Directory class ## Introduction This class is able to look for directories content. A directory object has the following attributes and methods: ## Constructor
Directory file: string Creates a directory object bound to the specified path.
## Methods
length returns int Indicates the number of files in the directory.
item return string Specifies the name of the file content.
# 10. MailService class ## Introduction Simple tool to send emails. The MailService object has the following methods. ## Constructor
MailService Create an object of type MailServer.
## Methods
setServer server: string Specifies the name of the mail server.
setFrom from: String Specifies the name of the sender.
Setter to: string Specifies the name of the recipient.
send text: string Send the message indicated.
# 11. NetworkResource class ## Introduction Connect and disconnect network services (disks and printers). ## Constructor
NetworkResource Creates an object of type NetworkResource.
## Methods
connectPrinter resource: string model: string Connects a remote printer to the local spooler.
connectDrive localDrive: string resource: string password: string (optional) user: string (optional) Connects a network drive.
disconnectAllPrinters Disconnects all remote printers.
disconnectPrinter name: string Disconnects a remote Printer.
disconnectDrive localName: string Disconnects a remote drive.
# 12. Registry class ## Introduction Manipulate the windows registry. ## Constructor
Registry path: string Create an object of type Registry
## Global objects
Registry.HKEY\_LOCAL\_MACHINE Tree Key LOCAL\_MACHINE
Registry.HKEY\_CURRENT\_USER Tree CURRENT\_USER key
Registry.HKEY\_USERS Tree Key USERS
Registry.HKEY\_CLASSES\_ROOT Tree Key CLASSES\_ROOT
Registry.HKEY\_LOCAL\_MACHINE32 Tree LOCAL\_MACHINE 32-bit keys
Registry.HKEY\_CURRENT\_USER32 Tree CURRENT\_USER key 32bit
Registry.HKEY\_USERS32 Tree 32bit key USERS
Registry.HKEY\_CLASSES\_ROOT32 Tree CLASSES\_ROOT 32-bit keys
## Methods
openKey path: string returns Registry Opens a registry subkey.
createKey path: string returns Registry Creates a registry subkey.
getValue entryName: string Object returns Reads registry value.
setValue entryName: string value: Object type: string Updates a registry value. Type (optional) can be: \- REG\_SZ \- REG\_EXPAND\_SZ \- REG\_BINARY \- REG\_DWORD \- REG\_MULTI\_SZ
# 13. ServerInfo class ## Introduction This helper class allows the script to query information stored at Soffid console. ## Constructor
ServerInfo path: string Queried the server returning an object of type ServerInfo.
## Methods
length returns int Returns the number of rows obtained.
row n: int object returns Returns information about the n-throw from.
The objects returned depend on the path indicated. # 14. Hll class (version 1.4.0) ## Introduction The Hll class gives the script engine access to Hll terminal emulators. When a hll pattern matches the emulator screen, a hll object of class Hll will be crated and can be used by the action script. ## Attributes
sessionId string Full URL of the document.
sessionName string Contains the domain of the page.
columns int Numer of columns.
rows int Number of rows.
## Methods
getCursorLocation returns object with row and column attributes Gets the cursor location.
setCursorLocation row: integer column: integer Changes cursor location.
getContent returns String Gets the terminal emulator screen content.
sendText text: string Send text to host.
sendKeyskeys:stringSend text, possibly containing escape sequences.
## Escape sequence The following escape sequence are defined:
Mnemonic
Meaning
3270
5250
VT
@BLeft TabYesYesNo
@CClearYesYesNo
@DDeleteYesYesNo
@EEnterYesYesNo
@FErase EOFYesYesNo
@HHelpNoYesNo
@IInsertYesYesNo
@JJump (Set Focus)YesYesNo
@LCursor LeftYesYesYes
@NNew LineYesYesYes
@OSpaceYesYesYes
@PPrintYesYesYes
@RResetYesYesNo
@TRight TabYesYesYes
@UCursor UpYesYesYes
@VCursor DownYesYesYes
@X\*DBCS (Reserved)YesYesNo
@ZCursor RightYesYesYes
@0HomeYesYesNo
@1PF1/F1YesYesNo
@2PF2/F2YesYesNo
@3PF3/F3YesYesNo
@4PF4/F4YesYesNo
@5PF5/F5YesYesNo
@6PF6/F6YesYesYes
@7PF7/F7YesYesYes
@8PF8/F8YesYesYes
@9PF9/F9YesYesYes
@aPF10/F10YesYesYes
@bPF11/F11YesYesYes
@cPF12/F12YesYesYes
@dPF13YesYesYes
@ePF14YesYesYes
@fPF15YesYesYes
@gPF16YesYesYes
@hPF17YesYesYes
@iPF18YesYesYes
@jPF19YesYesYes
@kPF20YesYesYes
@lPF21YesYesNo
@mPF22YesYesNo
@nPF23YesYesNo
@oPF24YesYesNo
@qEndYesYesNo
@uPage UpNoYesNo
@vPage DownNoYesNo
@xPA1YesYesNo
@yPA2YesYesNo
@zPA3YesYesNo
@A@CTestNoYesNo
@A@DWord DeleteYesYesNo
@A@EField ExitYesYesNo
@A@FErase InputYesYesNo
@A@HSystem RequestYesYesNo
@A@IInsert ToggleYesYesNo
@A@JCursor SelectYesYesNo
@A@LCursor Left FastYesYesNo
@A@QAttentionYesYesNo
@A@RDevice Cancel (Cancels Print Presentation Space)YesYesNo
@A@TPrint Presentation SpaceYesYesYes
@A@UCursor Up FastYesYesNo
@A@VCursor Down FastYesYesNo
@A@ZCursor Right FastYesYesNo
@A@9Reverse VideoYesYesNo
@A@bUnderscoreYesNoNo
@A@cReset Reverse VideoYesNoNo
@A@dRedYesNoNo
@A@ePinkYesNoNo
@A@fGreenYesNoNo
@A@gYellowYesNoNo
@A@hBlueYesNoNo
@A@iTurquoiseYesNoNo
@A@jWhiteYesNoNo
@A@lReset Host ColorsYesNoNo
@A@tPrint (Personal Computer)YesYesNo
@A@yForward Word TabYesYesNo
@A@zBackward Word TabYesYesNo
@A@-Field -NoYesNo
@A@+Field +NoYesNo
@A@<Record BackspaceNoYesNo
@S@EPrint Presentation Space on HostNoYesNo
@S@xDupYesYesNo
@S@yField MarkYesYesNo
@W@C Edit Copy Yes Yes Yes
@W@D Edit Clear Yes Yes Yes
@W@E Edit Copy Append Yes Yes Yes
@W@L Edit Copy Link Yes Yes Yes
@W@N Edit Paste Next Yes Yes Yes
@W@V Edit Paste Yes Yes Yes
@W@X Edit Cut Yes Yes Yes
@W@Z Edit Undo Yes Yes Yes
@X@1Display SO/SIYesYesNo
@X@5Generate SO/SINoYesNo
@X@6Display AttributeNoYesNo
@X@7Forward CharacterNoYesNo
@X@cSplit Vertical BarNoYesNo
@M@0VT Numeric Pad 0NoNoYes
@M@1VT Numeric Pad 1NoNoYes
@M@2VT Numeric Pad 2NoNoYes
@M@3VT Numeric Pad 3NoNoYes
@M@4VT Numeric Pad 4NoNoYes
@M@5VT Numeric Pad 5NoNoYes
@M@6VT Numeric Pad 6NoNoYes
@M@7VT Numeric Pad 7NoNoYes
@M@8VT Numeric Pad 8NoNoYes
@M@9VT Numeric Pad 9NoNoYes
@M@-VT Numeric Pad -NoNoYes
@M@,VT Numeric Pad ,NoNoYes
@M@.VT Numeric Pad .NoNoYes
@M@eVT Numeric Pad EnterNoNoYes
@M@fVT Edit FindNoNoYes
@M@iVT Edit InsertNoNoYes
@M@rVT Edit RemoveNoNoYes
@M@sVT Edit SelectNoNoYes
@M@pVT Edit Previous ScreenNoNoYes
@M@nVT Edit Next ScreenNoNoYes
@M@aVT PF1NoNoYes
@M@bVT PF2NoNoYes
@M@cVT PF3NoNoYes
@M@dVT PF4NoNoYes
@M@hVT HOld ScreenNoNoYes
@M@(space)Control Code NULNoNoYes
@M@AControl Code SOHNoNoYes
@M@BControl Code STXNoNoYes
@M@CControl Code ETXNoNoYes
@M@DControl Code EOTNoNoYes
@M@EControl Code ENQNoNoYes
@M@FControl Code ACKNoNoYes
@M@GControl Code BELNoNoYes
@M@HControl Code BSNoNoYes
@M@IControl Code HTNoNoYes
@M@JControl Code LFNoNoYes
@M@KControl Code VTNoNoYes
@M@LControl Code FFNoNoYes
@M@MControl Code CRNoNoYes
@M@NControl Code SONoNoYes
@M@OControl Code SINoNoYes
@M@PControl Code DLENoNoYes
@M@QControl Code DC1NoNoYes
@M@RControl Code DC2NoNoYes
@M@SControl Code DC3NoNoYes
@M@TControl Code DC4NoNoYes
@M@UControl Code NAKNoNoYes
@M@VControl Code SYNNoNoYes
@M@WControl Code ETBNoNoYes
@M@XControl Code CANNoNoYes
@M@YControl Code EMNoNoYes
@M@ZControl Code SUBNoNoYes
@M@uControl Code ESCNoNoYes
@M@vControl Code FSNoNoYes
@M@wControl Code GSNoNoYes
@M@xControl Code RSNoNoYes
@M@yControl Code USNoNoYes
@M@zControl Code DELNoNoYes
@Q@AVT User Defined Key 6NoNoYes
@Q@BVT User Defined Key 7NoNoYes
@Q@CVT User Defined Key 8NoNoYes
@Q@DVT User Defined Key 9NoNoYes
@Q@EVT User Defined Key 10NoNoYes
@Q@FVT User Defined Key 11NoNoYes
@Q@GVT User Defined Key 12NoNoYes
@Q@HVT User Defined Key 13NoNoYes
@Q@IVT User Defined Key 14NoNoYes
@Q@JVT User Defined Key 15NoNoYes
@Q@KVT User Defined Key 16NoNoYes
@Q@LVT User Defined Key 17NoNoYes
@Q@MVT User Defined Key 18NoNoYes
@Q@NVT User Defined Key 19NoNoYes
@Q@0VT User Defined Key 20NoNoYes
@Q@aVT BacktabNoNoYes
@Q@rVT Clear PageNoNoYes
@Q@sVT EditNoNoYes
@@@YesYesYes
@$Alternate Cursor (The Presentation Manager Interface only)YesYesYes
@<BackspaceYesYesYes
@:@sScreen ReverseYesYesYes
@:@nBidi LayerYesYesYes
@:@lLatin LayerYesYesYes
@:@FField ReverseYesYesNo
@:@pPushYesNoNo
@:@eEnd PushYesNoNo
@:@aAuto PushYesNoNo
@:@rAuto ReverseYesNoNo
@:@dCSDYesNoNo
@:@fFinalYesNoNo
@:@iIsolatedYesNoNo
@:@mMiddleYesNoNo
@:@tInitialYesNoNo
@:@hField ShapeYesNoNo
@:@uField BaseYesNoNo
@:@bBaseNoYesNo
@:@oCloseNoYesNo
@:@KColumn HeadingNoNoYes
@:@BCursor DirectionNoNoYes
@:@DEncoding ModeNoNoYes
@:@MVT Change Display ModeNoNoYes (Hebrew only)
# ESSO Scripting examples 1\. Run an application like notepad ``` exec ("notepad.exe"); ``` 2\. Automatic application update ```Java if (SystemInfo.os == "Linux") { exec ("(mkdir /tmp/google-chrome-updates && " + " wget -O /tmp/google-chrome-updates/google-chrome-stable_current_amd64.deb " + " -c https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb " + " && apt-get update && sudo apt-get install libappindicator1 " + " && sudo dpkg -i /tmp/google-chrome-updates/google-chrome-stable_current_amd64.deb " + " && sudo apt-get install google-chrome-stable) " + " >/var/log/google-chrome-stable_current_amd641.log 2>&1 " ); } ``` 3\. ```shell account = secretStore.getAccount("soffid.org-ldap"); debug("Account = "+account); u.setAttribute("value", account); password = secretStore.getPassword("soffid.org-ldap", account); debug("Password = "+password); p.setAttribute("value", password); sleep(100); debug("Clicking"); b.click(); debug("Clicked"); ``` # How to add to ESSO a second factor of authentication? ## Introduction Soffid allows you to add a second factor of authentication by configuring a parameter in Soffid Console and the Second Factor Authentication (2FA). ## Step by step 1. First of all, you need to configure the **addon.federation.essoidp** parameter. The value must be the Identity Provider Identifier: [![image-1685446185526.png](https://bookstack.soffid.com/uploads/images/gallery/2023-05/scaled-1680-/image-1685446185526.png)](https://bookstack.soffid.com/uploads/images/gallery/2023-05/image-1685446185526.png) 2. Then, you need to add the 2FA in the proper Identity Provider: [![image-1685521019693.png](https://bookstack.soffid.com/uploads/images/gallery/2023-05/scaled-1680-/image-1685521019693.png)](https://bookstack.soffid.com/uploads/images/gallery/2023-05/image-1685521019693.png) # How to upgrade ESSO? ## Introduction Once ESSO is installed, configured and operational, it is very likely that **an update will be required** at some point. There are many **reasons** for updating: - To keep up to date with the latest versions. - To adapt to changes in the operating system. - To resolve bugs or fixes. - To adapt to new versions of Soffid. - To include new features. - How to upgrade ESSO in Linux? ## How to upgrade ESSO in Linux? Installation on Linux or Windows is very simple, you just need to run the new installer again. This is explained in more detail below. 1. **Download** the new version of the installer, please go to the Soffid [Enterprise downloads](https://download.soffid.com/download/enterprise/) page in the Enterprise Single Sign On (ESSO seccion).

Please note that in Linux, the installer depends on the version of Linux.

2. Execute the **installer** of the new version. Open a Terminal, navigate to the directory where your downloaded file is located, and run the installer command: ``` sudo dpkg -i "the-name-of-your-file.deb" ``` 3. Now, for the system to apply the changes, you need to **log out** and then **log in** again. 4. To **veify** that you are using the correct version, you can check this information by clicking on the Soffid ESSO component icon in your browser, which will open a popup window displaying the version. ## How to upgrade ESSO in Windows? Installation on Linux or Windows is very simple, you just need to run the new installer again. This is explained in more detail below. 1. **Download** the new version of the installer, please go to the Soffid [Enterprise downloads](https://download.soffid.com/download/enterprise/) page in the Enterprise Single Sign On (ESSO seccion). 2. Execute the **installer** of the new version.

Please note that administrator permissions are required to run the administrator.

Please follow these steps: - Go to the **directory** where the downloaded file is located - Double click to **install** - In the first Windows pop-up, click on "**More information**" and then "**Run anyway**". - In the next popup from the installer, follow the steps, click **Next**, **Accept**, **Install**, **OK**, **Finish**, **Yes**. 3. After the final "Yes", the system wil **restart** to apply the changes. 4. To **veify** that you are using the correct version, you can check this information by clicking on the Soffid ESSO component icon in your browser, which will open a popup window displaying the version. ## Unable to select a soffid user after the update? If, after updating, the option to use Soffid users does not appear, it is very likely that you have an old configuration.
Image ![image.png](https://bookstack.soffid.com/uploads/images/gallery/2026-01/scaled-1680-/LzZsMnzMW5niTtOx-image.png)
You will probably need to update the ESSO configuration so that it points to Soffid's idp instead of Syncserver.

For further information, please refer to the [ESSO installation](https://bookstack.soffid.com/books/esso "ESSO") page.

Finally, this will be the correct option.
Image [![image.png](https://bookstack.soffid.com/uploads/images/gallery/2026-01/scaled-1680-/MDL9X6wGYGzC8LaU-image.png)](https://bookstack.soffid.com/uploads/images/gallery/2026-01/MDL9X6wGYGzC8LaU-image.png)