If [Security] is selected from the left menu, the security domain information will be displayed. From the list of the security domains, a domain can be specified as the 'Default Application Domain' that will be used by the applications. Domains also can be added or deleted from this screen.

The 'Connect Retries' setting is used to specify the connection retry count of JEUS Security NetworkService.

[Figure 2.1] Security Manager Main Screen

To directly modify the XML file, use the following tags from JEUS_HOME/domains/<domain name>/config/domain.xml file.

XML configuration methods for a domain are defined in jeus-domain.xsd and jeus-security.xsd in the JEUS_HOME/lib/schemas/jeus directory. The parent tag is <security-manager>, and it has the following child tags for domain configurations. Zero or more child tags can be used.

<security-manager>
   <security-domains>
      <default-application-domain>SYSTEM_DOMAIN</default-application-domain>
      <security-domain>
        <name>SYSTEM_DOMAIN</name>
        ...
      </security-domain>
   <security-domains>
</security-manager>

The following are descriptions of the configuration tags.

This section describes how to configure user accounts and security policies using the default XML file.

It is possible to store the user account and security policy information in the database as well as in the XML file. For more information refer to "2.5.3. Using Database" and "2.6.3. Using Database".

The following are the steps to configure accounts and policies.

If [Security] is selected from the left menu of WebAdmin, Security Manager screen will appear. Select a security domain that needs to be changed. Configure the security domain as described in "2.2. Configuring the Security System Domain" after clicking [Lock & Edit] to change to the edit mode.

[Figure 2.2] Security Domain Configurations

Under the Security Domains list, if a domain name is clicked, the security configuration screen will appear. The security configuration page consists of the following tabs. For more information about each tab, refer to the descriptions in the following table.

[Cache Config]

On the Cache Config screen, you can define the cache policy values that will be applied to the security services in the domain. The cache value applies to the repository service, which is one of the security services.

[Figure 2.3] [Security Service] - [Cache Config]

[Key Store]

On the Keystore Config screen, you can define the keystore file information that will be applied to the security services in the domain.

The certificate information is included in the Keystore file, and the information can be used for user authentication. If child configuration values do not exist and '–Djeus.ssl.*' or '–Djavax.net.ssl.*' is not configured, the default value will be applied.

[Figure 2.4] [Security Manager] - [Key Store]

The following are descriptions of each configuration item.

[Custom Service]

On the Custom Service screen, additional security services can be registered in the properties of the service that implements JEUS Security API, regardless of the service properties provided by the JEUS Security Framework. For more information about the service types provided by JEUS and Custom security service development, refer to "Chapter 5. Developing Customized Security Services".

[Figure 2.5] [Security Manager] - [Custom Service]

The security services that are loaded to each security domain are defined in domain.xml as follows.

The security configurations are defined by an XML schema in jeus-security.xsd, which is under the JEUS_HOME/lib/schemas/jeus directory.

Inside the <security-domains> tag, add <security-domain> child tags related to security settings. One or more <security-domain> tags can be used, and each tag defines a security domain used in JEUS.

The following is an example of the security configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<domain xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   . . .
   <security-manager>
      <default-application-domain>DEFAULT_APPLICATION_DOMAIN</default-application-domain>
      <security-domains>
         <security-domain>
            <name>SYSTEM_DOMAIN</name>
            .....
         </security-domain>
         <security-domain>
            <name>DEFAULT_APPLICATION_DOMAIN</name>
         </security-domain>
      </security-domains>
   </security-manager>
   . . .
</domain>

Descriptions of child tags of <security-domain> are as follows.

If the [Security Service] tab is selected, the security service configuration screen will appear. The security services can be defined for each domain. The authentication and authorization processes operate differently depending on the security services of the relevant security domain.

[Figure 2.6] [Security Service] - [Authentication]

[Authentication]

If the [Authentication] tab is selected in Security Service, security services related to user authentication can be modified.

[Authorization]

If the [Authorization] tab is selected in Security Service, security services that are related to user authorization can be modified.

[Identity Assertion]

On the Identity Assertion screen, the service that retrieves the user name from the certificate can be specified. Select one of the classes that implements jeus.security.spi.IdentityAssertionService.

[Figure 2.12] [Security Service] - [Identity Assertion]

