Return-Path: Delivered-To: apmail-geronimo-scm-archive@www.apache.org Received: (qmail 3209 invoked from network); 12 Dec 2005 05:28:54 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 12 Dec 2005 05:28:54 -0000 Received: (qmail 45654 invoked by uid 500); 12 Dec 2005 05:28:50 -0000 Delivered-To: apmail-geronimo-scm-archive@geronimo.apache.org Received: (qmail 45474 invoked by uid 500); 12 Dec 2005 05:28:49 -0000 Mailing-List: contact scm-help@geronimo.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: dev@geronimo.apache.org List-Id: Delivered-To: mailing list scm@geronimo.apache.org Received: (qmail 45233 invoked by uid 99); 12 Dec 2005 05:28:47 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 11 Dec 2005 21:28:47 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Sun, 11 Dec 2005 21:28:34 -0800 Received: (qmail 2797 invoked by uid 65534); 12 Dec 2005 05:28:13 -0000 Message-ID: <20051212052813.2795.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r356160 [10/11] - in /geronimo/branches/1.0/modules/scripts/src/resources/docs: ./ Administrative tasks_attachments/ Apache Geronimo V1 - Documentation_attachments/ Architecture_attachments/ Configuring LDAP_attachments/ Geronimo Administra... Date: Mon, 12 Dec 2005 05:27:58 -0000 To: scm@geronimo.apache.org From: dain@apache.org X-Mailer: svnmailer-1.0.5 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Login into Geronimo.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Login%20into%20Geronimo.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Login into Geronimo.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Login into Geronimo.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,154 @@ + + + Geronimo : Login into Geronimo + + + + + + + + + +

+ + Geronimo : Login into Geronimo + +

+ This page last changed on Nov 16, 2005 by hcunico@gmail.com. +

+ + +

+ +

Article donated by: Simon Godik, Hernan Cunico

+ +

Login Service API

Login into Geronimo is mediated by the Login Service implemented by the org.apache.geronimo.security.server.JaasLoginService gbean. To login into the server is to establish a security session with the Login Service. Login Service will perform authentication based on the application security requirements. Application security requirements are enforced by the security realm. Client application tells Geronimo server the name of the security realm it wants to use. Refer to the Geronimo and JAAS section for a discussion on the name parameter passed by the client to the security implementation.

+ +

It is useful to look briefly at the org.apache.geronimo.security.server.JaasLoginService API:

+ +

JaasSessionId connectToRealm(String realm-name)
+This method allows client to select the security realm and to initiate security session. Security-session-id is returned to the client.
+Client is supposed to hold on to it.

+ + +

JaasLoginModuleConfiguration[] getLoginConfiguration(JaasSessionId session-id)
+Return array of login module configurations for the security realm associated with the session-id.
+JaasLoginModuleConfiguration includes login module name, control flag, login module options, etc.

+ + +

boolean performLogin(JaasSessionId session-id, int login-configuration-idx, Callback[] callbacks)
+Perform login for the login module in the security realm associated with the session-id.
+Login module is selected by the login-configuration-idx.
+Callbacks is the array of Callback objects required by the login module and populated by the client.

+ + +

boolean performCommit(JaasSessionId session-id, int login-configuration-idx)
+Commit login results the login modules in the security realm associated with the session-id.
+Login module is selected by the login-configuration-idx parameter.

+ + +

Principal loginSucceed(JaasSessionId session-id)
+Signal that overall login succeeded for the security session. This method returns IdentificationPrincipal for the session.

+ + +

Set synchPrincipals(JaasSessionId session-id, Set principals)
+Synchronize principals between client-side subject and session subject. All principals from the client subject are added to the session subject and
+serializable principals from the session subject are added to the client subject.

+ + + +

Any client that has a reference to the JaasLoginService gbean can use it's API to log into Geronimo.

+ +

Login into Geronimo the portable way: JaasLoginCoordinator

Client side in the Geronimo login process is represented by the org.apache.geronimo.security.jaas.client.JaasLoginCoordinator login module. JaasLoginCoordinator drives login process using the Geronimo Login Service API and computes authentication result based on the JAAS login module combination semantics.

+ +

As a Login Module, JaasLoginCoordinator can be configured in the remote client or in the Geronimo server for use by the locally deployed component (such as a servlet).

+ +

JaasLoginCoordinator is invoked by the JAAS framework (as any other login module would be) in a sequence of initialize, login, and commit calls.

+ +

Next you can at each step more in detail.

+ +

JaasLoginCoordinator.initialize()

On initialization step, JaasLoginCoordinator connects to the Login Service etc. Because JaasLoginCoordinator represents authentication client, it keeps it's own Subject instance.

+ +

JaasLoginCoordinator.login()

Step 1: Initiate security session with the Login Service by calling connectToRealm(realmName); Realm name is passed as an input parameter from the application.
+A new security session is started by the Login Service and saved in the active-logins map. Security session identifier is returned to the JaasLoginCoordinator.

+ +

Two notes should be made here:

One is that the security session holds an instance of it's own Subject (distinct from the Subject held in the JaasLoginCoordinator). This Subject will be populated with principals from the login modules configured into security realm.
The other is that each JaasLoginModuleConfiguration within security session contains wrapPrincipals boolean flag. If set to true, the login module (Login Domain) will be wrapped with the special login module proxy. The type of this proxy is org.apache.geronimo.security.jaas.WrappingLoginModuleProxy and it has special behavior within it's commit() method. It produces additional Principals that hold association of a principal to the login domain and a principal to the security realm.

+ + +

In particular org.apache.geronimo.security.DomainPrincipal will be added for every Principal instance instantiated by the original login module (login domain) and RealmPrincipal will be added for each DomainPrincipal when login module is committed.

+ +

Step 2: Based on the security-session-id retrieve an array of JAAS login module configurations wired into the security realm by calling:
+JaasLoginModuleConfiguration[] getLoginConfiguration(JaasSessionId session-id). For further details refer to JaasLoginModuleConfiguration in the Login Service API section.

+ +

Step 3: Having to account for the remote and local scenarios, the JaasLoginCoordinator wraps each login-module in the JaasLoginModuleConfiguration[] array it got from the JaasLoginService with the LoginModuleProxies. LoginModuleProxies are login modules themselves (obviously). LoginModuleProxy is sub-classed with the ServerLoginProxy and ClientLoginProxy. ClientLoginProxy is further sub-classed by the WrappingClientLoginProxy.

+ +

We are now going to concentrate on the ServerLoginProxy. In keeping with the JAAS API, login modules wrapped by the login module proxies are invoked with the initialize, login, and commit sequence.

+ +

There are several details you have to keep in mind about this.

The Subject instance passed to the initialize() method for every login module proxy is JaasLoginCoordinator owned Subject instance (representing Subject on the client side).
Callback handler is passed by the client that initiated login procedure (for example a servlet).
Shared state for login modules is synchronized between JaasLoginCoordinator (the client side) and JaasLoginService (the server side) at the end of initialization loop.

+ + +

Step 4: Let the login procedure begin! Here is the place where the JAAS login module semantic is actually enforced by comparing the result of the login() method call for each login module proxy and login module configuration control flag. For further details on this procedure refer to the Geronimo and JAAS section.

+ +

Note that this computation is done by the JaasLoginCoordinator which is authentication client and not by the JaasLoginService itself.

+ +

Now we are going to look into what happens within the ServerLoginProxy.login() method. There is an array of ServerLoginProxies[] that correspond to the array of JaasLoginModuleConfigurations[] retrieved from the JaasLoginService. Each ServerLoginProxy is constructor-injected with the login-module control-flag, client-side Subject, JaasLoginModuleConfiguration array index, a reference to the JaasLoginService and security-session-id.

+ +

ServerLoginProxy.login() method first retrieves an array of Callbacks[] from the JaasLoginService that are configured for the corresponding login module in the security realm:
+Callback[] LoginService.getServerLoginCallbacks(security-session-id, login-module-index).
+We leave it out to figure out how it is done. The important thing at this time is that you can pass this callback array to the callback-handler (injected during initialize() method call and supplied by the authentication client (see above)). callback-handler.handle(Callbacks[]) populates server callbacks array with client data.

+ +

Now ServerLoginProxy.login() method asks the JaasLoginService to perform the actual login by passing it the security-session-id, login-module-configuration index, and an array of populated callbacks. As a result, security-session is retrieved from the active-logins map, and corresponding login module (configured in the security realm under login module index) is invoked to perform the login.

+ +

A point to note here is that security realm login modules are initialized at the time when server-side callbacks are retrieved by the ServerLoginProxy in preparation for login. (Not an obvious place to look). All information to the security realm login module comes from the security session (it is on the server-side of course).

+ +

It looks like we are logged in, or at least close...

+ +

JaasLoginCoordinator.commit()

If overall authentication succeeds (according to the security realm policy), JaasLoginService.commit() is called. Login-module-proxy.commit() is called for every proxy in the login module proxy array. It is here that all principals in the security realm login modules are collected (and possibly wrapped into the DomainPrincipal and RealmPrincipal) and then added to the Subject in the security session (server-side). At the end of the commit-loop, Principals between JaasLoginCoordinator Subject (client-side) and security session Subject (server-side) are synchronized. Principals from the JaasLoginCoordinator Subjects are added to the security session Subject (in case of the server-side JaasLoginCoordinator this is an empty set) and serializable Principals from the security session Subject are added to the JaasLoginCoordinator Subject.

+ +

At the very end JaasLoginCoordinator.commit() method notifies the JaasLoginService of login success: LoginService.loginSucceed(security-session-id). As a result, JaasLoginService registers it's session Subject with the ContextManager and generates a subject-id based on the Subject. It then wraps this subject-id into the IdentificationPrincipal, adds it to the set of Principals in the Subject and returns IdentificationPrincipal to the JaasLoginCoordinator.

+ +

JaasLoginCoordinator adds IndentificationPrincipal into it's own Subject.

+ +

Authentication complete!!!

+ + +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Login into Geronimo.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Login into Geronimo.html ------------------------------------------------------------------------------ svn:executable = * Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Maintenance.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Maintenance.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Maintenance.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Maintenance.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,39 @@ + + + Geronimo : Maintenance + + + + + + + + + +

+ + Geronimo : Maintenance + +

+ This page last changed on Dec 01, 2005 by hcunico@gmail.com. +

+ + +

+ +

Article donated by: Hernan Cunico

+ + +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Maintenance.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Maintenance.html ------------------------------------------------------------------------------ svn:executable = * Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Mapping J2EE Roles in M5 release.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Mapping%20J2EE%20Roles%20in%20M5%20release.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Mapping J2EE Roles in M5 release.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Mapping J2EE Roles in M5 release.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,86 @@ + + + Geronimo : Mapping J2EE Roles in M5 release + + + + + + + + + +

+ + Geronimo : Mapping J2EE Roles in M5 release + +

+ This page last changed on Nov 21, 2005 by hcunico@gmail.com. +

+ + +

+ +

Article donated by: Simon Godik, Hernan Cunico

+ +

The security schema namespace for the Apache Geronimo M5 is "http://geronimo.apache.org/xml/ns/security-1.0"

+ +

Geronimo M5 and earlier versions do not support concepts of the DomainPrincipal and RealmPrincipal. When wrapping J2EE roles to Principals, Principal elements are wrapped by the Realm elements.

+ +

<xsd:complexType name="roleType">
+   <xsd:sequence>
+      <xsd:element name="description" type="security-1.0:descriptionType" 
+         minOccurs="0" maxOccurs="unbounded"/>
+      <xsd:element name="realm" type="security-1.0:realmType" minOccurs="0" 
+         maxOccurs="unbounded"/>
+      <xsd:element name="distinguished-name" 
+         type="security-1.0:distinguishedNameType" minOccurs="0" 
+         maxOccurs="unbounded"/>
+   </xsd:sequence>
+   <xsd:attribute name="role-name" type="xsd:string" use="required"/>
+</xsd:complexType>

+ +

<?xml version="1.0" encoding="UTF-8"?>
+<web-app
+    xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
+    xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.0"
+    configId="org/apache/geronimo/tools/JMXConsole"
+    parentId="org/apache/geronimo/Server">
+
+    <context-root>/example</context-root>
+    <context-priority-classloader>false</context-priority-classloader>
+
+    <security-realm-name>geronimo-properties-realm</security-realm-name>
+    <sec:security>
+        <sec:default-principal realm-name="geronimo-properties-realm">
+            <sec:principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"/>
+        </sec:default-principal>
+        <sec:role-mappings>
+            <sec:role role-name="admin">
+                <sec:realm realm-name="geronimo-properties-realm">
+                    <sec:principal class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
+                        name="admin" designated-run-as="true"/>
+                </sec:realm>
+            </sec:role>
+        </sec:role-mappings>
+    </sec:security>
+</web-app>

+ + +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Mapping J2EE Roles in M5 release.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Mapping J2EE Roles in M5 release.html ------------------------------------------------------------------------------ svn:executable = * Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Migrating to Apache Geronimo.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Migrating%20to%20Apache%20Geronimo.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Migrating to Apache Geronimo.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Migrating to Apache Geronimo.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,60 @@ + + + Geronimo : Migrating to Apache Geronimo + + + + + + + + + +

+ + Geronimo : Migrating to Apache Geronimo + +

+ This page last changed on Nov 16, 2005 by hcunico@gmail.com. +

+ + +

+ +

Article donated by: Hernan Cunico

+ +

Migrating to Apache Geronimo

The following are a series of articles to assist you to migrate applications from JBoss v4 to Apache Geronimo. At the time of writing these articles JBoss v4.0.2 and Apache Geronimo M5 was used.

+ +

There are several articles focusing on different features/functionalities of the J2EE specification. All these articles are self contained and fully independent from each other. They provide feature-to-feature comparison analysis between the differences in the implementation from JBoss to Apache Geronimo, this will particularly help you when doing the migration planning.

+ +

Additionally, each article provides a sample application for you to practice and gain experience migrating from one platform to another. All these articles have the same internal structure so it will be easier for you to find similar information about different topics across the articles.

+ +

Available articles:

+ + + +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Migrating to Apache Geronimo.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Migrating to Apache Geronimo.html ------------------------------------------------------------------------------ svn:executable = * Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Performance and high availability.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Performance%20and%20high%20availability.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Performance and high availability.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Performance and high availability.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,44 @@ + + + Geronimo : Performance and high availability + + + + + + + + + +

+ + Geronimo : Performance and high availability + +

+ This page last changed on Nov 21, 2005 by hcunico@gmail.com. +

+ + +

+ +

Article donated by: Hernan Cunico

+ +

Here is a document with performance analysis on Geronimo M5 using DayTrader, Geronimo_Performance_BaseLine-20051007.pdf

+ +

Scalability

Clustering

+ + +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Performance and high availability.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Performance and high availability.html ------------------------------------------------------------------------------ svn:executable = * Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick%20start%20-%20Apache%20Geronimo%20for%20the%20impatient.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,207 @@ + + + Geronimo : Quick start - Apache Geronimo for the impatient + + + + + + + + + +

+ + Geronimo : Quick start - Apache Geronimo for the impatient + +

+ This page last changed on Dec 09, 2005 by system. +

+ +

+Article donated by: Hernan Cunico

+ +

If you are in a hurry to have Apache Geronimo up and running right away, this article will provide you with some basic steps for downloading, building (when needed) and run the server in no time. This is clearly not a complete guide so you may want to check the other links in the Apache Geronimo V1 \- Documentation Draft main section for further information.

+ +

All you need is 5 to 10 minutes and to follow these basic steps.

Getting the software
Start the server
Create and deploy a sample application

+ + +

Getting the software

At this time you have mainly two options to get the software. You can either download the latest, and stable, major milestone (namely M4, M5...) or get the latest available build (unstable sometimes). The fastest and easiest way is to get the binary directly from the Apache site. Since this article is intended to help you to have Apache Geronimo up and running in the fastest way only the binary download will be covered at this time.

+ +

Prerequisites

Although this installation path is the fastest one, still you will need to install some software before installing Geronimo.

+ +

J2SE 1.4.2

Geronimo is currently using the Sun ORB for RMI so it is required to use SUN JDK. Using a different JDK or different version of the JDK may result in compilation errors. Refer to the following URL for details on how to download and install J2SE 1.4.2:
+http://java.sun.com

+ +

Download binaries

Depending on the platform you plan to install and run Apache Geronimo you will select the appropriate installation image. Open a Web browser and access the following URL, there you will find the available packages for download (binaries and source code).

+ +

http://geronimo.apache.org/downloads.html

+ +

Select the file compression format compatible with your system (zip, tar, gz) by clicking directly on the link, download it and expand the binary to your hard drive in a new directory. For example in z:/geronimo, from now on this directory will be referenced as <geronimo_home>.

+ +

The installation of Apache Geronimo is as simple as uncompressing the .zip or .tar files. The next step is to start the server.

+ +

Start the server

With Apache Geronimo already installed, open a command line console and change directory to <geronimo_home>/bin. In that directory you will find some script files (.bat and .sh) and three .jar files. If you look at these three files you will find:

client.jar
deployer.jar
server.jar

+ + +

To start the server run the following command:

+ +

java -jar server.jar

+ +

Alternatively a script is provided, the startup script will also start the server. Once the server is started you should see the following information on the command line console.

+ +

 E:\geronimo\bin>java -jar server.jar
+Booting Geronimo Kernel (in Java 1.4.2_09)...
+Starting Geronimo Application Server
+[*****************] 100%  25s Startup complete
+  Listening on Ports:
+    1099 0.0.0.0 RMI Naming
+    1527 0.0.0.0 Derby Connector
+    4201 0.0.0.0 ActiveIO Connector EJB
+    4242 0.0.0.0 Remote Login Listener
+    8019 0.0.0.0 Tomcat Connector AJP
+    8080 0.0.0.0 Jetty Connector HTTP
+    8090 0.0.0.0 Tomcat Connector HTTP
+    8443 0.0.0.0 Jetty Connector HTTPS
+    8453 0.0.0.0 Tomcat Connector HTTPS
+   61616 0.0.0.0 ActiveMQ Message Broker Connector
+  Started Application Modules:
+    EAR: org/apache/geronimo/Console/Jetty
+    WAR: org/apache/geronimo/applications/Welcome/Jetty
+  Web Applications:
+    http://hcunico:8080/
+    http://hcunico:8080/console
+    http://hcunico:8080/console-standard
+Geronimo Application Server started

+ +

To test the Apache Geronimo server you can just point your Web browser to the following URL to test the Geronimo Console. The Geronimo Console is the first application you can test, and the good thing is, it is already deployed.

+ +

http://localhost:8080/console

+ +

When prompted enter system as the user name and manager as the password.

+ +

The following figure illustrates the Web based console.

+ +

At this point you have Apache Geronimo up and running and the time spent has been minimal. The following section will propose a very basic sample JSP and show you how to deploy and run that sample application.

+ +

Create and deploy a sample application

A HelloWorld like JSP is almost a default for these basic testing and everybody is already familiar with it. Create a new directory to hold all the application related files. From now on this directory will be referred as <app_home>.

+ +

Create a plain text file in the <app_home> directory named HelloWorld.jsp and copy the content of the following example.

+ +

HelloWorld.jsp

<html>
+  <head>
+    <jsp:useBean id="datetime" class="java.util.Date"/>
+    <title>
+      Basic HelloWorld JSP
+    </title>
+  </head>
+  <body bgcolor="#909DB8">
+    <h1>
+      <font face="tahoma" color="white">
+        Hello world from GERONIMO!
+      </font>
+    </h1>
+    <font face="tahoma" color="white">on ${datetime}</font>
+  </body>
+</html>

+ +

Although for such a simple application it is not necessary, you will still create a Geronimo deployment plan so you would get a first view of the deployment plans. Create a directory named WEB-INF inside the <app_home> directory.

+ +

Create a plain text file in the <app_home>/WEB-INF directory named geronimo-web.xml and copy the content of the following example.

+ +

Geronimo deployment plan geronimo-web.xml

<?xml version="1.0"?>
+<web-app 
+   xmlns="http://geronimo.apache.org/xml/ns/web" 
+   xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
+   configId="HelloWorld">
+
+   <context-root>/hello</context-root>
+
+</web-app>

+ +

Create a plain text file in the <app_home>/WEB-INF directory named web.xml and copy the content of the following example.

+ +

web.xml

<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
+   <welcome-file-list>
+      <welcome-file>HelloWorld.jsp</welcome-file>
+   </welcome-file-list>
+</web-app>

+ +

Package the application

+ +

From a command line window change directory to <app_home> and run the following command to package the HelloWorld application into a single .war file.

+ +

jar -cvf HelloWorld.war *

+ +

This will create a HelloWorld.war file in the <app_home> directory. The next step is to deploy this application.

+ +

Deploy and test the application

To deploy the application you have two options, you can use the Geronimo Console or the command line. For this example you will use the command line option. Change directory to <geronimo_home>/bin and run the following command:

+ +

java -jar deployer.jar --user system --password manager deploy <app_home>/HelloWorld.war

+ +

Once the application is successfully deployed you should see the following message:

+ +

 
+E:\geronimo\bin>java -jar deployer.jar --user system --password manager deploy E:\HelloWorld\HelloWorld.war
+    Deployed HelloWorld @ http://hcunico:8080/hello

+ +

Test the application by pointing a Web browser to the following URL:

+ +

http://localhost:8080/hello

+ +

Summary

This article showed you how simple is to have Apache Geronimo up and running. The overall time for getting the server running should be less than five minutes if you have the prerequisite (Java 1.4.2) already installed. Additionally, this article also showed you how to create, deploy and test a very simple JSP in less than five minutes.

+ +
+

+ Attachments: +

+ +

+ console_login.jpg (image/pjpeg) +
+

+ +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient.html ------------------------------------------------------------------------------ svn:executable = * Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient_attachments/console_login.jpg URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick%20start%20-%20Apache%20Geronimo%20for%20the%20impatient_attachments/console_login.jpg?rev=356160&view=auto ============================================================================== Binary file - no diff available. Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient_attachments/console_login.jpg ------------------------------------------------------------------------------ svn:executable = * Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Quick start - Apache Geronimo for the impatient_attachments/console_login.jpg ------------------------------------------------------------------------------ svn:mime-type = image/jpeg Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Security Definition Schema.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Security%20Definition%20Schema.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Security Definition Schema.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Security Definition Schema.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,273 @@ + + + Geronimo : Security Definition Schema + + + + + + + + + +

+ + Geronimo : Security Definition Schema + +

+ This page last changed on Nov 18, 2005 by hcunico@gmail.com. +

+ + +

+ +

Article donated by: Simon Godik, Hernan Cunico

+ +

Security schema is the main syntax for the security-related definitions of any deployment plan. Security schema is normally imported by the host schema.
+Security schema namespace is: http://geronimo.apache.org/xml/ns/security-1.1 Security schema file is geronimo-security-1.1.xsd.

+ +

The usual namespace prefix for the security schema is security. So if you want to refer to the elements of this namespace from some other namespace, you will do it this way: security:security.

+ +

Here is the syntactic reference for the security schema. All security schema types are global (in the xml schema sense). There are only two global security elements: security:security and security:defaultPrincipal.

+ +

Note that although default-principal is declared to be a global element, security schema does not make use of it and defines local default-principal element of the same type every time it needs it.

+ +

The following sections describe the syntax and meaning of the security schema element.

+ +

It has been used simple x-path path expressions such as /a/b/c and attribute expressions such as @attribute as a short-hand.

+ +

Type securityType

security:securityType is the global type that defines security requirements of an application with respect to the J2EE role mapping to Principals.

+ +

<xsd:complexType name="securityType">
+   <xsd:sequence>
+      <xsd:element name="description" type="security:descriptionType" 
+         minOccurs="0" maxOccurs="unbounded"/>
+      <xsd:element name="default-principal" type="security:default-principalType"/>
+      <xsd:element name="role-mappings" type="security:role-mappingsType" 
+         minOccurs="0"/>
+   </xsd:sequence>
+   <xsd:attribute name="doas-current-caller" type="xsd:boolean" default="false"/>
+   <xsd:attribute name="use-context-handler" type="xsd:boolean" default="false"/>
+   <xsd:attribute name="default-role" type="xsd:string"/>
+</xsd:complexType>

+ +

@doas-current-caller - Set this attribute to true if the work is to be performed as the calling Subject. This attribute is optional, the default value is false.
+@use-context-handler - Set this attribute to true if the installed JACC policy contexts will use PolicyContextHandlers. This attribute is optional, the default value is false.
+@default-role - Used by the Deployer to assign method permissions for all of the unspecified methods, either by assigning them to security roles or by marking them as unchecked. If the value of default-role is empty then the unspecified methods are marked unchecked.

+ +

description - optional element. 0 to many description elements.
+default-principal - required element. Defines default principal for anonymous access.
+role-mappings - optional element. Maps J2EE roles to principals.

+ +

Type defaultPrincipalType

Default principal is used for anonymous access.

+ +

security:default-principalType is a sequence of optional description, the choice of principal, login-domain-principal, realm-principal, followed by a sequence of
+named-username-password-credential elements.

+ +

<xsd:complexType name="default-principalType">
+   <xsd:sequence>
+      <xsd:element name="description" type="security:descriptionType" 
+         minOccurs="0" maxOccurs="unbounded"/>
+      <xsd:choice>
+         <xsd:element name="principal" type="security:principalType"/>
+         <xsd:element name="login-domain-principal" 
+            type="security:loginDomainPrincipalType"/>
+         <xsd:element name="realm-principal" type="security:realmPrincipalType"/>
+      </xsd:choice>
+      <xsd:element name="named-username-password-credential" 
+         type="security:named-username-password-credentialType" minOccurs="0" 
+            maxOccurs="unbounded"/>
+   </xsd:sequence>
+</xsd:complexType>

+ +

description - optional. 0 to many description elements.
+principal - required choice element. Defines default principal to be of the security:princpalType.
+login-domain-principal - required choice element. Defines default principal to be of the security:loginDomainPrincipalType.
+realm-principal - required choice element. Defines default principal to be of the security:realmPrincipalType.
+named-username-password-credential - optional sequence of 0 to many elements of the security:named-username-password-credentialType.

+ +

Type principalType

security:principalType defines authenticated principal.

+ +

<xsd:complexType name="principalType">
+   <xsd:sequence>
+      <xsd:element name="description" type="geronimo:descriptionType" 
+         minOccurs="0" maxOccurs="unbounded"/>
+   </xsd:sequence>
+   <xsd:attribute name="class" type="xsd:string" use="required"/>
+   <xsd:attribute name="name" type="xsd:string" use="required"/>
+   <xsd:attribute name="designated-run-as" type="xsd:boolean" default="false"/>
+</xsd:complexType>

+ +

@class is principal implementation class.
+@name is authenticated principal name.
+@designated-run-as if set to true makes this principal a run-as principal for the role that maps this principal.

+ +

Type loginDomainPrincipalType

security:loginDomainPrincipalType type associates a Principal with the Login Domain that authenticated that principal. If Security Realm into which login module (Login Domain) is wired up is configured to wrap Principals, every Principal produced by every login module will be wrapped into the DomainPrincipal.

+ +

<xsd:complexType name="loginDomainPrincipalType">
+   <xsd:complexContent>
+      <xsd:extension base="security:principalType">
+         <xsd:attribute name="domain-name" type="xsd:string" use="required"/>
+      </xsd:extension>
+   </xsd:complexContent>
+</xsd:complexType>

+ +

@domain-name - Login Domain name.

+ +

Note that elements of the security:loginDomainPrincipalType wrap elements of security:principalType, so the @class attribute value must be the value of the Principal implementation class that is wrapped by the security:loginDomainPrincipal.

+ +

Type realmPrincipalType

Realm principal associates a Principal with the realm in which it was authenticated. If Security Realm is configured to wrap Principals, each DomainPrincipal will be wrapped into the RealmPrincipal.

+ +

realmPrincipalType extends security:loginDomainPrincipalType.

+ +

<xsd:complexType name="realmPrincipalType">
+   <xsd:complexContent>
+      <xsd:extension base="security:loginDomainPrincipalType">
+         <xsd:attribute name="realm-name" type="xsd:string" use="required"/>
+      </xsd:extension>
+   </xsd:complexContent>
+</xsd:complexType>

+ +

@realm-name is required attribute that defines realm name.

+ +

Note that elements of security:realmPrincipalType wrap elements of security:principalType, that wrap elements of security:loginDomainPrincipalType. So the @class attribute value must be the value of the Principal implementation class that is wrapped by the security:loginDomainPrincipal.

+ +

Type named-username-password-credentialType

This element defines username - password credential.

+ +

<xsd:complexType name="named-username-password-credentialType">
+   <xsd:sequence>
+      <xsd:element name="name" type="xsd:string"/>
+      <xsd:element name="username" type="xsd:string"/>
+      <xsd:element name="password" type="xsd:string"/>
+   </xsd:sequence>
+</xsd:complexType>

+ +

name - required element. Names this credential set.
+username - required element. User name.
+password - required element. User password.

+ +

Type role-mappingsType

security:role-mappingsType defines mappings of J2EE roles to principals.

+ +

<xsd:complexType name="role-mappingsType">
+ <xsd:sequence>
+ <xsd:element name="role" type="security:roleType" minOccurs="1"
+ maxOccurs="unbounded"/>
+ </xsd:sequence>
+</xsd:complexType>

+ +

role - required sequence of 1 or more elements of security:roleType.

+ +

Type roleType

security:roleType element defines J2EE role mapping to a set of Principals. Mapped principals can be any kind of principal: domain-principal, realm-principal, principal, or a distinguished name (dn).

+ +

Note that ideally we want to map to DomainPrincipals or RealmPrincipals. This type of mapping is not supported in Geronimo M5 or earlier milestones. The only type of mapping in M5 and before is principalType mapping and dn mapping.

+ +

