Skip to content

Metrics Configuration

Jump to bottom
lheffner edited this page Apr 25, 2013 · 1 revision

Configuration

Default Configuration

The Metrics Service bundle is configured to run by default on localhost with a predefined set of users. In addition to users.properties, the Metrics Service provides two override files which are used to modify the default configuration.

To utilize an override file, place the individual file somewhere on the classpath of the server running the Metrics Service. When using the default Tomcat bundle, externalized configuration files should be placed in the folder \apache-tomcat-7.0.21\lib. By default, MetricConfig.groovy is located in \apache-tomcat-7.0.21\lib. The other override file, CASSpringOverrideConfig.xml, is located in the Metrics bundle at \etc\override. If using an application server other than Tomcat, copy the override files into the directory that will include them in the classpath for that specific application server.

The two optional override files are:

  • CASSpringOverrideConfig.xml
  • MetricConfig.groovy

Each of the override files is detailed in sections that follow.

Adding Users/Roles/Groups

At this time, the Metrics Service only stores users/roles/groups information in its database. Administrators may want to configure this information for future use. The addition of users, groups, and roles depends on the choice of security implementation. The following example outlines the procedures for adding users, groups, and roles to the sample OWF X.509-only, CAS-only, and X.509-with-CAS security modules:

Note: The sample security modules are included as examples and should NOT be used in a production environment.

    …
    testUser1=password,ROLE_USER,Test User 1,[group1;I am a sample Group 1 from users.properties;test@gmail.com;active]
    testUser2=password,ROLE_USER,Test User 2
    testUser3=password,ROLE_USER,Test User 3
    testAdmin1=password,ROLE_ADMIN,Test Admin 1,[group1;I am a sample Group 1 from users.properties;test@email.com;active],[group2;I am a sample Group 2 from users.properties;test2@email.com;active],[group3;I am a sample Group 3 from users.properties;test3@email.com;inactive]
    …

Note: To have actual spaces between names and numbers, escape spaces using the “\” character (do not include the quotation marks). Moreover, when using CAS or a custom setup which employs anything other than X.509 authentication, the user names MUST be entered in all lower case. This is a technical issue with Spring Security and will be remedied in a future release.

Edit \apache-tomcat-7.0.21\lib\users.properties:

  1. Add a user(s) to the file in accordance with the following rules: A. Data Format:
    Username=password, role, display name,[group name, group description, group contact email, active/inactive status] B. All of the information for a single user, including group information, should be on a single line C. Multiple groups may be delimited by commas D. Group information is optional, and may be left out for any single given user
  2. Save the file and restart the Metrics Service server.

Any user added to users.properties will be granted access to the Metrics Service upon restart. Any user deleted from users.properties will be denied access to the Metrics Service upon restart.

Note: If a custom Web server is being used along with the provided example security, the users.properties file can be copied to any directory that is on the classpath of the webserver being utilized. For example, if using Jetty, the file can be copied to the \<jetty root>\resources directory.

To add users to any security module utilizing X.509 authentication, a PKI User certificate that can be recognized by the Metrics Service must be generated.

Custom Configuration

Metrics Service externalized configuration files are MetricConfig.groovy and CASSpringOverrideConfig.xml. When the Metrics Service is deployed to a non-localhost environment, the externalized configuration files must be deployed and modified. Those modifications are explained in the individual sections about each file.

Use of a production quality database like Oracle or MySQL, instead of the default HSQLDB, will require a change to the MetricsConfig.groovy file, detailed in the following section.

MetricsConfig.groovy File

MetricConfig.groovy is a Metrics Service configuration file that allows an administrator to modify the database connectivity information see the Database Setup section on the Metrics Installation page. Once changes are made, restart the system to apply the changes. Developers comfortable with the Groovy language and the Grails application framework should be comfortable writing additional code for this file.

Listed below is an example of the file in its entirety:

    environments {
        production {
            dataSource {
                dbCreate = "none"
                username = "sa"
                password = ""
                driverClassName = "org.hsqldb.jdbcDriver"
                url = "jdbc:hsqldb:file:MetricsDb;shutdown=true"
                pooled = true
                properties {
                    minEvictableIdleTimeMillis = 180000
                    timeBetweenEvictionRunsMillis = 180000
                    numTestsPerEvictionRun = 3
                    testOnBorrow = true
                    testWhileIdle = true
                    testOnReturn = true
                    validationQuery = "SELECT 1 FROM INFORMATION_SCHEMA.SYSTEM_USERS"
                }
            }
            //enable uiperformance plugin which bundles and compresses javascript
            uiperformance.enabled = true
        }
    }

    beans {
                    
                    //This block is equivalent to using an org.springframework.beans.factory.config.PropertyOverrideConfigurer
                    //See Chapter 14 of the Grails documentation for more information: http://grails.org/doc/1.1/
                    
    }

    //databasemigration settings
    grails.plugin.databasemigration.updateOnStart = false


    println('MetricsConfig.groovy completed successfully.')