[Credential Mapping]

On the Credential Mapping screen, the Truststore path and password for X509Certificate can be configured.

By default, the jeus.security.impl.credmap.JKSCertificateCredentialMappingService, the default implementation class of jeus.security.spi.CredentialMappingService, is activated.

[Figure 2.13] [Security Service] - [Credential Mapping]

[Credential Verification]

On the Credential Verification screen, the service that checks the user credentials can be selected.

By default, 'Password Verification' is checked that enables the verification of a user password. If 'Jeus Certificate Verification' is checked, the X509Certificate verification is enabled.

Under the Credential Verification list, a class that implements the jeus.security.spi.CredentialVerificationService class can be added by clicking [Add].

[Figure 2.14] [Security Service] - [Credential Verification]

[Audit]

On the Audit screen, the service that collects information about the events that occurred in the JEUS Security Framework can be set.

The file name that will store the logs and its path can be specified in the 'Filename'and 'Filepath' fields. The log level can be specified in the 'Audit Level' field. The default implementation class jeus.security.impl.auditlog.BasicAuditLogFileService is used.

Under the Custom Audit Service list, the class that implements the jeus.security.spi.EventHandlingService class can be added by clicking [Add].

[Figure 2.15] [Security Service] - [Audit]

[Subject Validation]

On the Subject Validation screen, the validation checks for users (subjects) can be specified. If 'Default Subject Validation Service' is selected, jeus.security.impl.expiration.SubjectExpirationValidationService will be activated, and a user validation check will be performed based on whether the ExpiryTime is set or not.

Under the Custom Subject Validation Service list, the class that implements the jeus.security.spi.SubjectValidationService class can be added by clicking [Add].

[Figure 2.16] [Security Service] - [Subject Validation]

The security services that will be loaded for each security domain are set in the domain.xml file as follows.

The following is an example of a security configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<domain xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   . . .
   <security-manager>
      <default-application-domain>
        DEFAULT_APPLICATION_DOMAIN
      </default-application-domain>
      <security-domains>
         <security-domain>
            <name>SYSTEM_DOMAIN</name>
            <authentication>
               <repository-service>
                  <xml-file-repository>
                     <config-file>
                        <filename>accounts.xml</filename>
                        <filepath>
                         ${JEUS_HOME}/domains/domain1/config/security/
                        </filepath>
                     </config-file>
                  </xml-file-repository>
               </repository-service>
            </authentication>
         </security-domain>
         <security-domain>
            <name>DEFAULT_APPLICATION_DOMAIN</name>
         </security-domain>
      </security-domains>
   </security-manager>
   . . .
</domain>

The following are the detailed descriptions of the child tags of <security-domain> tag.

Custom Security Services

The following describes how to configure custom security services.

For more information about the security service types that are provided by JEUS, and custom security service development refer to "Chapter 5. Developing Customized Security Services".

The following describes how to configure user information using WebAdmin.

The XML schema of accounts.xml is accounts.xsd, which is in the JEUS_HOME/lib/schemas/jeus directory.

In the accounts.xml file, there are 0 or more <user> and <group> tags inside the <accounts> tag. They represents a user and a group, respectively.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<accounts xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   <users>
      <user>
         <name>user1</name>
         <password>{AES}mnG6ItxFO/WQlE2YzIZ7sA==</password>
         <group>group1</group>
      </user>
      <user>
         <name>user2</name>
         <password>{DES}7dJ0KDTGQNpSnQAPYBNnmA==</password>
      </user>
      <user>
         <name>user3</name>
         <password>{DES}7dJ0KDTGQNpSnQAPYBNnmA==</password>
         <group>nested_group</group>
      </user>
      <user>
         <name>user4</name>
         <password>{SEED}dl2EePMAcnxPYbIyknuZkA==</password>
         <group>nested_group</group>
      </user>
   </users>
   <groups>
      <group>
         <description>Group1</description>
         <name>group1</name>
         <subgroup>nested_group</subgroup>
      </group>
      <group>
         <description>For NestedGroup</description>
         <name>nested_group</name>
      </group>
   </groups>
</accounts>

Detailed descriptions of the configuration tags are as follows:

This section explains how to configure authentication using the database table defined by JEUS.

The following example illustrates how to use the data source defined in JEUS.

