Single Sign-On for Java 3.3.2 - Administration Guide

Setting up logging

Single Sign-on for Java includes a configurable logging package. This mechanism allows you to specify any logging mechanism that meets Single Sign-on for Java's requirements.

By default, Single Sign-on for Java uses Apache Commons Logging and relies on its autoconfiguration behavior. Apache Commons Logging delegates to some other logging package, and again Single Sign-on for Java relies on the autoconfiguration behavior of that logging package. The Single Sign-on for Java distribution provides an Apache Log4J configuration which should meet most needs.

To set up the logging mechanism, you must setup a log4j.properties or log4j.xml configuration file to be included in the WEB-INF/classes directory of your web application.

This log4j configuration should set the com.dstc and com.wedgetail loggers to use the log levels and appenders you desire.

# Set Single Sign-on for Java Kerberos logger priority to DEBUG and its only appender to # FILE.

log4j.logger.com.dstc=WARN, FILE

# Set Single Sign-on for Java SSO logger priority to DEBUG and its appenders to CONSOLE

# and FILE.

log4j.logger.com.wedgetail=DEBUG, FILE, CONSOLE

You can also configure the com.wedgetail.idm.sso.util.DefaultAuditor# login and com.wedgetail.idm.sso.util.DefaultAuditor#access loggers to turn on Single Sign-on for Java auditing for logins and page accesses respectively:

# Turn on Single Sign-on for Java login auditing and log messages to FILE.

log4j.logger.com.wedgetail.idm.sso.util.DefaultAuditor#login=INFO, FILE

# Turn on Single Sign-on for Java access auditing and log messages to FILE.

log4j.logger.com.wedgetail.idm.sso.util.DefaultAuditor#access=

INFO, FILE

As an alternative, you can set idm.logger.name (and optionally also idm.logger.props). In this case Single Sign-on for Java invokes and configures Log4J directly.

The parameter idm.logger.name is the Log4J logger name to be used. This can be any text as long as it is unique to a log file (that is, no other log file for any other web application can share the same name).

The name must also be specified in the Log4J properties file.

The parameter idm.logger.props is used to configure logging with a specified Log4J properties file. The value of this parameter is interpreted as follows:

• null - no logging output. This is equivalent to not specifying the idm.logger parameter at all.
• “BASIC” - This value indicates that basic error logging is required. All error messages will be sent to the standard output of the container. For example, if a servlet is executed under an Apache Tomcat Web server, error messages would be written to the logs/catalina.out file.
• Any other value (such as error-log.properties above) indicates the location of a Log4J properties file. This properties file is located in the WEB-INF directory with the deployment descriptor, and is used to configure the logger that Single Sign-on for Java uses for reporting errors and debug messages.

Controlling access to resources

This section shows how to use Active Directory to control access to resources in your Web application. It describes how to set up authorization using Active Directory groups, and how to write access policy files for Single Sign-on for Java.

• Authorization using Active Directory groups
• Writing access policy files
• Policy XML descriptor elements

Authorization using Active Directory groups

Single Sign-on for Java supports authorization of users using Active Directory groups. This allows a deployer to specify which groups are allowed to access a given application at deployment time, and then manage membership of this group using Active Directory without redeploying the application.

This section outlines the authorization model for Servlets and JSPs in Java EE, and discusses how this maps to the authorization configuration used by Single Sign-on for Java.

Java EE authorization model for servlets and JSPs

Java EE provides an authorization model for servlets and JSPs that are role-based.

A role is a collection of users or groups of users defined by the application server container.

Membership of one or more roles is used by the container to determine whether a particular user should be allowed to access a Web resource.

Java EE provides two mechanisms for enforcing role-based access control:

1. Declarative security. The application deployer defines the roles and associates them with the resources that they wish to protect at deployment time.

   This is done by associating a security constraint with the resources you wish to protect in the application's deployment descriptor.

   For example, supposing you want to restrict access to particular resources in an order/inventory system to members of the role “StockManager”.

   You could do this with the following XML fragment from the deployment descriptor:

   <security-constraint>

   <web-resource-collection>

   <web-resource-name>InventoryReports</web-resource-name>

   <description>

   Security constraint for restricting access to

   Inventory reports.

   </description>

   <url-pattern>/inventory/reports/*</url-pattern>

   <http-method>POST</http-method>

   <http-method>GET</http-method>

   </web-resource-collection>

   <auth-constraint>

   <description>

   Access only available to StockManagers

   </description>

   <role-name>StockManager</role-name>

   </auth-constraint>

   <login-config>

   <auth-method>BASIC</auth-method>

   </login-config>

   </security-constraint>

   The <security-constraint> tag has three main components:

   • The <web-resource-collection> tag defines those resources you want to protect. It can include one or more URL patterns to match (specified by the <url-pattern> tag), and the HTTP methods to which the security constraint should apply (specified by the <http-method> tag, or all methods if the tag is omitted).

     Note that the URL pattern specified should exclude the servlet-context.

   • The <auth-constraint> tag defines which roles are allowed access to the resources matched by the <web-resource-collection> definition. These roles are defined by application server-specific mechanisms outside of the standard deployment descriptor. For example, in BEA WebLogic these roles are defined in the weblogic.xml file using a <security-role-assignment> tag.
   • The <login-config> tag defines how users are authenticated by the container to perform authorization. The example uses standard basic authentication support which uses a user name and password.

     When a user attempts to access the resources in the security constraint, the container first checks the authentication method in the <auth-method> tag to determine how the user is to be authenticated. Once they have authenticated successfully, the container examines the <auth-constraint> to see which roles are required for the user to be able to access the resource.

     If the user is a member of the role, access is granted, otherwise an Access Denied error is displayed.

2. Programmatic security. Because the declarative security model only allows for very simple access control based on role membership, Java EE supports a programmatic enforcement mechanism that allows the application developer to implement more sophisticated rules. The basic element used is the isUserInRole method of the HttpServletRequest interface.

   This method allows the programmer to determine a user's role membership at run time and to take actions based on it.

   For example, supposing you wanted a Servlet to display different content depending on whether they were a member of the “Supplier” role or not, the following logic could be used:

   HttpServletRequest req = ...

   // Check if user is a "Supplier"

   if (req.isUserInRole("Supplier")) {

   // Display one set of content

   ...

   } else {

   // Display some other content

   }

   Programmatic security provides much more flexibility in authorization decisions. Constraints can be based on information other than simple role membership (for example time of day, or the source address from which the request originated).

   The main disadvantage of programmatic security is that it requires these decisions to be hard-coded at development time. Deployers also have a slightly more difficult task, as you need to know which roles the programmer is relying on and ensure that these are configured correctly at deployment time.

   When deploying applications with programmatic security, you may still specify a security constraint in the deployment descriptor. However, you may also have to perform a role mapping to ensure that roles defined by the application server map to role names that the programmer uses. This is often used where one or more roles with different members are required, but programmers have used the same names.

   This role mapping is done using the <security-role-ref> tag of the servlet descriptor that is enforcing the programmatic security and linking the role to another role defined by the <security-role> tag.

   For example:

   <servlet>

   <servlet-name>DisplayInventory</servlet-name>

   <servlet-class>DisplayInventoryServlet</servlet-class>

   <security-role-ref>

   <role-name>Supplier</role-name>

   <role-link>InventoryApplicationSupplier</role-link>

   </security-role_ref>

   </servlet>

   <security-role>

   <description>

   Suppliers who have access to the Inventory Application

   </description>

   <role-name>InventoryApplicationSupplier</role-name>

   </security-role>

   This defines a mapping between the “Supplier” role name used by the call to isUserInRole and the role InventoryApplicationSupplier. The InventoryApplicationSupplier role still needs to be defined using the application server-specific mechanisms described previously.