This document covers the following topics:
Forwarding the User Credentials to Natural (JBoss Application Server 5 and 6 only)
Defining the Security Realm and Users (Oracle GlassFish Server only)
Natural for Ajax comes as a Java EE-based application. For the ease of installation, the access to this application is by default not secured. You might, however, wish to restrict the access to certain parts of the application to certain users. An important example is the configuration tool, which enables you to modify the Natural session definitions and the logging configuration of Natural for Ajax. Other examples are the Application Designer development workplace contained in Natural for Ajax or the Natural logon page.
This section does not cover the concepts of JAAS-based security in full extent. It provides, however, sufficient information to activate the preconfigured security settings of Natural for Ajax and to adapt them to your requirements. More information on the topics described in this section can be found, for instance, at http://www.jboss.org/jbossas/docs/ (security on JBoss is described in the Configuration Guide).
Notes:
Security is configured in the file web.xml. The path to this file depends on the application server.
JBoss Application Server
<application-server-install-dir>/server/default/deploy/njx<nn>.ear/cisnatural.war/WEB-INF
Oracle GlassFish Server
<application-server-install-dir>/glassfish/domains/domain1/applications/cisnatural/WEB-INF
Apache Tomcat
<application-server-install-dir>/webapps/cisnatural/WEB-INF
Note:
The following applies to Oracle GlassFish Server: After the deployment, the file
web.xml can no longer be modified. Therefore, it is
important that you unpack the WAR file before deploying it, make your changes
to the web.xml file, repack the WAR file, and then deploy
it. For this reason, unsigned WAR files are delivered for these two application
servers.
Great care must be taken when editing and changing the configuration file web.xml. After a change, the application server must be restarted.
Edit the file web.xml and look for the section that is commented with "Uncomment the next lines to add security constraints and roles.". Uncomment this section by removing the comment marks shown in boldface below:
<!-- Uncomment the next lines to add security constraints and roles. -->
<!--
<security-constraint>
<web-resource-collection>
<web-resource-name>Configuration Tool</web-resource-name>
<url-pattern>/conf_index.jsp</url-pattern>
<url-pattern>/faces/*</url-pattern>
</web-resource-collection>
...
<security-role>
<description>Administrator</description>
<role-name>nwoadmin</role-name>
</security-role>
-->
The security constraints defined by default are just examples. A
<security-constraint> element contains of a
number of <web-resource-collection> elements
combined with an <auth-constraint> element.
The <auth-constraint> element contains a
<role-name>. The whole
<security-constraint> element describes which
roles have access to the specified resources.
Example - the following definition specifies that only users in the role "nwoadmin" have access to the configuration tool:
<security-constraint>
<web-resource-collection>
<web-resource-name>Configuration Tool</web-resource-name>
<url-pattern>/conf_index.jsp</url-pattern>
<url-pattern>/faces/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>nwoadmin</role-name>
</auth-constraint>
</security-constraint>
In the following section, you will see where and how the roles are defined.
A few lines below in the file web.xml, there is a
section <security-role>. Here, the roles that
can be used in <security-constraint> elements
are defined. You can define additional roles as needed. The assignment of users
to roles is done outside this file and will often be done in a user management
that is already established at your site.
Example:
<security-role>
<description>Administrator</description>
<role-name>nwoadmin</role-name>
</security-role>
In the file web.xml, there is a section
<login-config>. The only element that should
possibly be adapted here is <auth-method>. You
can choose between the authentication methods "FORM"
and "BASIC". Form-based authentication displays a
specific page on which users who try to access a restricted resource can
authenticate themselves. Basic authentication advises the web browser to
retrieve the user credentials with its own dialog box.
Example:
<login-config>
<auth-method>FORM</auth-method>
...
</login-config>
The directory
<application-server-install-dir>/server/default/conf
contains a file named njxnwo-login-config.xml. The
relevant part in this file is the selection of the login module specified in
the <login-module> element and the
configuration of this login module. The login module determines where the user
definitions and the assignment of users to roles are maintained.
By default, the UsersRolesLoginModule is preconfigured. The
UsersRolesLoginModule expects the role definitions in one file
(props/njxnwo-roles.properties) and the user definitions
(password and assignment to roles) in another file
(props/njxnwo-users.properties). An example user
"admin" with the password
"adminadmin" and the role
"nwoadmin" is defined to begin with.
You can choose and configure a different login module (for example, one that expects the user and role definitions in a database or in an LDAP directory), or you can even write a custom login module.
On JBoss Application Server 6, Natural for Ajax is installed as a web application (WAR file). See Installing Natural for Ajax on JBoss Application Server 6.
In order to create a sample JAAS-based security configuration, proceed as follows:
Move the following sample configuration files from <application-server-install-dir>/server/default/deploy/cisnatural.war/WEB-INF to their appropriate locations as described below:
njxnwo-login-config.xml
Move this file to
<application-server-install-dir>/server/default/conf.
njxnwo-roles.properties and
njxnwo-users.properties
Move these two files to
<application-server-install-dir>/server/default/conf/props.
Add the following definition to the file <application-server-install-dir>/server/default/conf/jboss-service.xml:
<mbean code="org.jboss.security.auth.login.DynamicLoginConfig"
name="jboss:service=DynamicLoginConfig">
<attribute name="AuthConfig">njxnwo-login-config.xml</attribute>
<depends optional-attribute-name="LoginConfigService">
jboss.security:service=XMLLoginConfig
</depends>
<depends optional-attribute-name="SecurityManagerService">
jboss.security:service=JaasSecurityManager
</depends>
</mbean>
This sample configuration uses the UsersRolesLoginModule.
The UsersRolesLoginModule expects the role definitions in one file
(props/njxnwo-roles.properties) and the user definitions
(password and assignment to roles) in another file
(props/njxnwo-users.properties). An example user
"admin" with the password
"adminadmin" and the role
"nwoadmin" is defined to begin with.
You can choose and configure a different login module (for example, one that expects the user and role definitions in a database or in an LDAP directory), or you can even write a custom login module.
Copy the login module njx82login.jar from the installation directory to <application-server-install-dir>/server/default/lib. You will need this login module in the step Forwarding the User Credentials to Natural (see below).
On JBoss Application Server 7, Natural for Ajax is installed as a web application (WAR file). See Installing Natural for Ajax on JBoss Application Server 7.
The configuration of JBoss Application Server 7 as a so-called standalone server is described here.
All configuration (especially the security configuration) is centralized in the file <application-server-install-dir>/standalone/configuration/standalone.xml.
In order to create a sample JAAS-based security configuration, proceed as follows:
Move the following sample configuration files from <application-server-install-dir>/standalone/deployments/cisnatural.war/WEB-INF to their appropriate location as described below:
njxnwo-roles.properties and
njxnwo-users.properties
Move these two files to
<application-server-install-dir>/standalone/configuration.
Add the following security domain definition in the file
standalone.xml, under
<security-domains>:
<security-domain name="NaturalWebIOAndAjaxRealm" cache-type="default">
<authentication>
<login-module
code="UsersRoles"
flag="required">
<module-option name="usersProperties"
value="${jboss.server.config.dir}/njxnwo-users.properties"/>
<module-option name="rolesProperties"
value="${jboss.server.config.dir}/njxnwo-roles.properties"/>
<module-option name="realm" value="NaturalWebIOAndAjaxRealm"/>
<module-option name="password-stacking" value="useFirstPass"/>
</login-module>
</authentication>
</security-domain>
This sample configuration uses the login module UsersRoles.
The login module UsersRoles expects the role definitions in one
file (njxnwo-roles.properties) and the user definitions
(password and assignment to roles) in another file
(njxnwo-users.properties). An example user
"admin" with the password
"adminadmin" and the role
"nwoadmin" is defined to begin with.
You can choose and configure a different login module (for example, one that expects the user and role definitions in a database or in an LDAP directory), or you can even write a custom login module.
In specific cases, it is possible and useful to forward the authenticated user along with the password directly to the Natural for Ajax logon page. This spares the end user entering the user ID and password twice, once on the authentication form of the application server and once again on the Natural for Ajax logon page.
However, this works only if both the authentication on the application server and the authentication on the Natural Web I/O Interface server are done with the same credentials against the same authentication system. This will be the case, for example, if the Natural Web I/O Interface server is configured to authenticate with RACF and you are in possession of a login module that authenticates with the same system.
To forward the user credentials to Natural
In the file njxnwo-login-config.xml (see also
Choosing the Login Module above) replace the preconfigured
UsersRolesLoginModule with your own login module.
Your login module must be configured to share user and password in
the standard way in the sharedState map.
As in the example configuration delivered in
njxnwo-login-config.xml, make sure that the option
flag="required" is set.
Keep the second preconfigured login module
NJXLoginModule in place. This login module is responsible for
forwarding the authenticated user and credentials to Natural for Ajax.
Uncomment the following line:
<attribute name="SubjectAttributeName">j_subject</attribute>
This line is contained in the file <application-server-install-dir>/server/default/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml.
In the session configuration (see Session Configuration which is part of Using the Configuration Tool), switch on Forward credentials.
The following information applies toOracle GlassFish Server 3, however, the procedure is similar in other versions.
To create a new security realm and define the user
Open the tree node Configuration > server-config > Security > Realms.
Choose .
Enter "NaturalWebIOAndAjaxRealm" as the name of the new realm.
Select
com.sun.enterprise.security.auth.realm.file.FileRealm as
the class name.
Use the following properties which are predefined for this class:
| Option | Value |
|---|---|
| JAAS Context | fileRealm |
| Key File | ${com.sun.aas.instanceRoot}/config/keyfile |
Choose OK.
Edit the new realm NaturalWebIOAndAjaxRealm and choose
the button.
Choose .
Enter the user names and the passwords for the users. The name of the group list must be "nwoadmin".
Choose OK.
In the tomcat-users.xml file (which is located in the conf directory), specify the role "nwoadmin" for any desired user name and password. For example:
<user username="pepe" password="pepe123" roles="nwoadmin"/>
For detailed information on the necessary realm configuration for Tomcat, see http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html#UserDatabaseRealm.