Introduction
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. The JOC Cockpit provides a graphical editing option for configuration of authentication and user authorization. Scope
Configuration File Structure
The Default Configuration
Shiro Authentication
The shiro.ini file is delivered with an 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 to implement other user profiles, change passwords and, if required, deactivate the root profile.
The location of the shiro.ini file after installation of the JOC Cockpit is described below.
LDAP and Database Authentication
An example configuration for LDAP and Database authentication is not included with the JOC Cockpit. However, example configurations are presented later in this article to provide system administrators with sufficient information to implement these types of authentication themselves.
Authorization
Default authorization profiles are provided in the shiro.ini file. System administrators are free to edit these profiles as required.
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 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
resourcesdirectory will be:C:\ProgramData\sos-berlin.com\joc\resources\joc
- On Unix systems the default location will be:
/home/[user]/sos-berlin.com/joc/resources/joc
Location 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.
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 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.
- If LDAP authentication is to be used:
- [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.
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.
User information for seven example users is delivered with the JOC Cockpit as shown in the listing below, with a role and password being mapped onto each user name. These roles are described in more detail in the Matrix of Roles and Permissions section of the JOC Cockpit - Authentication and Authorization article. The roles are then mapped onto permissions in the [roles] section of this file (described below).
The default user information for Shiro authentication is shown in the listing below:
- "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.
Syntax
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
- the roles defined in the default configuration and listed above - i.e.
- The JOC Cockpit will only show the names of a limited set of roles. These are:
[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.
An default mapping of seven roles is delivered with the JOC Cockpit installation. The roles in this mapping correspond with the seven roles specified in the [users] section of the file. System administrators can add additional and modify role configurations as required. The default mapping is shown in the listing below:
Note the following:
- The default mapping provided with the JOC Cockpit installation is only a subset of all the permissions that can be set. A full list of the permissions available is included in the Authentication and Authorization - Permissions for the JOC Cockpit Web Service article.
- The permissions for the api_user are not provided for the JOC Cockpit but for the JobScheduler Web Services API. For this reason the permissions structure is different and uses:
sos:products:commands:...instead ofsos:products:joc_cockpit:....
Syntax
role=permission1, \
permission2- where:
- permissions are separated by commas (","),
- each permission is shown in the
.inifile on a new line to ease readability, - a backward slash after each permission is the line continuation character,
- individual permissions are specified hierarchically, with each "level" being separated by a colon (":"),
- spaces (" ") are not allowed in user names,
- a wildcard ("*") can be used for all permissions,
a minus sign ("-") can be used at the start of a permission to disallow a user access to a resource that they would otherwise be able to use (See, for example the permission set for the api_user in the listing above).
The following example shows the role demo is allowed access to all products but is not allowed to see status of JobScheduler Master Clusters or any information related to Orders in the JOC Cockpit.Shiro Configuration - Permisisons Exclusiondemo = sos:products, \ -sos:products:joc_cockpit:jobscheduler_master_cluster:view:status, \ -sos:products:joc_cockpit:orderGranting and denying of permissions is carried out according to the union principle from set theory - all permissions granted are brought together and then all permissions denied are removed.
- The order in which roles and permissions are denied or removed is not important.
To illustrate this point consider the - perhaps artificial - situation where a user is given two roles: api_user and incident_manager, defined in the order shown in the code block below and each with their default permissions as listed above.The api_manager role allows the demo_user to carry out all job-related operations in the JOC Cockpit with the exception of viewing the job configuration. For convenience, these permissions are shown in the code block below.
The incident_manager role allows the demo_user to view all job-related operations.
Shiro Configuration - Multiple Roles[users] demo_user=secret, api_user, incident_manager [roles] api_user = ... sos:products:joc_cockpit:job, \ -sos:products:joc_cockpit:job:view:configuration, \ ... incident_manager = ... sos:products:joc_cockpit:job:view, \ ...- Regardless of the order in which the roles of the demo_user are defined, the demo_user will be able to view job all job operations except job configuration.
- The full default matrix of permissions is shown in the Matrix of Roles and Permissions section of the JOC Cockpit - Authentication and Authorization article.
- Roles and permissions are configurable to the following extent:
- What cannot be changed:
- The number and type of permissions is fixed.
- What can be changed:
- The number of roles can be changed.
- The permission value yes / no can be changed for each permission in each role.
- Restrictions:
- The JOC Cockpit will only show the names of a limited set of roles. These are listed in the [users] Configuration section above.
- What cannot be changed:
Multiple JobScheduler Master Instances
The default role configuration grants roles with the same permissions for all JobScheduler Masters or Master Clusters in a scheduling environment.
The ID of a JobScheduler Master or Master Cluster can be used to allow or disallow access to that Master or Master cluster.
The following example shows the JobScheduler Master with ID "scheduler_1" being granted access by all operations but for JobScheduler Master with ID "scheduler_2" only allowed limited permissions are granted and all permissions on JobScheduler Universal Agents.
- Note that the
jobscheduler_master:viewpermission should never be restricted to a particular JobScheduler ID as this will prohibit all other JobScheduler Masters from being seen. See the block below for an example configuration:
demo = sos:products:joc_cockpit:jobscheduler_master:view, \
scheduler_1:sos:products, \
scheduler_2:sos:products:joc_cockpit:jobscheduler_master:pause, \
scheduler_2:sos:products:joc_cockpit:jobscheduler_master:continue, \
scheduler_2:sos:products:joc_cockpit:jobscheduler_master:restart, \
scheduler_2:sos:products:joc_cockpit:jobscheduler_universal_agent
[main] Configuration
The contents of this section depend on the authentication method used.
Shiro Authentication
The only information required in the [main] section for Shiro authentication is a session timeout. The default session timeout setting is 15 minutes as shown in the listing below:
[main] securityManager.sessionManager.globalSessionTimeout = 900000
Syntax
- Timeout is specified in milliseconds.
LDAP Authentication
Please note that you can specify the roles also in the [users] section like
username = , role1, role2
If you do not want to get the roles from the shiro.ini, please remove the [users] section.
The [main] section contains the following information:
- specification of the LDAP directory service,
- a mapping of the JOC Cockpit role names specified in the [roles] section of the file onto LDAP group names and
- a session timeout.
Getting the roles of an user
You have to specify:
ldapRealm.userDnTemplate = cn={0},CN=mycn,DC=localhost ldapRealm.searchBase = CN=mycn,DC=localhost ldapRealm.contextFactory.url = ldap://localhost:389 #ldapRealm.groupNameAttribute=memberOf #ldapRealm.userNameAttribute=cn
ldapRealm.groupRolesMap = \ "CN=??????,OU=?????,OU=?????,OU=?????,DC=domain,DC=local":"all"
ldapRealm.userSearchFilter=(&(objectClass=User)(cn=%s))+
%s will be substituted by the user.
To get the correct values for ldapRealm.userDnTemplate, ldapRealm.searchBase and ldapRealm.userSearchFilter
- please create a query that finds all groups the user is a member of
- set ldapRealm.userSearchFilter to this query with %s for the user name.
- Example: (&(objectClass=User)(cn=%s))
- Example: (uniqueMember=uid=%s,dc=example,dc=com)
- set ldapRealm.userSearchFilter to this query with %s for the user name.
- Then identify the attribute in the result that contains the groupName
- set ldapReal.groupNameAttribute to this value (default is memberOf)
- Then assign the value of attribute specified in groupNameAttribute to the groupRolesMap
- Example: ldapRealm.groupRolesMap="value in attribute groupNameAttribute":"it_operator
- The userDnTemplate is identifiying the user entry in ldap (e.g. the value of uniqueMember)
Example LDAP Configuration
An example for LDAP configuration is provided with the listing below:
It should only be necessary for system administrators to modify three parts of this section:
- the LDAP directory service information in lines 4 to 6 of the listing,
- the mapping of LDAP groups to roles - here occupying lines 13 to 16 and which is described in the next sub-section and
- the timeout setting for sessions as shown in the last line of the listing and which is specified in milliseconds.
Example Mapping LDAP Groups to Roles:
- In line 15 of the listing above members of the JobScheduler_it_operator LDAP group are assigned the it_operator role
- More than one role can be specified for members of an LDAP group - for example:
- in line 16 members of the LDAP jobscheduler_admin group are assigned the roles of administrator and application_manager.
Example LDAP Configuration with a public LDAP Server
There are many ways of configuring LDAP authentication and authorization. The method you use depends on the structure of groups and users in your LDAP Server. You will find a working example for use with a public LDAP Server described on:
We cannot guarantee that the public LDAP Server will always be online, however, if you struggle with LDAP configuration then you might want to give it a try to have a working example.
Assigning roles in the shiro.ini when using LDAP
It is possible to mix LDAP authentication with local authorization from a shiro.ini file.
- In the
[users]section- specify the user name but do not specify a password for the user.
- specify the list of roles that are assigned to this user.
- Important: The assignment must start with a comma to skip the password assignment.
- In the
[main]section- you do not have to specify the LDAP group mapping to roles.
The roles specified with the user assignment and the roles retrieved from the
ldapRealm.groupRolesMapmapping will be added to the user.
Example LDAP Configuration for a public LDAP Server with local roles
Database Authentication
System administrators can implement database authentication manually, using a separate database to the JobScheduler(s) and, if required, a separate DBMS.
The JOC Cockpit configuration required to use database authentication is described in this section along with an example set of database tables. System administrators have to configure and maintain the database and tables manually as well as their query strings - there is neither a GUI available for this nor is batch support provided.
The [users] and [roles] sections of the shiro.ini file can be deleted or completely commented out when database authentication is to be used.
The information required in the [main] section for database authentication is shown in the following listing:
[main] hibernateRealm = com.sos.dialog.auth.SOSHibernateAuthorizingRealm hibernateRealm.hibernateConfigurationFile=C:\Users\userName\Documents\sos-berlin.com\jobscheduler\scheduler_current\config\hibernate.cfg.oracle.xml securityManager.realms = $hibernateRealm cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager securityManager.cacheManager = $cacheManager securityManager.sessionManager.globalSessionTimeout = 900000
Hibernate is used to access the database - in the example listed above an Oracle database is specified. System administrators must organize the necessary configuration information to address the database to be used to store authentication information themselves.
It should only be necessary for system administrators to modify two parts of this section of the shiro.ini file:
- the location of the Hibernate configuration file in line 3 of the listing,
- the default timeout setting, which is in the example is 15 minutes (specified in milliseconds as shown).
Maintenance and Security Considerations
While access in order to manipulate authentication information a database requires the database password, a system administrator still has to manually enter and modify user passwords with the associated security risks and maintenance costs.
Example Database Tables
The following table names and structure have to be used when configuring database authentication:
Table of User Names and Passwords (SOS_USER) - Structure
COLUMN_NAME DATA_TYPE NULLABLE DATA_DEFAULT COLUMN_ID COMMENTS 1 ID NUMBER(9,0) No (null) 1 (null) 2 SOS_USER_NAME VARCHAR2(250 BYTE) Yes (null) 2 (null) 3 SOS_USER_PASSWORD VARCHAR2(250 BYTE) Yes (null) 3 (null)
Table of User Names and Passwords (SOS_USER) - ContentsID SOS_USER_NAME SOS_USER_PASSWORD 1 1 administrator secret 2 2 application_manager secret 3 3 it_operator secret 4 4 incident_manager secret 5 5 business_user secret 6 6 api_user secret 7 7 root root Table of Roles (SOS_USER_ROLE) - Structure
COLUMN_NAME DATA_TYPE NULLABLE DATA_DEFAULT COLUMN_ID COMMENTS ID NUMBER(9,0) No (null) 1 (null) SOS_USER_ROLE VARCHAR2(250 BYTE) Yes (null) 2 (null) Table of Roles (SOS_USER_ROLE) - Contents
ID SOS_USER_ROLE 1 administrator 2 application_manager 3 it_operator 4 incident_manager 5 business_user 6 api_user 7 all Table Mapping Roles to Permissions (SOS_USER_PERMISSION) - Structure
COLUMN_NAME DATA_TYPE NULLABLE DATA_DEFAULT COLUMN_ID COMMENTS ID NUMBER(9,0) No (null) 1 (null) ROLE_ID NUMBER(9,0) Yes (null) 2 (null) USER_ID NUMBER(9,0) Yes (null) 3 (null) SOS_USER_ROLE VARCHAR2(250 BYTE) Yes (null) 4 (null) Table Mapping Roles to Permissions (SOS_USER_PERMISSION) - Contents
ID ROLE_ID USER_ID SOS_USER_PERMISSION 1 1 7 (null) 2 2 1 (null) 3 1 (null) sos:products 4 2 (null) sos:products:joc_cockpit:jobscheduler_master:view 5 2 (null) sos:products:joc_cockpit:jobscheduler_master:pause 6 2 (null) sos:products:joc_cockpit:jobscheduler_master:continue 7 2 (null) sos:products:joc_cockpit:jobscheduler_master:restart 8 2 (null) sos:products:joc_cockpit:jobscheduler_master:terminate 9 2 (null) sos:products:joc_cockpit:jobscheduler_master:abort 10 2 (null) sos:products:joc_cockpit:jobscheduler_master_cluster 11 2 (null) sos:products:joc_cockpit:jobscheduler_universal_agent Shown are the default permissions for user root (ID=7) mapped to role all (ID=1) and user administrator (ID=1) mapped to role administrator (ID=2).
[folders] Configuration
FEATURE AVAILABILITY STARTING FROM RELEASE 1.11.2
This feature is available from the following issues:
System Administrators can add a [folders] section to the shiro.ini file to define the folders that can be accessed by a role within the live folder of a JobScheduler configuration.
The following examples should make this clear:
[folders] it_operator = /sos/*, /nested/*, /split/* business_user = /* admin = /abcd, /sos/*
In the examples:
- the it_operator role has recursive access to the
/sos, /nestedand/splitfolders and all their sub-folders; - the business_user role has access to the whole live folder and
- the admin role has recursive access to the
/sosfolder and non-recursive access to the/abcdfolder. It does not have access to any sub-folders of the/abcdfolder.
Note:
- The default configuration - i.e. when no folders are specified for a Role - is that a Role has access to all folders within the live folder.
- If access to a folder is specified then access for that Role to all other folders is automatically denied. Any access required to other folders has then to be specified individually.
- Access is not inherited unless specified using
/*, in which case it is inherited to all child folders. - If a Job Chain contains a Job that is located in a different folder and permission has not been granted for the Job folder, then the functions from the Job menu will still be available in the JOC Cockpit as the Job Chain already has the necesary permissions.
- It is not necessary for the Jetty server to be restarted before changes made to folder permissions are implemented - a simple log-out and log-in is sufficient.
Folder Permissions for Users with Multiple Roles
When a user has multiple roles - for example, incident_manager and business_user - then the folder permissions for both roles will be added together and treated as if the permissions had been set for a single role. This means that if, for example, a permission is specified for the incident_manager role and one user has both incident_manager and business_user roles, then all folder permissions for users with the business_user role will automatically be withdrawn.
Folder Permissions for Specific JobSchedulers
Folder permisions can also be specified for specific JobScheduler Masters.
When a permission is specified for one JobScheduler Master it does not automatically affect the permissions for all other JobScheduler Masters accessed from the JOC Cockpit.
In the example below:
- The
business_usercan only access the/nested/*and/split/*folders onscheduler_id1but will have permission to access all folders onscheduler_id2. - The
it_operatorandadminroles have permissions for thesossubfolders on all JobScheduler Masters.
[folders] scheduler_id2|it_operator = /test* scheduler_id2|my_role = /abcd scheduler_id1|it_operator = /nested/*, /split/* scheduler_id1|business_user = /nested/*, /split/* scheduler_id1|my_role = /abcd, it_operator = /sos/* admin = /sos/*
Error Handling
- The
shiro.inifile is not validated by the JOC Cockpit. This means that a configuration error will lead to that entry not being implemented.- For example, a spelling error in a permission will lead to that permission not being set.
- The permissions granted for an account can be inspected in the JOC Cockpit interface by logging into the interface using that account and checking the Permissions section of the User Profile view
Additional Information
Jetty has to be restarted after changes are made to the shiro.ini file.
References
- For detailed information about the complete permission set see