<?xml version="1.0" encoding="UTF-8"?>
<domain xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   . . .
   <security-manager>
      <seuciry-domains>
         <security-domain>
            <name>MY_DOMAIN</name>
            <authentication>
               <repository-service>
                  <database-repository>
                     <datasource-id>auth</datasource-id>
                  </database-repository>
               </repository-service>
            </authentication>
            . . .
         </security-domain>
      </security-domains>
   </security-manager>
   . . .
</domain>

In the previous example, the data source ID must be configured using the <datasource-id> element. The data source ID is registered in the domain.xml file that will be used for authentication. Authentication can also be performed by directly communicating with the database through the DriverManager without using the JDBC that is provided by JEUS. To do this, change the <datasource-id> element block of the previous example as follows.

The following example illustrates how to configure the database repository when not using the JEUS JDBC.

   <security-manager>
      ...
      <repository-service>
         <dbdriver-config>
            <vendor>oracle</vendor>
            <driver>oracle.jdbc.OracleDriver</driver>
            <url>jdbc:oracle:thin:@127.0.0.1:1521:ORA9I</url>
            <username>scott</username>
            <password>{base64}dGlnZXI=</password>
         </dbdriver-config>
      </repository-service>
      ...
   </security-manager>

The tables that are used in the database are organized as follows:

[Figure 2.21] Database Table Structure that Stores the User Information for Subjects

If the tables do not exist in the database, create a DB table by using the JEUS_HOME/templates/security/dbrealm.sql.template file. This will initially create the user with the name 'jeus' and the password 'jeus'.

This section describes the encryption algorithms and how to manage the SecretKey file for the password security configurations.

Encryption Algorithm

When configuring a user, the user password must be set. The password can be stored in plain-text, but for security reasons, it is better to encrypt the password using an encryption algorithm.

Password can be encrypted by users using the WebAdmin or the set-password command in jeusadmin. It can be encrypted directly by using the tool, JEUS_HOME/bin/encryption.

To manually encrypt the password, use the following format.

{Algorithm}Encrypted string 

The key value of the symmetric-key algorithm is stored in JEUS_HOME/domains/<domain name>/config/security/security.key.

The following are descriptions of algorithms that can be used for password encryption.

SecretKey File Management Using The Master Password

When encrypting a password using the encryption tool (located in JEUS_HOME/bin), the SecretKey information that is applied to an encryption file can be stored in security.key file grouped by algorithm types. A master password can be used to encrypt the security.key file.

The security.key file is placed in the following path. When configuring a domain environment, the security.key file must be moved to another node.

JEUS_HOME/domains/<domain name>/config/security/security.key

When you encrypt the DB password, which needs to be registered in JEUS, a client needs a key to decrypt it. At this point, you can configure the secret key file path by using the system property.

When the master password is specified in the secret key file, this master password can also be configured using the system property. The property name for the key path is jeus.security.keypath. To specify the master password, use the jeus.security.master property. These properties can also be used when starting JEUS. However, for security reasons, it is recommended to use the prompt (standard input) to enter the master password.

The user information must be entered when starting a server using the JEUS script or by accessing the server using jeusadmin. In such case, the user information can be cached so that the user information does not need to be entered every time.

Only the login information, that was authenticated, is stored in the cache.

When executing the connect command in jeusadmin, if the option -cachelogin is added with the user information, the login information will be stored in the file. When JEUS script is used, the login information is stored using the key, <domain name>:<server name>.

When JEUS script is executed, if login information with the same domain and server name exists, the user information will be automatically filled without having to re-enter the user information. If the user manually enters the information, even if there is already cached login information, the cached information will be ignored. Jeusadmin stores the login information using the <host>:<port> key of the sever, which you are trying to access.

The following example shows the stored login information.

#Warning: We don't recommend to use this on Production Environment.
localhost:9736 amV1czpqZXVz
domain1:server1 amV1czpqZXVz

The stored login information can be deleted using the remove-login-cache command, an off-line jeusadmin command.

In the [Accounts & Policies Management] tab, if [policies] is selected, security policies can be configured. In the Role Permissions section, principals can be mapped to roles. Multiple principals can be mapped to a role. The mapped principals inherit the role's permissions.

