4. Using SAF Security in Tomcat

This document describes how to configure t:Z QuickStart for Tomcat to use SAF (RACF) for J2EE user Authentication and Authorization.

	Note
	Configuring Tomcat to use SAF for user authentication and authorization is different than running Tomcat under a Java security manager.

Support for using SAF to authorize users, passwords, and roles is provided by the Dovetailed Technologies Tomcat SAF Realm, which is included as Java classes in package com.dovetail.zos.tomcat in lib/zos-tomcat.jar.

The Tomcat SAF Realm uses SDK APIs in the com.ibm.os390.security package to validate userid/passwords and assign roles by checking associated SAF entities. These APIs use system services that require that the Tomcat job have the following system authorities:

The userid executing Tomcat must have read access to the BPX.SERVER SAF entity (or be a superuser).
The Tomcat address space must be "program controlled", which means that all of the load module libraries and DLLs that are loaded must be marked as program controlled. This is not the same as APF authorization, but is a system privilege required to check passwords and SAF entity access.

The following steps are required to configure t:Z QuickStart for Tomcat to use SAF:

Set the program controlled extended attribute on any DLLs that you added to the SDK runtime environment.
These would include any installation JNI libraries that you added to your LIBPATH in TCENV. If you configured TCENV to use an alphaWorks version of JZOS, rather than the SDK-supplied version, then the alphaWorks JZOS native libraries must also be program controlled. If neither of these apply, then you may ignore this step.
```
          extattr +p libjzos*.so
          
```
Note
Your userid must be authorized for READ access to the BPX.FILEATTR.PROGCTL SAF entity to set this attribute.

All libraries with modules loaded by the Tomcat job must be program controlled. These include the JZOS Batch Launcher load module (JVMLDMxx) as well as the c/c++ runtime libraries used by Java.

RALTER PROGRAM * ADDMEM ('<JZOS_PDSE_LOADLIB>'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('SYS1.LINKLIB'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('SYS1.CSSLIB'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('CEE.SCEERUN'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('CEE.SCEERUN2'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('CBC.SCLBDLL'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('SYS1.SEZALINK'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('SYS1.SEZALNKE'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('DSN910.SDSNEXIT'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('DSN910.SDSNLOAD'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM ('DSN910.SDSNLOD2'//NOPADCHK) UACC(READ)
SETROPTS WHEN(PROGRAM) REFRESH

	Note
	Many of these libraries may already be program controlled. The TSO command `RLIST PROGRAM * ALL` can be used to check the status of all libraries

Edit the SAMPJCL(SERVXML) member, which contains the Tomcat configuration XML. Near the bottom, locate and edit the Realm tag so that default UserDatabase Realm is commented out and the SafRoleDatabase is uncommented.

The result should be as follows:

<!-- This Realm uses the UserDatabase configured in the global JNDI
     resources under the key "UserDatabase".  Any edits
     that are performed against this UserDatabase are immediately
     available for use by the Realm.  -->
<!--
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
       resourceName="UserDatabase"/>
-->        
       
<!-- For SAF(RACF) Authentication, replace the Realm above with: -->
<Realm className="com.dovetail.zos.tomcat.SafRealm"
       resourceName="SafRoleDatabase"/>

Edit SAMPJCL(SAFROLES) and define the Tomcat (J2EE) roles and the SAF entities that will be used to grant them.

<role rolename="manager" 
      safclass="EJBROLE" safentity="TCAT.DEV.MANAGER" saflevel="READ"/>

<role rolename="myrole" 
      safclass="EJBROLE" safentity="TCAT.DEV.MYROLE" saflevel="READ"/>

Use the following TSO commands to define a new SAF entity and grant a user access to it:

RDEFINE EJBROLE TCAT.DEV.MANAGER UACC(NONE)
PERMIT TCAT.DEV.MANAGER CLASS(EJBROLE) ID(<user_id>) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH

Restart Tomcat and attempt to access a protected resource such as the Tomcat manager page: http://host:port/manager/html

Supply your SAF userid and password when prompted to logon. If everything is setup and configured correctly, then the Tomcat manager page will display. If not, check the job's STDOUT and STDERR files for more information.

	Note
	If you receive an error message in the log indicating that the address space is not properly program controlled, check the system log for an IBM message that indicates which load module library or DLL is causing the problem.

Prev		Next
3. Basic Configuration and Operation	Contents	5. For More Information...

Prev		Next
3. Basic Configuration and Operation	Home	5. For More Information...

	Note
	Your userid must be authorized for READ access to the `BPX.FILEATTR.PROGCTL` SAF entity to set this attribute.

T:Z QuickStart for Tomcat - User's Guide V 1.0 (Draft)

4. Using SAF Security in Tomcat