ESSO

• ⏰ Getting started
• How to install ESSO?
• ESSO Installation Windows (from 3.3.3-enterprise to 3.4.3-enterprise)
• ESSO Installation Windows (+3.5.0-enterprise)
• ESSO Installation Linux
• Startup process
• Enforcing browser addons
• ESSO Configuring Rules for Single Sign On
• Configuring Rules for Single Sign On
• Support and configuration tools
• ESSO Scripting Language
• Configuring terminal emulation SSO
• ESSO Related configuration parameters
• ESSO Manuals
• Windows Administrator access
• Linux Administrator access
• Windows user access
• Linux User access
• ESSO Scripting Language
• ESSO Scripting Language
• 1. Global functions
• 1.1. ESSO SendKeys syntax
• 2. secretStore object
• 3. SystemInfo object
• 4. Window class
• 5. Document class
• 6. Element class
• 7. Collection class
• 8. File class
• 9. Directory class
• 10. MailService class
• 11. NetworkResource class
• 12. Registry class
• 13. ServerInfo class
• 14. Hll class (version 1.4.0)
• ESSO Scripting examples
• How to add to ESSO a second factor of authentication?

⏰ 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.
2. Run it as administrator. Once the interactive installation has finished, a message window will notice you:
   
   
   
3. Finally, the system will prompt you to configure Soffid ESSO. This prompt will not be shown on updates or silent installations.
   
   

   
   

   

   
   
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.

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:

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:

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:

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:

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

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

The GUUID of Soffid ESSO group policy is {53252A52-D536-11DF-866D-5B82D67A00D1}

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.

2. Install as administrator. Once the interactive installation has finished, a message window will notice you:

3. Finally, the system will prompt you to configure Soffid ESSO. This prompt will not be shown on updates or silent installations.

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.

4. After configuring the system, it's required to reboot the computer.

For more information, you can visit the Windows user acces page and the Windows Administrator access page. 

Configure the ESSO Profile

1. Then you need to configure the ESSO profile in your Identity Provider

💻 Image

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

2. And finally, you can configure the Adaptive authentication rules

💻 Image

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:

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:

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

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

The GUUID of Soffid ESSO group policy is {53252A52-D536-11DF-866D-5B82D67A00D1}

ESSO Installation Linux

Introduction

Here you can find the details about the ESSO installation.

Installation

sudo dpkg -i '<your_path>/MazingerInstaller-3.5.2-enterprise.deb'

💻 Image

Interactive configuration

1. To configure, you need to run the following command with your Soffid Identity Provider URL.

sudo configure_esso https://<YOUR_IdP_URL>:443

💻 Image

2. Then you need to configure the ESSO profile in your Identity Provider

💻 Image

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

3. And finally, you can configure the Adaptive authentication rules

💻 Image

 

For more information, you can visit the Linux Administrator access page and  the Linux user acces page. 

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

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

The GUUID of Soffid ESSO group policy is {53252A52-D536-11DF-866D-5B82D67A00D1}

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

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

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

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:

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:

The Component element allows the following attributes:

The Action element accepts the following attributes:

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.

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:

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:

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.

The Action element accepts the following attributes:

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:

<Mazinger>
  <WebTransport url="https://no-soffid.bubu.lab:4443/" system="OSCM"/>
  <WebTransport url="https://no-ad.bubu.lab/" system="ad" domain="AD"/>
</Mazinger>

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:

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 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

<Mazinger>
<HllApplication>
  <Pattern row="2">.*SOFFID.*</Pattern>
  <Pattern row="23">.*ABC.*</Pattern>
  <Action type="script" event="onMatch" repeat="true" delay="1">
     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");
  </Action>
</HllApplication>
</Mazinger>

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.

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

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.

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

How to check the log?

C:\Windows\System32\type mazinger-install.log

💻 Image

How to run the configuration?

C:\Program Files\SoffidESO\SoffidConfig.exe

💻 Image

How to check the status?

C:\Program Files\SoffidESSO>Shirokabuto debug

💻 Image

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

How to check the log?

/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

How to login using the command line?

Raise permissions to super users:

sudo -i

Login with your Soffid user

login userName

💻 Image

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.

💻 Image

Credentials required

2FA required

 Soffid ESSO options

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

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.

💻 Image

 Credentials required

 2FA required

Soffid ESSO options

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

 

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
   1. ESSO SendKeys syntax
2. secretStore object
3. SystemInfo object
4. Window class
5. Document class
6. Element class
7. Collection class
8. File class
9. Directory class
10. MailService class
11. NetworkResource class
12. Registry class
13. ServerInfo class
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.
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.

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:

To send function keys, you can use the following codes: 

Here are a few small examples :

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

3. SystemInfo object

Introduction

The SystemInfo object is always visible from any action, and provides access to information about the machine.

Attributes

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

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

Methods

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

Methods

7. Collection class

Introduction

The collection object implements a subset of the standard DOM HTMLCollection

Attributes

Methods

8. File class

Introduction

It allows easy manipulation of files using the File class.

Constructor

Methods

(static) methods and attributes

Additionally, the File object has the following (static) methods and attributes:

9. Directory class

Introduction

This class is able to look for directories content. A directory object has the following attributes and methods:

Constructor

Methods

10. MailService class

Introduction

Simple tool to send emails. The MailService object has the following methods.

Constructor

Methods

11. NetworkResource class

Introduction

Connect and disconnect network services (disks and printers).

Constructor

Methods

12. Registry class

Introduction

Manipulate the windows registry.

Constructor

Global objects

Methods

13. ServerInfo class

Introduction

This helper class allows the script to query information stored at Soffid console.

Constructor

Methods

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

Methods

Escape sequence

The following escape sequence are defined:

ESSO Scripting examples

1. Run an application like notepad

exec ("notepad.exe");

2. Automatic application update

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) " +
		  " </dev/null >>/var/log/google-chrome-stable_current_amd641.log 2>&1 "
          );
}

3.

<Mazinger>
  <WebApplication url="https://jira.soffid.com/.*"  >
    <Input id="login-form-username" ref-as="u"/>
    <Input id="login-form-password" ref-as="p"/>
    <Input id="login" ref-as="b"/>
    <Action event="onLoad" type="script" repeat="true" delay="5">
      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");
    </Action>
  </WebApplication>
</Mazinger>
                  

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:

2. Then, you need to add the 2FA in the proper Identity Provider: