Versions Compared

Old Version 76

changes.mady.by.user Unknown User (hcunico@gmail.com)

Saved on

compared with

New Version Current

changes.mady.by.user Hernan Cunico

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Anchor
top
top
Article donated by: Hernan Cunico
This article is an attempt to cover as many administrative tasks as possible, common and not so common tasks. This article is grouped in four main sections having a similar flow to what you would find while using the Geronimo Administration Console, this way should be easier for you to familiarize on both tasks and console.

...

Additional reference:

...

Covered in this section are the most common, every day, server related administrative tasks you may deal with. Subsequent sections will focus on configuring services, managing applications and configuring security.

...

Choosing the Web container (Jetty or Tomcat)

When you download and build Apache Geronimo from source code (from svn) you would get a directory structure similar to this one:

...

If the server is already running you have the option of using the Geronimo Administration Console to shutdown the server remotely. With the server up and running open a Web browser and point to the following URL to access the console:

http://localhost:8080/consoleImage Removed

Log in to the Geronimo Administration Console and click on Shutdown on the Console Navigation menul on the left.

...

  • Request:
    Lets you specify the Request Method from and the Requested URI. You can select the Requested Method from a drop-down menu, the possible values are ANY, POST and GET. To filter by Requested URI just enter a URI, for example http://localhost:8080/console/login.jspImage Removed.

Back to Top

...

Code Block
xml
xml
borderStylesolid
<dependency>
	        <uri>castor/jars/castor-0.9.5.3.jar</uri>
</dependency>

...

You should now see the database pool you just imported listed in the database pool portlet.

Image RemovedImage Added

Removing database pools

...

If you want to run any SQL command on this database make sure you select test from the Use DB: pull-down menu, enter the SQL command and then click on the Run SQL button. The results of the command will be displayed near the bottom of the protlet.

Configuring JMS

Connection factories, queues, topics and destinations.

To configure JMS, the JMS Connection Factories and JMS Destination Manager portlets are avaiable by selecting JMS on the Console Navigation menu on the left hand side. The JMS Connection Factories portlet illustrated in the following figure displays all the JMS connectors that are configured in the Geronimo server and allows you to add a new JMS Connection Factory.

Image Removed

Further details on JMS integration are covered in the Integrating A Third Party JMS Provider section.

Back to Top

Administering applications

The JMS Destination Manager portlet lists all the queues and topics that are configured in the Geronimo server.

Image Added

In Apache Geronimo v1.0 these portlet are not totally implemented and you will need to create deployment plans and command line tools to deploy these configurations. Additional details for configuring JMS and integration are covered in the Integrating A Third Party JMS Provider section.

Back to Top

Administering applications

This section focuses on the available alternatives for managing applications. This section will This section focuses on the available alternatives for managing applications. This section will show you how to perform these application management activities using the both Geronimo Administration Console and the command line options. For the examples shown in this section we will be using the HelloWorld.war sample application created in the Quick start - Apache Geronimo for the impatient section.

...

...

From the Install New Applications portlet click on Browse to specify the path to the HelloWorld.war in the Archive: section. Make sure the Start app after install checkbox is selected (by default it is checked) and then click on Install.

...

Another way to verify that the application has been successfully installed and started is by checking the Installed Web Applications portlet which is available by selecting Web App WARs on the Console Navigation menu on the left hand side. You should see the application listed as HelloWorld and with the status running.

Since the application we installed is HelloWold.WAR we use this portlet, when you install an EAR you can would check the status using the Installed Application EARs portlet available by selecting Application EARs on the Console Navigation menu on the left hand side. The installation procedure is the same for both WAR and EAR applications.

To remove apps ...

Deploy tool

Hot deployment

Starting and stopping application modules

Administering security

Adding security realms

...

the applications through the Geronimo Administration Console you will use these last two portlets, either the Installed Web Applications or the Installed Application EARs portlets depending on the application to uninstall.

Image Added

For our example access the Installed Web Applications portlet, and click on Uninstall for the Component Name HelloWorld. This will stop the application first and then uninstall it. The confirmation message " Uninstalled application " should be listed at the bottom of the portlet.

These are the basic steps for installing and uninstalling applications via de Geronimo Administration Console, the following two sections will focus on the command line options.

Back to Top

Deployer tool

The deployer tool will allow you, among other things, install and uninstall applications via a command line. In this section we will focus on just these two tasks for the sample application, this tool is fully covered in the Deployer tool section.

To deploy the HelloWorld.war sample application using the Deployer tool open a command line window and type the following command from the <geronimo_home>\bin directory:

deploy --user system --password manager deploy <app_home>\HelloWorld.war

Once deployed you should see a confirmation message similar to this one:

No Format
bgColor#000000
borderStylesolid

E:\geronimo-1.0_Jetty\bin>deploy --user system --password manager deploy ..\..\HelloWorld\HelloWorld.war
    Deployed HelloWorld @ http://hcunico:8080/hello

As a difference from the deployment via de Geronimo Administration Console, using the command line tool you receive more information in the confirmation message. For instance you receive the Component Name (a.k.a. ConfigId) and you also receive the context root where the application was deployed. This is very usefull when isntalling, testing and uninstalling several different applications where it would be hard to remember all these values.

You can also use the Deployer tool to list all the installed applications. The list-modules command allows you to list all the applications, it also lets you narrow down the query by asking for just the started or stopped applications. The list-modules command without additional parameter will list by default all the started applications.

To uninstall an application you may want to list it first to get the right Component Name (or ConfigId). Run the following command from the <geronimo_home>\bin directory:

deploy --user system --password manager list-modules

You will receive a list similar as the one shown in the following example.

No Format
bgColor#000000
borderStylesolid

E:\geronimo-1.0_Jetty\bin>deploy --user system --password manager list-modules
Found 36 modules
  + geronimo/remote-deploy-jetty/1.0/car @ http://hcunico:8080/remote-deploy
  + geronimo/ldap-demo-jetty/1.0/car @ http://hcunico:8080/ldap-demo
  + geronimo/activemq-broker/1.0/car
  + geronimo/j2ee-server/1.0/car
  + geronimo/jetty-deployer/1.0/car
  + geronimo/welcome-jetty/1.0/car @ http://hcunico:8080/
  + geronimo/ldap-realm/1.0/car
  + geronimo/uddi-jetty/1.0/car
      `-> uddi-jetty @ http://hcunico:8080/juddi
      `-> uddi-db
  + HelloWorld @ http://hcunico:8080/hello
  + user/database-pool-examples-dataSource-demoPool/1/car
  + user/database-pool-Derby_Test/1/car
  + user/database-pool-DefaultDS/1/car
  + geronimo/activemq/1.0/car
  + geronimo/directory/1.0/car
  + geronimo/j2ee-security/1.0/car
  + geronimo/j2ee-deployer/1.0/car
  + geronimo/hot-deployer/1.0/car
  + geronimo/system-database/1.0/car
  + geronimo/jmxdebug-jetty/1.0/car @ http://hcunico:8080/debug-tool
  + geronimo/j2ee-system/1.0/car
  + geronimo/jsp-examples-jetty/1.0/car @ http://hcunico:8080/jsp-examples
  + geronimo/rmi-naming/1.0/car
  + geronimo/jetty/1.0/car
  + geronimo/servlets-examples-jetty/1.0/car @ http://hcunico:8080/servlets-examples
  + geronimo/daytrader-derby-jetty/1.0/car
      `-> daytrader-web-1.0.war @ http://hcunico:8080/daytrader
      `-> daytrader-ejb-1.0.jar
      `-> daytrader-streamer-1.0.jar
      `-> daytrader-wsappclient-1.0.jar
      `-> TradeDataSource
      `-> TradeJMS
  + geronimo/geronimo-gbean-deployer/1.0/car
  + geronimo/webconsole-jetty/1.0/car
      `-> geronimo-console-standard-1.0.war @ http://hcunico:8080/console-standard
      `-> geronimo-console-framework-1.0.war @ http://hcunico:8080/console
    geronimo/client-system/1.0/car
    geronimo/j2ee-corba/1.0/car
    geronimo/daytrader-derby-jetty-streamer-client/1.0/car
    geronimo/javamail/1.0/car
    geronimo/online-deployer/1.0/car
    geronimo/client-security/1.0/car
    geronimo/client-corba/1.0/car
    geronimo/client/1.0/car
    geronimo/shutdown/1.0/car

Look for the HelloWorld entry, thas is the value you will have to use when trying to uninstall the application.

To uninstall the application run the following command from the <geronimo_home>\bin diretory using the Component Name you identified while listing the modules.

deploy --user system --password manager undeploy HelloWorld

This command will first stop the runnning application and then uninstall it. You should see a confirmation message similar to this:

No Format
bgColor#000000
borderStylesolid

E:\geronimo-1.0_Jetty\bin>deploy --user system --password manager undeploy HelloWorld
    Module HelloWorld unloaded.

    Module HelloWorld uninstalled.

    Undeployed HelloWorld

In this example you have used the same tool with three different commands:

  • deploy
  • list-modules
  • undeploy

These are not the only options and commands available for this tool, please visit the Deployer tool section for additional details.

Back to Top

Hot deployment

Apache Geronimo has support for Hot Deployment. This means that you can copy an application JAR file into the <geronimo_home>/deploy directory and the application will be deployed automatically. This will also work for uninstalling or refreshing applications previously deployed via this method. Alternatively, you may also copy the directory (umpacked) for the application module instead of copying a single JAR file.

Note that with this deployment method you have to include the deployment plan in the application package, this method does not support external deployment plans. Also note that applications deployed via the Deployer tool or the Geronimo Administratio Console will not be listed in the <geronimo_home>/deploy directory.

When you copy an application in the deploy directory, let's say HelloWorld.war, you will see a confirmation message in the console where Geronimo is running stating the application was deployed and the context to access that application.

No Format
bgColor#000000
borderStylesolid

11:50:22,501 INFO  [Hot Deployer] Deploying HelloWorld.war
    Deployed HelloWorld @ http://hcunico:8080/hello

To remove the application, just delete the WAR or EAR file from the deploy directory. When the application has been removed you should see a confirmation message in the console where Geronimo is running stating the application was undeployed.

No Format
bgColor#000000
borderStylesolid

11:57:33,451 INFO  [Hot Deployer] Undeploying HelloWorld.war
    Undeployed HelloWorld

Back to Top

Starting and stopping application modules

You can change the status of an application in two different ways. You can use the Deployer tool or the Geronimo Administration Console.

As mentioned before, the Deployer tool has many commands. So far we have explored mainly deploy and undeploy and very briefly list-modules. This section is going to focus on the latter command to retrieve the name of the module we want to change the status and will introduce two new commands, start and stop. Later we will discuss the use of the Geronimo Administration Console as the alternative method.

The list-module command accepts the following tree parameters:

  • --all : is used by default when no other option is specified. It will list all the available modules.
  • --started : this option will list only the modules that are running.
  • --stopped : this option will list only the modules that are not running.

This is usefull to identify the status of a particular module and the module ID itself. We will use this command to identify the HelloWorld application and change it's status.

From a command line window run the following command from the <geronimo_home>\bin directory to list all the modules:

deploy --user system --password manager list-modules

You will receive a list of all the modules installed on the server. Note that the started modules are differenciated by a + sign on the left and are displayed first in the list.

No Format
bgColor#000000
borderStylesolid

E:\geronimo-1.0_Jetty\bin>deploy --user system --password manager list-modules
Found 35 modules
  + geronimo/j2ee-deployer/1.0/car
  + geronimo/webconsole-jetty/1.0/car
      `-> geronimo-console-standard-1.0.war @ http://hcunico:8080/console-standard
      `-> geronimo-console-framework-1.0.war @ http://hcunico:8080/console
  + geronimo/welcome-jetty/1.0/car @ http://hcunico:8080/
  + geronimo/jetty-deployer/1.0/car
  + geronimo/directory/1.0/car
  + geronimo/ldap-realm/1.0/car
  + user/database-pool-examples-dataSource-demoPool/1/car
  + user/database-pool-DefaultDS/1/car
  + geronimo/j2ee-system/1.0/car
  + geronimo/activemq/1.0/car
  + geronimo/j2ee-server/1.0/car
  + HelloWorld @ http://hcunico:8080/hello
  + geronimo/ldap-demo-jetty/1.0/car @ http://hcunico:8080/ldap-demo
  + geronimo/jetty/1.0/car
  + geronimo/geronimo-gbean-deployer/1.0/car
  + geronimo/jsp-examples-jetty/1.0/car @ http://hcunico:8080/jsp-examples
  + geronimo/rmi-naming/1.0/car
  + geronimo/servlets-examples-jetty/1.0/car @ http://hcunico:8080/servlets-examples
  + geronimo/remote-deploy-jetty/1.0/car @ http://hcunico:8080/remote-deploy
  + geronimo/system-database/1.0/car
  + geronimo/j2ee-security/1.0/car
  + user/database-pool-Derby_Test/1/car
  + geronimo/activemq-broker/1.0/car
  + geronimo/jmxdebug-jetty/1.0/car @ http://hcunico:8080/debug-tool
  + geronimo/hot-deployer/1.0/car
  + geronimo/uddi-jetty/1.0/car
      `-> uddi-jetty @ http://hcunico:8080/juddi
      `-> uddi-db
    geronimo/client-system/1.0/car
    geronimo/online-deployer/1.0/car
    geronimo/client-corba/1.0/car
    geronimo/daytrader-derby-jetty-streamer-client/1.0/car
    geronimo/client-security/1.0/car
    geronimo/shutdown/1.0/car
    geronimo/client/1.0/car
    geronimo/javamail/1.0/car
    geronimo/j2ee-corba/1.0/car

Our taget now is "+ HelloWorld @ http://hcunico:8080/hello " , this module's status is started since there is a + on the left. Alternatively, you can run the following command to list just the started modules:

deploy --user system --password manager list-modules --started

To stop the HelloWorld module type the following command:

deploy --user system --password manager stop HelloWorld

You will receive a confirmation message that the module has been stopped.

When you list all the stopped modules you should now see added to the list the HelloWorld module. See the command and results in the following example.

No Format
bgColor#000000
borderStylesolid

E:\geronimo-1.0_Jetty\bin>deploy --user system --password manager list-modules --stopped
Found 10 modules
    geronimo/client-system/1.0/car
    geronimo/online-deployer/1.0/car
    geronimo/client-corba/1.0/car
    geronimo/daytrader-derby-jetty-streamer-client/1.0/car
    HelloWorld
    geronimo/client-security/1.0/car
    geronimo/shutdown/1.0/car
    geronimo/client/1.0/car
    geronimo/javamail/1.0/car
    geronimo/j2ee-corba/1.0/car

To start the modules just use start instead of stop.

As an alternative to the command line option you can use the Geronimo Administration Console to change the status of the modules. Open the Geronimo Administration Console and navigate to Applications on the Console Navigation menu on the left hand side. There you will find Application EARs and Web App WARs, depending on the type of application you want to change the status, you will choose either Application EARs or Web App WARs. For this example we will continue to use HelloWorld.war as the sample application, hence we will select Web App WARs.

Image Added

We used this portlet earlier to install and remove applications via the console. From this same portlet you can also change the status of the applications. The avaialable commands within the portlet will change depending on the status for each application. If the application is in running status (started), only the command Stop will be displayed. If the application is stopped, only the command Start will be displayed. The Unninstall command will always be displayed independently of the status of the application. To change the status of the application just click on the command (Start or Stop).

Back to Top

Administering security

This section covers some common security related taks such as adding and removing users and groups, dealing with digital certificates and increasing the security level by using different realms and authentication methods. Refer to the Security section for further details on how security is implemented in Apache Geronimo.

Administering users and groups

You can add users and groups via the Geronimo Administration Console or by modifying some configuration files. We will start simple by using the realm provided by Geronimo by default. Then, as we explore the different realms and security configurations, we will come back and revisit some of the topics as needed.

To manage users and groups via the Geronimo Administration Console the Console Realm portlet is avaiable on the Console Navigation menu on the left hand side. Here you will find two portlets, one for administering users and another for administering groups and illustrated in the following figures.

Image Added

Image Added

To change a user's password click on the user in the Console Realm Users portlet, it will bring up the UserID and Password so you can update that profile.

To add a new user click on Create New User, you will be prompted for a UserID and Password (twice), enter those values and click Add.

To remove a user click on the corresponding Delete, you will be prompted to confirm deletion of that user, click OK.

Once you created new users you can add them to group. By default, the group admin is available and the user system is in that group. If you click on the admin group you will see the user system in the window on the right and any other available user will be listed in the window on the left.

To add a new user to this group select the user first, then click Add >> and then click Update.

Image Added

To create a new group click on Create New Group, this step is very similar to the previous one. In addition to be prompted for adding users to this group you will also have to provide a group name. When you entered entered the new group name and added the users click on Add to finish.

The changes you made via the Console Realm Users and Console Realm Groups portlets are reflected in two different files, these files are users.properties and groups.properties respectively and they are located in the <geronimo_home>\var\security directory.

Warning

When you delete a user from the console, that user will not be removed from the group it belonged to. The Console Realm Users portlet will not modify the groups.

You can equally administer users and groups by modifying directly these files:

users.properties
groups.properties

users.properties uses the <user_name>=<password> format, groups.properties uses the <group_name>=<user_name> format. See the following examples for additional details.

No Format
borderStylesolid
titleusers.properties

system=manager
user2=p2
user1=p1

As we are using the basic, by default, security configuration you will see the user IDs and passwords are stored in plain text. You can add, remove and change passwords from this file.

No Format
borderStylesolid
titlegroups.properties

admin=system,user1
users=user2

Just like with the users, with the groups.properties you can add and remove groups and users to those groups.

The files mentioned in this sections along with the all the security configuration in addition to user names and passwords are defined in the geronimo-properties-realm security realm covered in the following section.

Back to Top

Administering security realms

Before we move on, it is recommended for you to become familiar with the Geronimo security architecture and concepts. Visit the Security section for details on how security is implemented in Geronimo. The two main Security concepts on which the Apache Geronimo security architecture is built on are Login Domain and Security Realm, in this section we will focus on the later.

To administer security realms via the Geronimo Administration Console the Security Realms portlet is available on the Console Navigation menu on the left hand side. This portlet allows you to add a new security realm or edit an existing one. To remove realms you would normally use the command line option with the Deployer tool.

Image Added

Listed in this portlet you will find all the available security realms. By default, the security realm used by Geronimo to authenticate users via properties file is geronimo-properties-realm.

When you edit an existing realm (in this case geronimo-properties-realm) you will be presented with the following screen, note that you will not be able to change the realm name nor the login domain name.

Image Added

The following example illustrates the deployment plan generated by this portlet.

Code Block
xml
xml
borderStylesolid
titlegeronimo-properties-realm

<configuration configId="SecurityRealm-geronimo-properties-realm" xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0">
    <gbean name="geronimo-properties-realm" class="org.apache.geronimo.security.realm.GenericSecurityRealm">
        <attribute name="realmName">geronimo-properties-realm</attribute>
	<reference name="ServerInfo">
	    <gbean-name>geronimo.server:J2EEApplication=null,J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
	                j2eeType=GBean,name=ServerInfo</gbean-name>
	</reference>
        <reference name="LoginService">
            <gbean-name>geronimo.server:J2EEApplication=null,J2EEModule=geronimo/j2ee-security/1.0/car,J2EEServer=geronimo,
	            j2eeType=JaasLoginService,name=JaasLoginService</gbean-name>
        </reference>
	<xml-reference name="LoginModuleConfiguration">
            <log:login-config xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-1.0">
                <log:login-module control-flag="REQUIRED" server-side="true" wrap-principals="false">
                    <log:login-domain-name>geronimo-properties-realm</log:login-domain-name>
                    <log:login-module-class>org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule</log:login-module-class>
                    <log:option name="usersURI">var/security/users.properties</log:option>
                    <log:option name="groupsURI">var/security/groups.properties</log:option>
                </log:login-module>
            </log:login-config>
        </xml-reference>
    </gbean>
</configuration>

As we mentioned before, this plan is for the default, properties file based, security realm. When you create a new realm you will have to choose from the following realm types available:

  • Certificate Properties File Realm
  • Database (SQL) Realm
  • LDAP Realm
  • Properties File Realm
  • Other

The last available option lets you create your custom realm type when none of the above fits your environment needs.

Apache Geronimo has a properties file realm already configured, this is the default realm used for authentication. Geronimo also comes with a set of sample applications, one of those applications provide an additional security realm for LDAP. For this example, we will focus on a different type, we will use a database for verifying and retrieving user names and passwords.

For this example we created a new database called SecurityDatabase using the built-in Derby database. The following steps summarize the procedure followed to create the database and tables, load some sample data and create the connection pool. Detailed instructions on how to define database connection pools are described in the #Configuring database pools section.

Create database and load sample data

  • In the Console Navigation menu on the left click on Database Manager.
  • Enter SecurityDatabase in the Create DB: field and click Create.
  • Select the SecurityDatabase database from the Use DB: pull-down menu, enter the following commands and click Run SQL.
    create table users
    (username varchar(15),
    password varchar(15));
    create table groups
    (username varchar(15),
    groupname varchar(15));
    insert into users values('userone','p1');
    insert into users values('usertwo','p2');
    insert into users values('userthree','p3');
    insert into groups values('userone','admin');
    insert into groups values('usertwo','admin');
    insert into groups values('userthree','user');

Create connection pool

  • In the Console Navigation menu on the left click on Database Pools.
  • Click on Using the Geronimo database pool wizard.
  • Enter SecurityDatabase as the database pool name. Select Derby embedded from the database pool type pull-down menu and click Next.
  • Verify the JDBC driver class is org.apache.derby.jdbc.EmbeddedDriver.
  • From the Driver Jar pull-down menu select org.apache.derby/derby/10.1.1.0/jar.
  • Leave blank the connection user name and password.
  • Enter SecurityDatabase as the database name and click Next.
  • Click Test Connection.
  • Click Deploy.

Add a new security realm

To create a new security realm click on Add new security realm from the Security Realms portlet.

Image Added

Enter derby_security_realm in the Name of Security Realm: field and select Database (SQL) Realm from the Realm type: pull-down menu and click Next.

The following screen configures the login module. The first two field you need to fill will potentially vary from one database type to another. In this case we are using the embedded Derby database so the User and Group select SQL should read as follows:

User SELECT SQL: select username, password from APP.users where username=?
Group SELECT SQL: select username, groupname from APP.groups where username=?

Note that APP is the default schema for the embedded Derby database and it needs to precede the table in the SQL statement. These statements are likely to be different from one database to another, for instance this procedure was also tested with DB2, the SQL statements used were:

User SELECT SQL: select username, password from users where username=?
Group SELECT SQL: select username, groupname from groups where username=?

Once you entered the SQL statements for retrieving users and groups you need to select from the Database Pool pull-down menu the database connection pool you created in the previous step ( #Create connection pool) and click Next.

The remaining fields are no necessary to fill since that information is already provided by the database conneciton pool. If you are not using predefined database connection pools you will need to fill-in all the fields.

Image Added

The following step will allow you to enable auditing for monitoring the login attempts via this realm. In this step you can also configure the account lockout based on the number of failed loging attempts withing a specified timeframe. The last option in this step, Store Password, when enabled will allow the realm to store the user password in a private credential in the subject.

Image Added

At this point you have configured this new security realm, the next step i to test it and then deploy it. Click on Test a Login.

Enter a valid user name and password to be retrieved from the database and click Next.

Image Added

You should receive a confirmation message that the login succeded, click on Deploy Realm to load this configuration to the server.

Image Added

Now you have a new, fully configured, security realm that retrieves user names and passwords from the build in Derby database.

The followig example shows the deployment plan for this security realm. As an alternative to the Geronimo Administration Console, you can save this example to a file (i.e. derby_security_realm.xml) and deploy it with the Deployer tool by running the following command:

<geronimo_home>\bin\deploy --user system --password manager deploy <realm_path>\derby_security_realm.xml

Code Block
xml
xml
borderStylesolid
titlederby_security_realm

<configuration configId="SecurityRealm-derby_security_realm" xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0">
    <import>
        <uri>user/database-pool-SecurityDatabase/1/car</uri>
    </import>
    <gbean name="derby_security_realm" class="org.apache.geronimo.security.realm.GenericSecurityRealm">
        <attribute name="realmName">derby_security_realm</attribute>
        <reference name="ServerInfo">
            <gbean-name>geronimo.server:J2EEApplication=null,J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
	                j2eeType=GBean,name=ServerInfo</gbean-name>
        </reference>
        <reference name="LoginService">
            <gbean-name>geronimo.server:J2EEApplication=null,J2EEModule=geronimo/j2ee-security/1.0/car,J2EEServer=geronimo,
	                j2eeType=JaasLoginService,name=JaasLoginService</gbean-name>
        </reference>
        <xml-reference name="LoginModuleConfiguration">
            <log:login-config xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-1.0">
                <log:login-module control-flag="REQUIRED" server-side="true" wrap-principals="false">
                    <log:login-domain-name>derby_security_realm</log:login-domain-name>
                    <log:login-module-class>org.apache.geronimo.security.realm.providers.SQLLoginModule</log:login-module-class>
                    <log:option name="userSelect">select username, password from APP.users where username=?</log:option>
                    <log:option name="dataSourceApplication">null</log:option>
                    <log:option name="groupSelect">select username, groupname from APP.groups where username=?</log:option>
                    <log:option name="dataSourceName">SecurityDatabase</log:option>
                </log:login-module>
                <log:login-module control-flag="OPTIONAL" server-side="true" wrap-principals="false">
                    <log:login-domain-name>derby_security_realm-Audit</log:login-domain-name>
                    <log:login-module-class>org.apache.geronimo.security.realm.providers.FileAuditLoginModule</log:login-module-class>
                    <log:option name="file">var/log/derby_security_realm.log</log:option>
                </log:login-module>
                <log:login-module control-flag="REQUISITE" server-side="true" wrap-principals="false">
                    <log:login-domain-name>derby_security_realm-Lockout</log:login-domain-name>
                    <log:login-module-class>org.apache.geronimo.security.realm.providers.RepeatedFailureLockoutLoginModule</log:login-module-class>
                    <log:option name="lockoutDurationSecs">60</log:option>
                    <log:option name="failurePeriodSecs">10</log:option>
                    <log:option name="failureCount">3</log:option>
                </log:login-module>
            </log:login-config>
        </xml-reference>
    </gbean>
</configuration>

Testing the security realm

If you want to quickly test this realm you can use the LDAP sample application covered in the Configuring LDAP section. You will just need to change the deployment descriptor geronimo-web.xml to the one shown in the following example, repackage the application and deploy it.

Note that we only changed from the original plan the realm name from ldap-realm to derby_security_realm.

Code Block
xml
xml
borderStylesolid
titlegeronimo-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://geronimo.apache.org/xml/ns/web"
    xmlns:sec="http://geronimo.apache.org/xml/ns/security"
    configId="org/apache/geronimo/ldap-secure-demo">
    <context-root>/ldap-demo</context-root>
    <context-priority-classloader>false</context-priority-classloader>
<!--    <security-realm-name>ldap-realm</security-realm-name> -->
	<security-realm-name>derby_security_realm</security-realm-name>
    <security>
        <default-principal realm-name="derby_security_realm">
            <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"/>
        </default-principal>
        <role-mappings>
            <role role-name="content-administrator">
                <realm realm-name="derby_security_realm">
                    <principal class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" name="admin" designated-run-as="true"/>
                    <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"/>
                </realm>
            </role>
            <role role-name="guest">
                <realm realm-name="derby_security_realm">
                    <principal class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal" name="guest" designated-run-as="true"/>
                    <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="user1"/>
                    <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="user2"/>
                </realm>
            </role>
        </role-mappings>
    </security>
</web-app>

Follow the instructions in the Configuring LDAP section to repackage and deploy the application. When you test it, this time you will using the database SQL realm. Give it a try a few times, you should see the successful login attempts recorded in the log file you specified when created this security realm (in this example var\log\derby_security_realm.log)

No Format
borderStylesolid
titlederby_security_realm.log

03/01/2006 15:56:33 - Authentication attempt - userone
03/01/2006 15:56:33 - Authentication succeeded - userone
03/01/2006 16:10:05 - Authentication attempt - usertwo
03/01/2006 16:10:05 - Authentication succeeded - usertwo

Back to Top

Administering certificates

To administer SSL certificates the Keystore Configuration portlet in available by selecting Keystore on the Console Navigation menu on the left hand side. From this portlet you can either import an existing certificate or create a new certificate request.

Image Added

The certificates in Geronimo are stored in a keystore located in <geronimo_home>\var\security\ssl-keystore-1. This ssl keystore file does not exist until you create the first private key.

If you already have a certificate you can click on import trusted certificate.

Image Added

Specify the location of the certificate file and click View Certificate. The certificate information will be displayed, you may add an alias to identify this certificate, when done click on Import to add that certificate to the keystore. You should now see that the keystore size has increased.

To generate a key click on generate key pair. In the following screen enter the relevant information and click on Submit. For this example we entered the following values:

Alias:

Geronimo Server

Key Algorithm:

RSA

Key Size:

1024

Signature Algorithm:

MD5withRSA

Validity:

2000

Common Name (CN):

127.0.0.1

Organizational Unit (OU):

Geronimo

Organizational Name (O):

Apache

Locality (L):

Locality

State (ST):

State

Country (C):

Country

You should now see that the keystore size has increased and the private key you just created is listed near the bottom of the Keystore Configuration portlet. Click on view next to the private key you created, you should see the details of this key pair and the options to generate a certificate request and to import a certificate reply from a certification authority (CA).

Image Added

To generate a certificate request to send to a CA click on generate CSR, copy the content generated and send it to the CA (you would normally receive the instructions from the CA on how to send this CSR).

Image Added

Once you receive the reply from the CA you will likely receive a certificate file, to add this certificate to the keystore follow the steps to import trusted certificate.

Using the certificates

Warning

There is currently a known issue using the certificates to secure new HTTPS listeners, there is a patch alredady available and it should be applied to the next release of Apache Geronimo, see JIRA GERONIMO-1503 for details.

To use your own certificates instead of the one provided by default with the installation you need to create a new HTTPS listener. Use the Network Listener portlet available by selecting Web Server in the Console Navigation menu on the left hand side. The steps for adding a new HTTPS listener were covered earlier in the #Add new HTTPS listener section.

Back to Top