Introduction
Three methods of authentication - Shiro, LDAP and Database - can be implemented for the JobScheduler Cockpit. These methods are described in the JOC Cockpit - Authentication and Authorization article. This article describes the configuration required to implement each of the three authentication methods. This configuration is held in an Apache ShiroTM .ini file.
Configuration File Structure
The Default Configuration
Shiro Authentication
The shiro.ini file is delivered with a set of (default) information for Shiro authentication. This information includes an active profile for a default user (root) which has all permissions. This profile allows a system administrator to log onto the JOC Cockpit and access all of its features after installation. After installation a system administrator can modify the shiro.ini file to implement other user profiles and deactivate the root profile.
LDAP and Database Authentication
Default information for LDAP and Database authentication is not included with the JOC Cockpit. However example configurations are presented in this article to provide system administrators with sufficient information to implement these types of authentication themselves.
File Location
The location of the shiro.ini file is dependent on whether or not 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 jetty_base directory:
- On Windows systems the default location for the
jetty_basedirectory will be:C:\ProgramData\sos-berlin.com\joc
- On Unix systems it will be:
/home/[user]/sos-berlin.com/joc
If the Jetty provided as part of the JOC Cockpit distribution is not installed with the JOC Cockpit then the shiro.ini file can be found in the JOC Cockpit resources directory:
- On Windows systems the default location will be:
C:\Program Files\sos-berlin.com\joc\resources
- On Unix systems it will be:
...< PATH TO BE COMPLETED
- In this situation the
shiro.inifile and other resources must be moved by the system administrator to the appropriate application directory.
The Internal File Structure
The shiro.ini file will have two or three sections, depending on the authentication method specified:
- [users]
- Contains the roles assigned to users.
- Contains authentication information when Shiro authentication is used.
Is not required for other authentication methods.
- [roles]
- Contains the permissions assigned to roles.
- Required for all authentication methods.
- [main]
- Contains timeout information and, if relevant, information for LDAP or Database authentication.
- Required for all authentication methods.
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.
Default user information for seven users is delivered with the JOC Cockpit in this section as shown in the listing below, with a role 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 the configuration file (described below).
The default user information provided with the JOC Cockpit 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/role mappings are commented out. System administrators can add and modify mappings configurations as required.
- In this default configuration user names and roles are identical. This is not necessary.
- Passwords are stored in open text. Password encryption is not available with Shiro authentication.
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. Multiple roles separated by commas can be specified for a user.
- Each entry is specified on a new line, password and role are separated by a comma.
[roles] Configuration
This section contains the mapping of roles onto permissions. This section is required when either Shiro or LDAP authentication is used.
A default mapping of seven roles is delivered with the JobScheduler. The roles in this mapping correspond with the seven roles specified in the [users] section of the file. This mapping is shown in the listing below:
Syntax
role=permission1, \
permission2- where:
- permissions are separated by commas (","),
- each permission is shown in the ini file on a new line to ease readability,
- a backward slash after each permission is used to mark the end of a line in the .ini file,
- 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 - User Exclusiondemo = sos:products, \ -sos:products:joc_cockpit:jobscheduler_master_cluster:view:status, \ -sos:products:joc_cockpit:order
The ID of a JobScheduler can be used to allow or disallow access a particular JobScheduler or Master cluster
The following example shows the JobScheduler "scheduler_1" is allowed access to all SOS products but "scheduler_2" is only allowed limited permissions for JobScheduler Masters and all permissions on JobScheduler Universal Agents.
Shiro Configuration - JobScheduler IDsdemo = scheduler_1:sos:products, \ scheduler_2:sos:products:joc_cockpit:jobscheduler_master:view, \ 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
- The full matrix of permissions is shown in the Matrix of Roles and Permissions section of the JOC Cockpit - Authentication and Authorization article.
Users can add additional and modify role configurations as required.
[main] Configuration
This 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 timeout. The default timeout setting is 20 minutes as shown in the listing below:
[main] securityManager.sessionManager.globalSessionTimeout = 1200000
Syntax
- Timeout is specified in milliseconds.
LDAP Authentication
The [users] section of the shiro.ini file can be deleted or completely commented out when LDAP authentication is to be used.
Role names are mapped onto LDAP group names.
The information required in the [main] section for LDAP authentication is shown in the listing below.
[main]
ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.userDnTemplate = cn={0},CN=myLDAPFolder,DC=localhost
ldapRealm.searchBase = CN=myLDAPFolder,DC=localhost
ldapRealm.contextFactory.url = ldap://localhost:389
#ldapRealm.groupNameAttribute=memberOf
#ldapRealm.userNameAttribute=cn
ldapRealm.userSearchFilter=(&(objectClass=user)(cn=%s))
# Mapping of a ldap group to roles. You can assign more than one role with separator sign |
ldapRealm.groupRolesMap = \
"CN=JobScheduler_it_operator,CN=Roles,CN=ur_dell_partition,DC=localhost":"it_operator", \
"CN=jobscheduler_admin,CN=Roles,CN=myLDAPFolder,DC=localhost":"administrator|application_manager"
rolePermissionResolver = com.sos.auth.shiro.SOSPermissionResolverAdapter
rolePermissionResolver.ini = $iniRealm
ldapRealm.rolePermissionResolver = $rolePermissionResolver
securityManager.realms = $ldapRealm
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
securityManager.sessionManager.globalSessionTimeout = 360000
It should only be necessary for system administrators to modify three parts of this section:
- the LDAP service information in lines 4 to 6 of the listing,
- the mapping of LDAP groups to roles in lines 13 to 16, which id described in the next sub-section and
- the timeout setting for sessions as shown in the last line 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 allocated 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 allocated the roles of administrator and application_manager.
Database Authentication
The [users] section of this file can be deleted or completely commented out.
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 = 1200000
Hibernate is used in the example listed to address an Oracle database. 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:
- the location of the Hibernate configuration file location in line 3 of the listing,
- the default timeout setting, which is 20 minutes (specified in milliseconds as shown) as shown:
Maintenance and Security Considerations
While access in order to manipulate authentication information a database requires the database password, a system administrator has to manually enter and modify user passwords with the associated security risks and maintenance costs.
Example Database Tables
The following table structure could be used for a database authentication configuration:
Table of User Names and Passwords (SOS_USER)
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 Roles (SOS_USER_ROLE)
COLUMN_NAME DATA_TYPE NULLABLE DATA_DEFAULT COLUMN_ID COMMENTS 1 ID NUMBER(9,0) No (null) 1 (null) 2 SOS_USER_ROLE VARCHAR2(250 BYTE) Yes (null) 2 (null) Table Mapping Roles to Permissions
COLUMN_NAME DATA_TYPE NULLABLE DATA_DEFAULT COLUMN_ID COMMENTS 1 ID NUMBER(9,0) No (null) 1 (null) 2 ROLE_ID VARCHAR2(250 BYTE) Yes (null) 2 (null) 3 SOS_USER_PASSWORD VARCHAR2(250 BYTE) Yes (null) 3 (null) Table Mapping Roles to Permissions
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)
Error Handling
- TODO
- Was passiert wenn, z.B. ein Tippfehler in eine Permission gemacht wird?
Note
Jetty has to be restarted after changes are made to the shiro.ini file.
Additional Information
Text to be added ....