If [Add] is clicked, a principal-to-role mapping can be added.

[Figure 2.22] Policy Configuration Main Screen

Role Permission Registration

Under the Role Permissions list, Role Permission can be registered by clicking [Add].

After entering a name in 'Role', select the principal that will be granted the role permission. To deny access to the role, check 'Excluded' and to allow access to the role check 'Unchecked'. After completing the configurations, click [OK].

[Figure 2.23] Policy Configurations - Role Permission Registration

Resource Permissions Registration

The following shows how to register Resource Permissions.

The XML schema of the policies.xml file is policies.xsd, and it is in the JEUS_HOME/lib/schemas/jeus. policies.xml directory.

It consists of multiple <policy> tags and each tag represents individual policies (authorization data). Each <policy> tag consists of the following child tags.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<policies xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   <policy>
      <role-permissions>
         <role-permission>
            <principal>user1</principal>
            <role>administrator</role>
         </role-permission>
         <role-permission>
            <principal>user1</principal>
            <role>teller</role>
            <actions>9:00-17:00</actions>
            <classname>
               jeus.security.resource.TimeConstrainedRolePermission
            </classname>
         </role-permission>
      </role-permissions>
      <resource-permissions>
         <context-id>default</context-id>
         <resource-permission>
            <role>teller</role>
            <resource>bankdb</resource>
            <actions>select, update</actions>
         </resource-permission>
         <resource-permission>
            <role>administrator</role>
            <resource>jndi</resource>
            <actions>modify, delete</actions>
         </resource-permission>
         <resource-permission>
            <resource>jndi</resource>
            <actions>lookup</actions>
            <unchecked/>
         </resource-permission>
         <resource-permission>
            <role>administrator</role>
            <resource>jeus.*</resource>
            <actions>*</actions>
         </resource-permission>
      </resource-permissions>
   </policy>
</policies>
             

The following are descriptions of the configuration tags.

Normally the policies.xml file is exclusively used to configure permissions for JEUS Server Resource (like JNDI, JMS, Security Server, etc.), and NOT for J2EE application modules. To configure J2EE application module permissions, you should use various DD (deployment descriptor) files. For more information, refer to "Chapter 3. Configuring Security for Applications and Modules".

Custom Permission Implementation and Configurations

Whenever a permission (role permissions or resource permissions) is added to the policies.xml file, the Java class name of the permission must be specified. This is the name of a Java class that extends the java.security.Permission abstract class. Create a customized implementation subclass that extends the java.security.Permission Permission class, and specify the implementation class name in the <classname> tag of policies.xml.

This sub-section describes how to develop a new customized role permission that meets the following requirements. The new role permission should imply another role permission only if the following two conditions are met.

The following shows an example of a banking application where a role permission grants the principal user2 the teller role only during the 9 to 5 business hours.

To accomplish this, you must complete the following 2 steps.

In order to configure the policy using a database, domain service must be configured in the domain.xml file as in the following. In order to directly use the driver manager, add the <dbdriver-config> tag, instead of the <datasource-id> tag, as for the authentication setting. However, it is recommended to use JEUS JDBC data source for performance benefits.

<?xml version="1.0" encoding="UTF-8"?>
<domain xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   ...
   <security-manager>
      <security-domains>
         <security-domain>
            <name>MY_DOMAIN</name>
            <authorization>
               <repository-service>
                  <database-repository>
                     <datasource-id>auth</datasource-id>
                  </database-repository>
               </repository-service>
            </authorization>
            . . .
         </security-domain>
      </security-domains>
   </security-manager>   
   . . .
</domain>                 

A URL, username, and password to access the JDBC driver, which accesses the database, are required to use the AuthenticationRepositoryService that uses a database.

In the following example, a password that is encoded in Base 64 must be entered to access the Oracle DB. When entering a password applied with a certain encryption algorithm or encoding method, use the same method as for user password of accounts.xml.

The database tables have the following structure.

[Figure 2.27] Database Table Structure to Save Policies

If the tables do not exist in the database, create a DB table by using the JEUS_HOME/templates/security/dbrealm.sql.template file. The basic policy is granted the administrator role in “SYSTEM_DOMAIN”, thereby possessing Resource authority for “jeus.*”. The default principal included in the administrator role is jeus as mentioned in "2.5.3. Using Database".