metric-override-log4j.xml file

General logging can be enabled by editing the Metric-override-log4j.xml file which can be found in the apache-tomcat-7.0.21\lib directory:

    <logger name="AuditOWFWebRequestsLogger" additivity="false">
      <level value="error" />
      <appender-ref ref="ozone-async" />
    </logger>

    <!-- For security logging, set this log level to "info". -->
    <logger name="ozone.securitysample.authentication.audit.SecurityAuditLogger" additivity="false">
      <level value="info" />
      <appender-ref ref="ozone-async-audit" />
    </logger>

    <!—Add this to enable general Metrics Debug logging -->
    <logger name="grails.app" additivity="false">
      <level value="trace" />
      <appender-ref ref="ozone-async" />
    </logger>

Note: The Metric-override-log4j.xml file shown above does not ship with the code shown at the bottom of the sample. However, it can be pasted into the file at an administrator’s discretion in order to enable the logging of general server debug messages.

To confirm that the log files are being written, examine the apache-tomcat-7.0.21\logs directory. Developers familiar with Log4j configurations should be comfortable with this file.

Note: Useful configurations and common requests are called out in comments in the file. For example, audit logging describing each user’s Web calls can be enabled by setting AuditOWFWebRequesterLogger and ozone.filter to logging level info.

Different third party libraries within the Metrics Service have also been called out so that administrators can easily modify logging levels.

Audit Logging

The Metrics Service includes an option to audit all user entries and exits from the system. The Metrics Service bundle ships with this feature enabled by default. The Audit Log tracks the following types of changes:

  • Both successful and unsuccessful login attempts
  • User Logout Events:
    • A user logging out on purpose
    • A session times out

Note: References to the CAS and Metrics Service must match the settings of the current installation.

Configuring Audit Log Levels

Metrics Service logging levels can be set by editing the /apache-tomcat-7.0.21/lib/metric-override-log4j.xml file, which ships with the Metrics Service bundle. To change the audit log level, open the file and search for the following section:

    <!-- For security Audit logging, set this log level to "info". -->
     <logger name="ozone.securitysample.authentication.audit.SecurityAuditLogger" additivity="false">
        <level value="info" />
        <appender-ref ref="ozone-async-audit" />
    </logger>

The log statement shown above, ozone.securitysample.authentication.audit.SecurityAuditLogger, captures login and logout events. But, in debug mode, the logger will record authentication credentials, such as SubjectDN, IssuerDN and validity dates for X.509 Certificate logins, as well as CAS credentials for CAS login. When deploying a custom security plugin, use the logger shown above to capture all login events for the system. This logger supports “info”, “debug” and “off” levels, as described in the section below.

When distributed, the default log level is set to “info”. Audit logging supports the following three log levels:

  1. Info - The minimal amount of information concerning a database change is logged and consists of the following fields within the log statement: A. Log Level - This will set to “INFO” or “DEBUG” while logging is turned on. B. Log Date/Time - The date and time that an event occurred. The time pattern can be changed by editing the layout tag of the ozone-audit-log appender. C. Remote IP - The IP address of the remote client that triggered the log event. D. Session ID - The HTTP request session ID of the log event. E. User - The username of the authenticated user that caused the log event. F. Event Type - USER LOGIN or USER LOGOUT. G. Event Message - A description of the event.
  2. Debug - This level provides all of the same information as the INFO level, but provides more detail in the event message.
  3. Off - No login events will be logged.

When the audit log levels are modified, it is not necessary to restart the Metrics Service, as the server has a log-change listener which periodically (every 3 minutes, by default) checks for log file changes and reloads the changes.

Login Events

When using the sample pluggable security modules included in the Metrics Service bundle, successful login authentication is captured in ListenerBeans.xml.