<xsd:complexType name="roleType">
+   <xsd:sequence>
+      <xsd:element name="description" type="security:descriptionType" minOccurs="0" maxOccurs="unbounded"/>
+      <xsd:element name="realm-principal" type="security:realmPrincipalType" minOccurs="0" maxOccurs="unbounded"/>
+      <xsd:element name="login-domain-principal" 
+         type="security:loginDomainPrincipalType" minOccurs="0" maxOccurs="unbounded"/>
+      <xsd:element name="principal" type="security:principalType" minOccurs="0" maxOccurs="unbounded"/>
+      <xsd:element name="distinguished-name" 
+         type="security:distinguishedNameType" minOccurs="0" maxOccurs="unbounded"/>
+   </xsd:sequence>
+   <xsd:attribute name="role-name" type="xsd:string" use="required"/>
+</xsd:complexType>

+ +

@role-name - J2EE role name. This is required attribute.

+ +

description - optional sequence from 0 to many security:description elements.
+realm-principal - optional sequence from 0 to many security:realmPrincipalType elements. Not supported for Geronimo M5 or earlier milestones.
+login-domain-principal - optional sequence from 0 to many security:loginDomainPrincipal type elements. Not supported for Geronimo M5 or earlier milestones.
+principal - optinal sequence from 0 to many security:principalType elements.
+distinguished-name - optional sequence of security:distinguishedNameType elements.

+ +

Type distinguishedNameType

<xsd:complexType name="distinguishedNameType">
+   <xsd:sequence>
+      <xsd:element name="description" type="security:descriptionType" 
+         minOccurs="0" maxOccurs="unbounded"/>
+   </xsd:sequence>
+   <xsd:attribute name="name" type="xsd:string" use="required"/>
+   <xsd:attribute name="designated-run-as" type="xsd:boolean" default="false"/>
+</xsd:complexType>

+ +

@designated-run-as - Set this attribute to true if this principal is to be used as the run-as principal for this role. This is optional attribute, default value is false.

+ +

desciption - optional sequence from 0 to many elements of security:descriptionType.

+ +

Type descriptionType

security:descriptionType element allows description to be inserted in any other element. This type extends schema string type with the reference to the global xml:lang attribute.

+ +

<xsd:complexType name="descriptionType">
+   <xsd:simpleContent>
+      <xsd:extension base="xsd:string">
+         <xsd:attribute ref="xml:lang"/>
+      </xsd:extension>
+   </xsd:simpleContent>
+</xsd:complexType>

+ +

@xml:lang - language attribute. This attribute is optional.

+ +

+ + +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Security Definition Schema.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Security Definition Schema.html ------------------------------------------------------------------------------ svn:executable = * Added: geronimo/branches/1.0/modules/scripts/src/resources/docs/Security.html URL: http://svn.apache.org/viewcvs/geronimo/branches/1.0/modules/scripts/src/resources/docs/Security.html?rev=356160&view=auto ============================================================================== --- geronimo/branches/1.0/modules/scripts/src/resources/docs/Security.html (added) +++ geronimo/branches/1.0/modules/scripts/src/resources/docs/Security.html Sun Dec 11 21:27:20 2005 @@ -0,0 +1,125 @@ + + + Geronimo : Security + + + + + + + + + +

+ + Geronimo : Security + +

+ This page last changed on Nov 29, 2005 by hcunico@gmail.com. +

+ + +

+ +

Article donated by: Simon Godik, Hernan Cunico

+ +

The following are a series of articles that will help you understand better security and how those comcepts are implemented in Apache Geronimo.

+ +

Concepts +
- Login Domain
- Security Realm
- Authentication and Principals
+
Login into Geronimo +
- Login Service API
- Login into Geronimo the portable way: JaasLoginCoordinator
+
Geronimo and JAAS +
- Integrating Geronimo security with the JAAS API
- ConfigurationEntryFactory implementations
+
JaasLoginService API Discussion
Component Configuration +
+
Authorization \- mapping J2EE roles to Principals
Security Definition Schema +
+
Geronimo Login Config Schema +
+
Deploying secure applications +
+
Available login modules +
- PropertiesFileLoginModule
- LDAPLoginModule
- SQLLoginModule
- CertificateChainLoginModule
- CertificatePropertiesFileLoginModule
- FileAuditLoginModule +
  - Configuring LDAP
  +
+
Mapping J2EE Roles in M5 release
Configuring SSL

+ + + +

+ + + + + + + +

Document generated by Confluence on Dec 09, 2005 22:10

+ + \ No newline at end of file Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Security.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: geronimo/branches/1.0/modules/scripts/src/resources/docs/Security.html ------------------------------------------------------------------------------ svn:executable = *