Introduction

There might be situations when users lock the door behind them and throw away the key to access the JOC Cockpit, for example:

• if JS7 - Identity Services are used that are based on external access to an Identity Provider, such as an JS7 - LDAP Identity Service that is not accessible.
• if a misconfiguration occurs that prevents an Identity Service from authenticating and/or authorizing a user account, for example due to missing permissions.

In such situations a key service is required to open the door.

Rescue Script

The Rescue Script is available to administrators with access to the server which the JOC Cockpit is operated on.

Identify the JOC Cockpit Installation Directory

JOC Cockpit by default is installed:

• for Unix in the
  • installation directory: /opt/sos-berlin.com/js7/joc
• for Windows in the
  • installation directory:  Program Files\sos-berlin.com\js7\joc

However, the installation directory can be freely chosen during setup.

If in doubt try to identify where JOC Cockpit is located from running processes:

• For Unix execute the command
  • ps -ef | grep js7 or ps -ef | grep joc
  • This should return processes related to JS7. The process in question includes the characters "joc" and should indicate its installation directory.
• For Windows use the Task Manager to identity a process with the name 
  • js7_joc.exe
  • Adding the "command line" column to the display of processes with the Task Manager should reveal the installation directory.

Run the Rescue Script to create the JOC-RESCUE Identity Service

The JOC Cockpit installation directory includes a sub-folder install that holds the Rescue Script:

• joc_install_tables.sh for Unix,
• joc_install_tables.cmd for Windows.

Run the Rescue Script like this:

./joc_install_tables.sh --rescue

Notes:

• Note that the Rescue Script requires the java executable to be included in the directories specified by your PATH environment variable.
• If in doubt then identify the location of your Java JDK or JRE and execute for example:
  • PATH=$PATH:/usr/lib/java/jdk/bin
  • provided that your java executable is located in /usr/lib/java/jdk/bin

joc_install_tables.cmd --rescue

Notes:

• The Rescue Script requires the java.exe executable to be included in the directories specified by your PATH environment variable.
• If in doubt then identify the location of your Java JDK or JRE and execute for example
  • set PATH=%PATH%;C:\Program Files\Java\jdk\bin
  • provided that your java.exe executable is located in C:\Program Files\Java\jdk\bin

The Rescue Script will perform the following actions:

• The Rescue Script acts on the JS7 - Database and works independently of whether or not the JOC Cockpit is started or not.
• The Rescue Script:
  • disables any existing Identity Services,
  • adds an Identity Service of type JOC with the name JOC-RESCUE,
    • adds an administrative role for full access to JOC Cockpit with the name all to the Identity Service,
    • adds a user account with the name root and the password root to the Identity Service.

After the Rescue Script has been executed you can login to JOC Cockpit by specifying the following credentials:

• user: root
• password root

Repair Identity Services

After login you should find:

• a new Identity Service JOC-RESCUE is active:
  • this Identity Service includes a single user account root with the all role that is granted full permissions
• any previously configured Identity Services are disabled.

This is the perfect point in time to reconfigure the offending Identity Service(s) that prevented users from login.

• Only enable the offending Identity Service(s) after having reworked their configuration.
• It is recommended that Identity Services are made optional during the repair phase and not to use required Identity Services.

Then try to login to JOC Cockpit using accounts specified for the repaired Identity Service(s).

Remove JOC-RESCUE Identity Service

When things are back to normal then delete the JOC-RESCUE Identity Service.

• Deleting the Identity Service includes:
  • deleting the user account root from the Identity Service (other Identity Services still can use a user account with this name which is local to the Identity Service),
  • deleting the all role of the Identity Service,
  • deleting the Identity Service configuration.