Introduction

Scope

This article describes the configuration of user authentication and authorization by directly editing the shiro.ini file and is therefore directly applicable to the 1.11.x Releases and Release 1.12.0. This method of configuration can be used with all three methods of user authentication and authorization - Shiro, LDAP and Database - for these releases.

...

Migration of an existing configuration from a shiro.ini file to the Reporting database takes place automatically as part of the update procedure. After migration the shiro.ini file is deleted and the new shiro.ini.active file generated. 

Revert shiro.ini to default values

Download the file shiro.ini-example, rename the file to shiro.ini then login to JOC Cockpit (no restart required).

Using the example shiro.ini file activates password hashing an allows access with the user account: root and password: root.

Configuration File Structure

...

[users]
#administrator=secret, administrator
#application_manager=secret, application_manager
#it_operator=secret, it_operator
#incident_manager=secret, incident_manager
#business_user=secret, business_user
#api_user=secret, api_user
root=root, all

...

The default user account information for Shiro authentication for releases 1.11.5 and newer with hashed passwords is shown in the listing below:

...

1. Update the JOC Cockpit to release 1,11.5 following the procedure described in the JOC Cockpit - Installation article.
2. Start the Jetty Web Server / check that the Web Service is running.
3. Log into the JOC Cockpit with a user account that has edit permissions for the Manage Accounts view. (In the default configuration root and administrator accounts have the necessary permissions.)
4. Go to the Manage Accounts view in the JOC Cockpit. Ensure that the Accounts tab is selected, showing the current user accounts.

5. Copy and uncomment the following two lines from the [main] section of the shiro.ini-example file to the [main] section of the shiro.ini file:

   Code Block
   language text
   passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher iniRealm.credentialsMatcher = $passwordMatcher

6. Delete all user accounts from the shiro.ini.active file (they will not be lost from the JOC Cockpit).
7. Save the shiro.ini.active file.
8. Open the Edit Account modal window for any user.
9. Click on Submit.
10. All user accounts (Account Names, Passwords and Roles) will now be written back into the shiro.ini file by the JOC Cockpit and the Passwords will now be saved as hashed values. Users will be able to log in as before the update and new Passwords can be entered in plain text and will be saved as hashed values.
11. Save the shiro.ini.active file under the name shiro.ini
12. logout
13. login

Activating Password Hashing in Releases 1.11.0 to 1.11.4

...

Multiple instances of the JOC Cockpit can be configured to operate as an active cluster. This requires a load balancer and session sharing between the JOC Cockpit instances. See the JOC Cockpit - Authentication and AuthorizationClustering article for an introduction to Clusteringmore information.

Database Authentication

System administrators can implement database authentication manually, using a separate database to the JobScheduler(s) and, if required, a separate DBMSthe tables stored in the reporting database.

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 user management in the JOC Cockpit can not be used, when users and roles are stored in the database.

The [users] and [roles] sections of the shiro.ini file can be deleted or completely commented out when database authentication is to be used. Please note that until 1.13.4 there must be empty sections for users and roles.

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

...

• 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).

[main]
hibernateRealm = com.sos.auth.shiro.SOSHibernateAuthorizingRealm
 
securityManager.realms = $hibernateRealm
cacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
securityManager.cacheManager = $cacheManager
securityManager.sessionManager.globalSessionTimeout = 900000

Maintenance and Security Considerations

While access in order to manipulate the 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

...

create table sos_user(
id number(9) not null ,
sos_user_name varchar2(250),
sos_user_password varchar2 (250),
PRIMARY KEY ( "ID" )
)


create table sos_user_role(
id number(9) not null ,
sos_user_role varchar2(250),
PRIMARY KEY ( "ID" )
)


create table sos_user2role(
id number(9) not null ,
role_id number(9) null ,
user_id number(9) null ,
PRIMARY KEY ( "ID" )
)


create table sos_user_permission(
id number(9) not null ,
role_id number(9) null ,
user_id number(9) null ,
sos_user_permission varchar2(250),
PRIMARY KEY ( "ID" )
)

The following table names and structure have to be used when configuring database authentication:

Table of User Names and Passwords (SOS_USER

...

) - Structure

...

...

...

...

Table of User Names and Passwords (SOS_USER) - Contents

The password is stored MD5 encrypted. E.g. secret is 5ebe2294ecd0e0f08eab7690d2a6ee69

...

...

Table

...

of Roles

...

(SOS_USER_

...

ROLE) - Structure

...

...

...

...

...

Table mapping users to roles

...

...

...

...

...

...

...

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 users and roles to Permissions (SOS_USER_PERMISSION) - Structure

Table Mapping Roles to Permissions (SOS_USER_PERMISSION) - Contents

...

...

...

...

...

...

...

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

...

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_user can only access the /nested/*  and /split/* folders on scheduler_id1 but will have permission to access all folders on scheduler_id2.
• The it_operator and admin roles have permissions for the sos subfolders 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.ini file is not validated by the JOC Cockpit. This means that a configuration error will lead to that entry not being processed.
  
  • 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

Logging

To get a debug log file for the login procedure please add this to the file $JETTY_BASE/resources/joc/log4j.properties

#logger for security
log4j.logger.com.sos.auth=debug, shiro
log4j.additivity.com.sos.auth= false
log4j.appender.shiro = org.apache.log4j.FileAppender
log4j.appender.shiro.layout = org.apache.log4j.EnhancedPatternLayout
log4j.appender.shiro.layout.ConversionPattern = %d{ISO8601}{Europe/Berlin} %-5p %m%n%throwable{short}
#filename of shiro log
log4j.appender.shiro.File = ${jetty.base}/logs/JOCShiroLog.log

Additional Information

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_user can only access the /nested/*  and /split/* folders on scheduler_id1 but will have permission to access all folders on scheduler_id2.
• The it_operator and admin roles have permissions for the sos subfolders 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.ini file is not validated by the JOC Cockpit. This means that a configuration error will lead to that entry not being processed.
  
  • 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

Logging

Logging of user Authentication can be configured in the $JETTY_BASE/resources/joc/log4j.properties file. See the JOC Cockpit - Logging article for more information.

Additional Information

Jetty does not have Jetty has to be restarted after changes are made to the [main] section of the shiro.ini file.

...

• For detailed information about the complete permission set see 
  • Authentication and Authorization - Permissions for the JOC Cockpit Web Service
  • Authentication and Authorization - Permissions for the JobScheduler REST Web Service

...