A login failure will occur and be recorded in the log if a user has a valid PKI certificate but the associated username is not registered as a valid user within the Metrics Service. A failed login produces the following log statement at the info level:

    INFO [02/15/2011 15:24:04 -0500] IP: 127.0.0.1 User: testAdmin1 [USER LOGIN]: LOGIN FAILURE - ACCESS DENIED with FAILURE MSG [Login for 'testAdmin1' attempted with authenticated credentials [CERTIFICATE LOGIN]; However, the Provider was not found. Access is DENIED.]

A failed login produces the following log statement at the debug level:

    DEBUG [02/15/2011 15:27:18 -0500] IP: 127.0.0.1 User: testAdmin1 [USER LOGIN]:LOGIN FAILURE - ACCESS DENIED with FAILURE MSG [Login for 'testAdmin1' attempted with authenticated credentials [CERTIFICATE LOGIN >> Signature Algorithm: [SHA1withRSA, OID = 1.2.840.113549.1.1.5]; Subject: [EMAILADDRESS=testAdmin1@nowhere.com, CN=testAdmin1, OU=Ozone, O=Ozone, L=Columbia, ST=Maryland, C=US]; Validity: [From: Thu Feb 04 13:58:52 EST 2010, To: Sun Feb 03 13:58:52 EST 2013]; Issuer: [EMAILADDRESS=ozone@nowhere.com, CN=localhost, OU=Ozone, O=Ozone, L=Columbia, ST=Maryland, C=US]; ]; However, the Provider was not found. Access is DENIED. Login Exception Message: [No AuthenticationProvider found for org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationToken]]

A successful PKI Certificate login produces the following log statement at the info level:

    INFO [02/15/2011 15:39:13 -0500] IP: 127.0.0.1 User: testAdmin1 [USER LOGIN]: LOGIN SUCCESS - ACCESS GRANTED USER [testAdmin1], with DISPLAY NAME [Test Admin 1], with AUTHORITIES [ROLE_ADMIN,ROLE_USER], with ORGANIZATION [Test Admin Organization], with EMAIL [testAdmin1@nowhere.com]with CREDENTIALS [CERTIFICATE LOGIN]

A successful PKI Certificate login statement produces the following log statement at the debug level:

    DEBUG [02/15/2011 15:42:10 -0500] IP: 127.0.0.1 User: testAdmin1 [USER LOGIN]:LOGIN SUCCESS - ACCESS GRANTED USER [testAdmin1], with DISPLAY NAME [Test Admin 1], with AUTHORITIES [ROLE_ADMIN,ROLE_USER], with ORGANIZATION [Test Admin Organization], with EMAIL [testAdmin1@nowhere.com] with CREDENTIALS [CERTIFICATE LOGIN >> Signature Algorithm: [SHA1withRSA, OID = 1.2.840.113549.1.1.5]; Subject: [EMAILADDRESS=testAdmin1@nowhere.com, CN=testAdmin1, OU=Ozone, O=Ozone, L=Columbia, ST=Maryland, C=US]; Validity: [From: Thu Feb 04 13:58:52 EST 2010, To: Sun Feb 03 13:58:52 EST 2013]; Issuer: [EMAILADDRESS=ozone@nowhere.com, CN=localhost, OU=Ozone, O=Ozone, L=Columbia, ST=Maryland, C=US]; ]

Logout Events

Logout events are logged by the ozone.securitysample.authentication.audit.SecurityAuditLogger. This logger supports the same two levels of logging: info and debug. The latter provides more detailed information about each logout event.

Below is a typical user-initiated logout event which has been saved as a log entry, with the log level set to info:

    INFO  [02/03/2011 16:13:35 -0500] IP: 127.0.0.1 SessionID: 8ki2ttimdxc User: testAdmin1 [USER LOGOUT]:

Below is a typical user-initiated logout event which has been saved as a log entry, with the log level set to debug:

    DEBUG [02/03/2011 15:59:53 -0500] IP: 127.0.0.1 SessionID: 1tjefhsxz1x6t User: testUser1 [USER SESSION TIMEOUT] with ID [2], with EMAIL [testUser1@nowhere.com], with ACCOUNT CREATED DATE [02/03/2011 15:58:50 -0500], with LAST LOGIN DATE [02/03/2011 15:58:50 -0500]

A user can also be forced to logout when their session times out. Below are both info and debug log statements:

    INFO  [02/07/2011 10:08:21 -0500] IP: 127.0.0.1 SessionID: 1b4nvaqnb0qx8 User: testAdmin1 [USER SESSION TIMEOUT]

