Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor changes to text



Three methods of user authentication - Shiro, LDAP and Database - and user authorization can be implemented for the JobScheduler JOC Cockpit. A general description of the authentication and authorization is presented in the JOC Cockpit - Authentication and Authorization article. This article describes the configuration required to implement each of the three authentication methods as well as user authorization. This configuration information is held in an Apache ShiroTM .ini file and is used not only by the JOC Cockpit but also by the JobScheduler Web Services API.


This article describes the file-based configuration of user authentication and authorizarion. authorization by directly editing the shiro.ini file. The JOC Cockpit provides a graphical editing option for an editor for the configuration of authentication and user authorization, which is described in the JOC Cockpit - Managing Authentication and Authorization for User Accounts article

Configuration File Structure


The shiro.ini file is delivered with an a default configuration for Shiro authentication. This configuration includes a number of user profiles - one of which (root:root) is active and has a role all with all permissions. This profile allows a system administrator to log onto the JOC Cockpit GUI and access all of its features after installation. A system administrator can then use the Account Manager GUI Once the root User has created an administrative user account with the necessary permissions, this account can be used to implement other user profiles, set and change passwords and, if required, deactivate the root profile.


Default authorization profiles are provided in the shiro.ini file. System administrators are free to edit these profiles as required.


The shiro.ini File Location

The location of the shiro.ini file is dependent on whether or not the Jetty web server included with the JOC Cockpit installation archive is installed with the JOC Cockpit.

Location of the shiro.ini file when Jetty is Installed with the JOC Cockpit

If the Jetty provided as part of the JOC Cockpit distribution is installed with the JOC Cockpit then the shiro.ini file can be found in the resources sub-folder in the jetty_base directory where the jetty_base directory is specified during the installation process of the JOC Cockpit. See the JOC Cockpit - Installation article for more information.

  • On Windows systems the default location for the resources directory will be:
    • C:\ProgramData\\joc\resources\joc
  • On Unix systems the default location will be:
    • /home/[user]/

Location of the shiro.ini file when Jetty is not Installed with the JOC Cockpit

If the Jetty provided as part of the JOC Cockpit distribution is not installed with the JOC Cockpit then the location of the shiro.ini file and resources directory will depend on previous installation history. See the Configuration with Alternative Web Servers section of the JOC Cockpit - Installation article for more information.

In this situation the shiro.ini file and other resources can be moved by the system administrator to an appropriate directory in the web server to be used.

shiro.ini File Syntax Restrictions

Upper case letters and special characters should not be used, blank spaces within names should be avoided.

JOC Cockpit Updates

A first installation of the JOC Cockpit will write a single instance of the shiro.ini file to the resources/joc folder. As the shiro.ini file is intended to be modified by system administrators, an update or a full installation of the JOC Cockpit that finds an existing shiro.ini file will not overwrite this file but create a shiro.ini-example file alongside the .ini file. This new file will contain the current example configuration and give system administrators a reference configuration containing any configuration updates.

The Internal shiro.ini File Structure

The shiro.ini file will have between two and four sections, depending on the authentication method specified and whether or not folder permissions are specified. These sections are:

  • [users]
    • Contains authentication information when Shiro authentication is used.
    • Contains the roles assigned to users after authentication when Shiro authentication is used.
    • Is not required for other authentication methods.
  • [main]
    •  If LDAP authentication is to be used:
      • contains configuration information for accessing the LDAP directory service;
      • contains a mapping of LDAP groups onto JOC Cockpit authorization roles.
    •  If Database authentication is to be used:
      • contains configuration information for accessing the database via Hibernate.
    • Contains session timeout information for the JOC Cockpit.
    • Is required for all authentication methods.
  • [roles]
    • Contains the JOC Cockpit authorization information - i.e. the permissions assigned to roles.
    • Is required for Shiro and LDAP authentication methods.
  • [folders]
    • Optional for all authentication methods.
    • Defines the set of folders that are available for a role.

Note that:

  • The default configuration does not include the [folders] section - this is only required when folder Permissions are configured and will be either dynamically added by the Add Folder function in the Manage Accounts view or should be manually added if the shiro.ini file is being directly configured.
  • The order in which these sections are positioned in the shiro.ini file is not important.

[users] Configuration

This section contains the authentication information when Shiro authentication is used. It is only required when the Shiro authentication is used.


  • "As delivered" only one user/role mapping is active - root, with a default password as shown in the listing above. The other user configurations are commented out. System administrators can add and modify these configurations as required.
  • It should be clear that the default passwords should replaced either before user profiles are activated or as soon as possible afterwards.
  • In this default configuration user names and role names are identical. This is not necessary.
  • Passwords are stored in open text. Password encryption is not available with Shiro authentication.
  • Note that the api_user is not intended for use with the JOC Cockpit but instead for use by other applications accessing the JobScheduler Web Services.


  • user=password, role1, role2
  • Where:
    • user is the user name.
    • password is saved in open text.
    • role entries must be identical to roles specified in the [roles] section of the file. Any number of roles can be assigned to a user. Multiple roles are separated by commas.
    • Each entry is specified on a new line, password and role are separated by a comma.

Role Name Restrictions:

    • The JOC Cockpit will only show the names of a limited set of roles. These are:
      • the roles defined in the default configuration and listed above - i.e.
        • administrator,

        • application_manager,

        • it_operator,

        • incident_manager,

        • business_user,

        • api_user,

        • root

      • a number of additional role names:
        • events,

        • joc,

        • joe,

        • jid,

        • workingplan,

        • controller,

        • jobeditor,

        • joc_admin,

        • admin,

        • super

  • Role names may not contain a blank space.

[roles] Configuration

This section contains the authorization information i.e. the mapping of roles onto permissions. This section is required when either Shiro or LDAP authentication is used.