The use of a JavaSE SecurityManager in JEUS can increase the platform reliability, but might undermine the performance. Usually, all core JEUS codes as well as the J2EE application and module code deployed to JEUS may be treated as completely “trusted” code, and thereby avoid the overhead incurred by the SecurityManager. This mode of operation, with no SecurityManager, is the default mode in JEUS.

However, there may be cases where the increased reliability and code-level security provided by a JavaSE SecurityManager is considered more important than the performance enhancement.

For example, the administrator may have to deploy some untested or otherwise suspicious JavaEE applications or modules to JEUS. In such case, it may be desirable to protect your machines and environment by boosting the code level protection at the expense of performance by using JavaSE SecurityManager.

In order to use a JavaSE SecurityManager with JEUS, define jvm-option in the domain.xml file for a particular server as follows.

-Djava.security.manager 
-Djava.security.policy=${JEUS_HOME}/domains/domain1/config/security/policy (UNIX)

The policy file is JEUS_HOME/domains/<domain name>/config/security/policy and the its content is as follows:

grant codeBase "file:${jeus.home}/lib/system/*" {
   permission java.security.AllPermission;
};

grant {
   permission java.net.SocketPermission "127.0.0.1:1024-", 
   "connect, accept, connect, listen, resolve";
   permission java.security.SecurityPermission "runTrustedLogin", "read";
   permission java.security.SecurityPermission "loginCodeSubject", "read";
   permission java.security.SecurityPermission "putProviderProperty.*";
   permission java.security.SecurityPermission "insertProvider.*";
   permission javax.management.MBeanPermission "*", "*";
};                    

The JavaSE SecurityManager is completely independent from JEUS security system. The JEUS security system does not provide protection at the code level (permission configuration that can execute code), but instead it provides security at the user level (the identity of the process that is running and what it is allowed to do).

The only overlap between the two is that, under special conditions, the JEUS security system can check with the JavaSE SecurityManager for some code level permission(see above) in order to protect JEUS from malicious or bug-filled Servlet and EJB code.

For details of configuring the JACC 1.4, refer to "Chapter 6. Using JACC Provider".

If IdentityAssertionService is supported, it is read from the cert-user-map.xml file that contains the mapping information between a certificate and user. The file is in the following location.

JEUS_HOME/domains/<domain name>/config/security/<security domain name>/

The <domain name> tag is for the domain name and the <security domain name> tag is for the security domain where the user belongs to. The XML schema of the cert-user-map.xml file is cert-user-map.xsd, which is in the JEUS_HOME/lib/schemas/jeus directory.

In the file, the parent tag, <cert-user>, can have <user>, <cert>, and multiple <cert-user> child tags. Each contains the property information for user to certificate mapping.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cert-user-map xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   <cert-user>
      <username>user1</username>
      <cert>
         <subjectDN>user1DN</subjectDN>
      </cert>               
   </cert-user>
</cert-user-map>      

Each <cert-user> tag has the following child tags.

The JEUS security system provides an API, through the UserCertMappingService, that can be used to obtain certificate information of the authenticated user's identity. If UserCertMappingService class is supported, the user data is read from the user-cert-map.xml file, where additional mapping information exists for the certificate grouped by users. The file is in the following path.

JEUS_HOME/domains/<domain name>/config/security/<security domain name>/ 

The <domain name> tag is for the domain name and the <security domain name> tag is for the security domain that the user belongs to. The XML schema of user-cert-map.xml is user-cert-map.xsd, and its path is JEUS_HOME/lib/schmas/jeus.

In the file, the parent tag, <user-cert-map>, can have 0 or more <user-cert> tags. Each contains the property information to obtain a user certificate from the Keystore file.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user-cert-map xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   <user-cert>
      <username>user1</username>
      <alias>alias1</alias>
      <keypassword>changeit</keypassword>
      <secretkey>
         <keyname>testkeypass</keyname>
         <keyalgorithm>AES</keyalgorithm>
         <keyvalue>bjhTUjJvSXRTOGlkVEdlNHJnM2N3VnljSDZXV0JkYz0=</keyvalue>
      </secretkey>
   </user-cert>
</user-cert-map>

Each <user-cert> tag has the following child tags.