DEBUG [02/07/2011 10:24:21 -0500] IP: 127.0.0.1 SessionID: d0pq3g4xguv3 User: testAdmin1 [USER SESSION TIMEOUT] with ID [1], with EMAIL [testAdmin1@nowhere.com], with ACCOUNT CREATED DATE [02/07/2011 10:23:18 -0500], with LAST LOGIN DATE [02/07/2011 10:23:18 -0500]

Auditing Login Attempts From Custom Security Modules

Audit logging of custom security modules can be achieved by adding logging capabilities via security authentication event listeners in the /owf-security/MetricSecurityContext.xml file, as in the case of the ozone.securitysample.authentication.listener.AuthenticationSuccessListener and ozone.securitysample.authentication.listener.AuthenticationFailureListener beans (both of which implement org.springframework.context.ApplicationListener<org.springframework.security.authentication.event.AbstractAuthenticationEvent>) located in /apache-tomcat-7.0.21/lib/ozone-security-beans/ListenerBeans.xml and shown below:

    <!-- REQUIRED FOR AUDIT LOGGING OF AUTHENTICATION FAILURES -->
        <bean id="authenticationFailureListener"    class="ozone. securitysample.authentication.listener.AuthenticationFailureListener"/>
        
    <!-- REQUIRED FOR AUDIT LOGGING OF AUTHENTICATION SUCCESS -->
        <bean id="authenticationSuccessListener"        class="ozone. securitysample.authentication.listener.AuthenticationSuccessListener"/>

Once an onApplicationEvent event of type InteractiveAuthenticationSuccessEvent is fired in the Spring Security framework, the authenticationSuccessListener bean will be used to log the details of the successful authentication. Moreover, once an onApplicationEvent event of type AbstractAuthenticationFailureEvent is fired in the Spring Security framework, the authenticationFailureListener bean will be used to log the details of the failed authentication.

Server Settings

All references to the CAS and Metrics must match the settings of the current installation. Based on the settings in OzoneConfig.properties, the variables (e.g. ${ozone.host}) are filled in at runtime.

Table: MetricsCasBeans.xml Server Settings

Property Purpose Example
casProcessingFilterEntryPoint. loginUrl Must point to the CAS login page. https://${ozone.host}:${ozone.port}/${ozone.cas.serverLoginLocation} (e.g. https://servername:port/cas/login)
serviceProperties. Service Must point to the Metrics Service web server. https://${ozone.host}:${ozone.port}/${ozone.cas.Metrics.jSpringCasSecurityCheckLocation} (e.g. https://servername:port /Metrics/j_spring_cas_security_check)
ticketValidatorFactory. casServiceUrl Must point to the CAS server. https://${ozone.host}:${ozone.port}/${ozone.cas.serverName} (e.g. https://servername:port/cas)
ticketValidatorFactory. proxyCallbackUrl Must point to the Metrics Service web server. https://${ozone.host}:${ozone.port}/${ozone.cas.Metrics.serverSecureReceptorLocation} (e.g. https://servername:port/prefs/secure/receptor)
OzoneLogoutSuccessHandler/constructor-arg/index=1 Must point to the CAS logout page. https://${ozone.host}:${ozone.port}/${ozone.cas.serverLogoutLocation} (e.g. https://servername:port/cas/logout)

CASSpringOverrideConfig.xml File

CASSpringOverrideConfig.xml, located in the /etc/override directory, is a Spring framework override file and should be deployed to the same server as Metrics.war.

If using CASSpringOverrideConfig.xml from a server without connectivity to the outside Internet, copy the CASSpringOverrideConfig.xml to the \apache-tomcat-7.0.21-6.1.11\lib folder. From there, the file will use classpath references to override the online Springframework URLs that the header points to during start up.

JVM Memory Settings

Adjusting a server’s memory settings can increase performance or resolve PermGen OutOfMemoryError occurrences. To adjust memory settings:

  1. In the Tomcat start script (apache-tomcat-7.0.21\bin\setenv.sh or setenv.bat), set the initial PermGen size to at least 256 MB. This can be accomplished by adding -XX:PermSize=256m to the Java options. If more server memory is available, increasing this PermGen size may increase performance.
  2. Set the maximum PermGen size to at least 384 MB. This can be accomplished by adding -XX:MaxPermSize=384m to the Java options. If you have more memory available on your server increasing this PermGen size may increase performance.
  3. If you have a server JVM, point to it when starting Java to increase performance. To do this, navigate to serverjvm.dll or add the server flag –server to the deployment command line.

Clone this wiki locally