Chapter 2. Configuring the Security System
Prev   Next

Chapter 2. Configuring the Security System

Table of Contents

2.1. Overview
2.2. Configuring the Security System Domain
2.2.1. Using WebAdmin
2.2.2. Configuring XML
2.2.3. Configuring User Accounts and Security Policies
2.3. Configuring Security Domain Components
2.3.1. Using WebAdmin
2.3.2. Editing XML
2.4. Configuring Security Services
2.4.1. Using WebAdmin
2.4.2. Configuring XML
2.5. Configuring the Security System User Information
2.5.1. Using WebAdmin
2.5.2. Configuring XML
2.5.3. Using Database
2.5.4. Configuring Password Security
2.5.5. Caching Login Information
2.6. Configuring Security System Policies
2.6.1. Using WebAdmin
2.6.2. Editing XML
2.6.3. Using Database
2.7. Configuring Additional Settings
2.7.1. Configuring Java SE SecurityManager
2.7.2. Configuring JACC Provider
2.7.3. Configuring information to Grant Identity
2.7.4. Configuring Identity Certificate Information

This chapter describes how to install and configure the security system in JEUS. For configuring other services in a domain other than what is mentioned here, refer to References.

2.1. Overview

This section will briefly summarize some basic aspects related to security system configurations.

The JEUS security system starts when the server is executed by the Security Installer. To protect JEUS, the Security Installer creates a security domain based on the information in the domain.xml file before starting the security service. The user accounts and security policies defined in the account.xml and policies.xml files are applied in the default security system.

The following two items can be configured in a security domain.

  • Definitions of security domain and security services.

  • Accounts and policies for the domain.

Following steps are performed to configure the default security system.

  1. Configure security domains.

  2. Configure security Services for each security Domain.

  3. Configure Subjects (authentication data) for each Domain.

  4. Configure Policies (authorization data) for each Domain.

  5. Configure additional items.

  6. Configure a JavaSE SecurityManager (optional).

  7. Configure a JACC provider (optional).

Directory Structure for the Default Security System

The following figure is the directory structure of the default security system. Each directory lists the configuration files used by the default security system.

JEUS_HOME/domains/<domain name>
|--config
     |--security
           |--security.key
           |--policy
           |--SYSTEM_DOMAIN
                   |--accounts.xml
                   |--policies.xml

The following describes each directory.

security
ClassificationDescription
security.keyThe file that stores the key for synchronous encryption algorithm. The file will be created when the encryption is executed for the first time.
policyThe Java Permission configuration file. It is used in Java SE Security Manager, separate from the JEUS security system.
SYSTEM_DOMAIN

A domain used by the JEUS server to check for user authentication and authorization. This domain contains Permissions to start and terminate JEUS, and JEUS system administrator accounts.

Note

To apply different security policies to applications, a separate security domain directory must be created and configured.

2.2. Configuring the Security System Domain

Domains can be configured using WebAdmin or by manually modifying the domain.xml file. Other configurations, besides user account and security policy configurations, cannot be changed dynamically. Therefore, when a security domain is added or security service configurations are changed, the server must be restarted to apply the changes.

Caution

All configurations related to security apply to all servers in the JEUS domain. All servers must be restarted in order to apply the security configurations, except for user account and security policy configurations.

Domain Admin Server (DAS) must be running to configure the security domain configurations, and all servers including DAS must be restarted to apply these configurations. This section describes how to define the security domain using WebAdmin or by modifying the XML file.

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

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.

[Example 2.1] <<JEUS_HOME/domains/<domain name>/config/domain.xml>>

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

TagDescription
<connect-retries>

Sets the connection retry count in JEUS Security NetworkService

(Default value: 10)

<default-application-domain>

Sets the default domain name that will be used in J2EE applications.

(Default value: SYSTEM_DOMAIN)

<security-domains>Sets the security domains that will be registered with JEUS. For more examples of <security-domains> refer to "2.3. Configuring Security Domain Components".

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.

  1. To configure a new security domain, a new directory must be created under the JEUS_HOME/domains/<domain name>/config/security directory. The name of the new directory should match the name of the domain that you wish to create. By convention, domain names use all capital letters and are appended with the string "_DOMAIN". For example, the name "DEFAULT_APPLICATION_DOMAIN" can be used as a domain name.

    To create a domain with the name DEFAULT_APPLICATION_DOMAIN, execute the following command.

    $ mkdir ${JEUS_HOME}/domains/domain1/config/security/DEFAULT_APPLICATION_DOMAIN

    Note

    domain1 should be replaced with the actual JEUS domain name.

  2. After creating the new domain directory, you must create a number of configuration files in it.

    The best way is to simply copy existing configuration files from existing domain directory and modify these files according to your need (enter the following commands in a single line). The following sections will explain how to modify these copied configuration files.

    $ cp ${JEUS_HOME}/domains/domain1/config/security/SYSTEM_DOMAIN/*.*
     ${JEUS_HOME}/domains/domain1/config/security/DEFAULT_APPLICATION_DOMAIN

    By default, SYSTEM_DOMAIN already exists under the JEUS_HOME/domains/<domain name>/security directory. SYSTEM_DOMAIN is the domain used by the JEUS server to perform authentication and authorization. Among other things, this domain contains the JEUS system "administrator" account and permissions for starting and terminating the JEUS server.

  3. The newly created domain will be applied when JEUS is restarted.

    The security domain, SYSTEM_DOMAIN, will always be included regardless of the configurations in the domain.xml file. In general, you can create a directory with the same name as the domain under the JEUS_HOME/domains/<domain name>/config/security directory. In this directory, you can define the security policy information (policies.xsd) and account information (accounts.xsd) of the Repository, which needs to be defined for each domain. You can also use the domain.xml file to register the Security Service for each domain.

Caution

If a security domain was added using WebAdmin in the default security system without following the aforementioned steps, the account information and security policy information in SYSTEM_DOMAIN will be shared. In order to separate the account and security policy information by security domains, you must follow the aforementioned steps.

2.3. Configuring Security Domain Components

This section describes how to configure security domain components, excluding security services.

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

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.

TabDescription
[Cache Config]Defines the cache policy value that will be applied to the security service in the domain.
[Key Store]Defines the Keystore file information that will be applied to the security services in the domain.
[Security Service]The security services configuration screen.
[Custom Service]Regardless of the service properties provided by JEUS Security Framework, additional security services can be registered through the properties of the service that implements JEUS Security API. For more information, refer to "2.4. Configuring Security Services".
[Accounts & Policies Management]Configures the user accounts and security policies. For more information, refer to "2.5. Configuring the Security System User Information" and "2.6. Configuring Security System Policies".

[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]

[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]

[Security Manager] - [Key Store]

The following are descriptions of each configuration item.

ItemDescription
Keystore Path

The path to the keystore file that will be applied to the current domain.

(${JEUS_HOME}/domains/<domain name>/config/security/keystore)

Keystore AliasAn alias for the keystore. When there are multiple keyEntry certificates in the keystore file, the keystore entries are accessed by their unique aliases.
Keystore PasswordThe password for the keystore file for the current domain (Default value: changeit).
Keystore Keypassword

The password for the keystore file for the current domain.

(Default value: Same as the <keystore-password> value)

Truststore Path

The path to the truststore file the current domain.

(${JEUS_HOME}/domains/<domain name>/config/security/truststore)

Truststore PasswordPassword for the truststore file for the current domain (Default value: changeit).

[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]

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

[Example 2.2] Security System Service Configurations: <<domain.xml>>

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

Note

Inside the <security-domain> tag, if you only configure the <name> tag and do not configure other Service Provider information, the default security services will be used for the corresponding domain.

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

2.4. Configuring Security Services

JEUS security system supports plugin type of authentication and authorization services. This section describes how to configure security domain components, including security services, by using WebAdmin and by modifying the XML file.

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]

[Security Service] - [Authentication]

MenuDescription
[Authentication]Modifies the security services related to user authentication.
[Authorization]Modifies the security services related to user authorization.
[Identity Assertion]Specifies the service that retrieves user name from the certificate.
[Credential Mapping]Specifies the Path to the Truststore file and password for X509Certificate.
[Credential Verification]Specifies the service that verifies user credential.
[Audit]Specifies the service that collects information about events that occurred in JEUS Security Framework.
[Subject Validation]Performs user(subject) validation.

[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]

[Security Service] - [Identity Assertion]


ItemDescription
Default Identity Assertion Service

The configuration can be modified for DefaultIdentityAssertionService, a default service provided by JEUS. This service operates based on the X509Certificate.

The 'Filename' and 'Filepath' fields specifies the XML file that contains the mapping information between a certificate and user name.

Custom Identity Assertion ServiceDefines the Custom Identity Assertion service. Specifies a class that directly implements SPI.
Kerberos Identity Assertion

Specifies Assertion that uses the Keberos protocol.

If this configuration is set, jeus.security.impl.login.KerberosSharedStateLoginModule, among the LoginModule implementation classes that are provided by JEUS, is activated.

[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]

[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]

[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]

[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]

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

[Example 2.3] Security System Service Configurations: <<domain.xml>>

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

2.5. Configuring the Security System User Information

In the default security configurations, user data is read from the accounts.xml file.

The following is the file path.

JEUS_HOME/domains/<domain name>/config/security/<security domain name>/accounts.xml

Here, <domain name> is the name of the domain and <security domain name> is the name of the security domain for which the users are managed.

The following describes how to configure user information using WebAdmin.

  1. User information can be configured in [Accounts & Policies Management] > [accounts] screen. The user information is modified dynamically. Users can be added or deleted using the [Add], [Delete] buttons.

    [Figure 2.17] Accounts Configuration Screen

    Accounts Configuration Screen


    Under the Groups list, groups can be added or deleted. In the Users list, a user can be added to an existing group. Groups can be added or deleted by clicking the [Add], [Delete] buttons.

  2. In the User list, if [Add] is clicked, the User screen will appear. On this screen, you can only modify the accounts.xml file, which is the default security system provided by JEUS.

    [Figure 2.18] Accounts - User Registration

    Accounts - User Registration


  3. If [Input] to the right of 'Password' is clicked, the user password can be set as follows. Select an encryption algorithm to encrypt the password. Enter the password and then click [OK].

    [Figure 2.19] Accounts - Password Configurations

    Accounts - Password Configurations


    When the password configuration is complete, the user password will be encrypted by the specified algorithm, and the result can be checked on the following screen. For more information, refer to "2.5.4. Configuring Password Security".

    [Figure 2.20] Accounts - Password Algorithm

    Accounts - Password Algorithm

  4. Specify the group where the user will belong to in 'Group' and click [OK].

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.

[Example 2.4] Security System User Information Configuration: <<accounts.xml>>

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

[Example 2.5] Configuring Users Using Database: <<domain.xml>>

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

[Example 2.6] Without Using JEUS JDBC: <<domain.xml>>

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


Note

As applications frequently establish database connections and close them in this way, there may be some drop in performance. So, it is recommended to use JEUS JDBC (<datasource-id>) to enhance performance.

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

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.

Note

It is recommended to use AES, a symmetric-key algorithm with proven reliability.

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.

ItemDescription
AES/DES/DESede/SEED/Blowfishcryptographic symmetric-key algorithm.
base64Encoding algorithm. Since the information encrypted in Base64 can be easily decoded by any one, it is not secure.
SHAHash algorithm. Decryption is impossible for this algorithm.

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.

Caution

The information is stored encrypted in Base64 in USER_HOME/.jeusadmin/.jeuspasswd. Since the Base64 encoding is not secure and is used to store sensitive user information, ID/password, it is not recommended for use.

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.

[Example 2.7] Stored Login Information: <<.jeuspassword>>

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

2.6. Configuring Security System Policies

When configuring default securities, the policy data (authorization data) is read from the file, policies.xml.

The file is in the following path.

JEUS_HOME/domains/<domain name>/config/security/<security domain name>/policies.xml

<domain name> is the domain name, and <security domain name> is the domain name where the policy will be applied.

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

Policy Configuration Main Screen

Caution

Like other user information configurations, only the policies.xml file that is provided by the default JEUS security system can be changed from this 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

Policy Configurations - Role Permission Registration


Resource Permissions Registration

The following shows how to register Resource Permissions.

  1. To grant resource permission to a role, select 'default' under Resource Permissions. Context ID is used to identify security policies, and 'default' is the Context ID of the security policy that is used in the default JEUS security system.

    [Figure 2.24] Policy Configurations - Resource Permission Registration (1)

    Policy Configurations - Resource Permission Registration (1)

  2. The default Context ID can be used to configure resource permissions for the JEUS system. Under the Resource Permissions, a role-to-resource mapping can be added by clicking [Add].

    [Figure 2.25] Policy Configurations - Resource Permission Registrations (2)

    Policy Configurations - Resource Permission Registrations (2)


  3. On the Resource Permissions screen, enter the resource name and actions, and select the roles for the resource, and then click [Add]. Like the Role Permission configurations, to deny access to the resource, click 'Excluded' and to allow access to the resource, check 'Unchecked'. For the list of JEUS resource permissions, refer to "Appendix B. JEUS Server Permissions".

    [Figure 2.26] Policy Configurations - Resource Permission Registration (3)

    Policy Configurations - Resource Permission Registration (3)

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.

[Example 2.8] Security System Policy Configurations: <<policies.xml>>

<?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 other role has the same role name as this permission.

  • The current time is between the specified time limits (example: 9 am and 5 pm).

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.

  1. Create the Custom Permission. Then, compile the class with javac and set the class path within the JEUS server class path.

    Configure the Permission in the policies.xml file. The following implements the Custom Permission class that meets the aforementioned requirements. Code details have been omitted.

    [Example 2.9] Custom Permission Class: <<TimeConstrainedRolePermission.java>>

    package jeus.security.resource;

import java.security.Permission;
import java.util.Calendar;
import java.util.StringTokenizer;

/**
 * A time-constrained Role permission.
 * <p>
 * With this permission implementation you can express
 * things such as "X can only be in the role Y between
 * 09:00 AM to 05:00 PM".
 */
public class TimeConstrainedRolePermission extends RolePermission {
    private String timeConstraint = "*";
    private int startTime = Integer.MIN_VALUE;
    private int endTime = Integer.MAX_VALUE;

    public TimeConstrainedRolePermission(String roleName) {
        this(roleName, "*");
    }

    public TimeConstrainedRolePermission(String roleName, String timeConstraint)
    {
        super(roleName);
        if (timeConstraint != null) {
            this.timeConstraint = timeConstraint;
            parseTimeConstraint();
        }
    }

    private void parseTimeConstraint() {
        . . .
    }

    public boolean equals(Object anotherObject) {
        . . .
    }

    public int hashCode() {
        . . .
    }

    public String getActions() {
        return timeConstraint;
    }

    public boolean implies(Permission anotherPermission) {
        if (this.timeConstraint.equals("*")) {
            return super.implies(anotherPermission);
        } else {
            Calendar cal = Calendar.getInstance();
            int curHour = cal.get(Calendar.HOUR_OF_DAY);
            int curMinute = cal.get(Calendar.MINUTE);
            int now = curHour * 60 + curMinute;
            if (now >= this.startTime && now <= this.endTime) {
                return super.implies(anotherPermission);
            } else {
                return false;
            }
        }
    }
}


    The previous class inherits the jeus.security.resource.RolePermission class, which in turn inherits the java.security.Permission class. This structure promotes code reusability.

    It is also possible to create another java.security.Permission class by inheriting the TimeConstrainedRolePermission class.

    In the previous example, there are two types of constructors.

    • The first has one parameter (role name).

    • The second has two parameters (role name, time constraint)

      In java.security.Permission class, the first parameter is name, and the second parameter is actions. Some permission implementation classes omit the second constructor that receives the actions parameter.

      • The actions parameter contains the valid time period for the permission, and it has the value “09:00-17:00”.

      • The name parameter represents the role name, such as administrator or teller.

    The heart of the implementation is in the "implies(Permission anotherPermission)" method, which first checks whether the current system time is within the given time constraints. And, if so, it delegates the call to the super class by calling the super.implies() method, and if not, it returns "false". All implies(..) method should return a boolean value, and whether the relevant Permission implies the Permission object passed to it.

    Note

    1. For more information about the implies() method and the abstract class java.security.Permission, refer to Java SE Javadoc documents.

    2. For more information about jeus.security.resource.RolePermission, jeus.security.resource.TimeConstrainedRolePermission, and jeus.security.resource.ResourcePermission classes, refer to Reference and jeus.security.resource package in JEUS Security Javadoc.

  2. Configure the policies.xml file to use permissions.

    [Example 2.10] Custom Permission Class: <<policies.xml>>

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<policies xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
   <policy>
      <role-permissions>
         <role-permission>
            <principal>user2</principal>
            <role>administrator</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>administrator</role>
            <resource>jeus.*</resource>
            <actions>*</actions>
         </resource-permission>
      </resource-permissions>
   </policy>
   . . .
</policies>


    The user, user2, is in the administrator role during the business hours of 9 am to 5 pm. The administrator role has the right to perform any actions (‘*’) on all JEUS resources (‘jeus.*’). Therefore, user2 can perform any operations on all JEUS resources during the business hours.

    The previous rule also applies when configuring JEUS DD file in J2EE application and module. Naturally, the rule also applies to role-to-resource permission and to principal-to-role permission as shown in the previous example. For more information about using customized permissions in JEUS DD, refer to "Chapter 3. Configuring Security for Applications and Modules".

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.

[Example 2.11] Configuring Policies Using Database: <<domain.xml>>

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

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

2.7. Configuring Additional Settings

This section describes how to add additional configurations other than subject and policy.

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, follow these steps.

In the domain.xml file, define the property in jvm-option for a particular server. 

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

[Example 2.12] Java SE SecurityManager Configurations: <<policy>>

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.

[Example 2.13] Configuring Information to Grant Identity: <<cert-user-map.xml>>

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

[Example 2.14] Configuring the Certificate Information for Identity: <<user-cert-map.xml>>

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

Prev   Next
Chapter 1. Introducing the Security System Home Chapter 3. Configuring Security for Applications and Modules