The purpose of this section is to provide some general guidelines on the application deployment process from a Security perspective. This is not intended to be the absolute guide for deployment. Throughout the articles in the Apache Geronimo V1 - Documentation, you will find several deployment examples organized by topics such as JDBC, Web services, JCA, Security, etc.

This section is organized in the following topics:

Deployment options for Web applications

Web applications can be deployed in a number of ways, standalone war file or part of an ear file. Web applications deployment can be targeted to a specific servlet container (such as jetty or tomcat) or use container-neutral schema. Note that container-neutral schema also has a way to define container-specific parameters.

If deployed as part of an ear file, there are 2 ways to include the Web application deployment plan: include it in the geronimo-application.xml as it's own module element or include a reference to the Web application deployment plan by using <alt-dd> element. The syntax of the Web application element is the same in both cases, so keep this in mind when you look at the examples.

Back to Top

Deploying Web application with the container-neutral schema

The namespace for the container neutral Web application deployment plan is http://geronimo.apache.org/xml/ns/j2ee/web-1.0. The name of the schema file is
geronimo-web-1.0.xsd. It is best if you become familiar with the schema.

When configuring security in the deployment plan you need to specify two elements, security-realm-name and security:security element.

security-realm-name element defines the name of the Security Realm for the application. security:security element defines J2EE role mappings to Principals.

Here is an example of the Web application deployment plan:

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0">
   ...
   <security-realm-name>geronimo-properties-realm</security-realm-name>
   <security:security xmlns:security=":http://geronimo.apache.org/xml/ns/security-1.1">...</security:security>
   ...
</web-app>

Back to Top

Defining Security Realm Name

Security realm name is specified by the <security-realm-name> element. Its value is passed as an input parameter to the JAAS LoginContext constructor. In JAAS terms, this is application configuration name.

Do not be misled by the name of the security-realm-name element. This name implies that you are naming the Security Realm, but in fact you may not. The value of this element is application configuration name and as such, it selects a GBean implementing ConfigurationEntryFactory interface that has this name. The most likely choice is the GenericSecurityRealm of the same name. But other GBean types are possible, such as ServerRealmConfigurationEntry or (less likely) DirectConfigurationEntry. Make sure you know what GBean you are refererring to.

You can reuse Security Realm definitions in other configurations or include your own. For example, org/apache/geronimo/Security configuration contains geronimo-properties-realm GenericSecurityRealm. If you decide to define your own GenericSecurityRealm GBean, use GBean elements that are allowed by your deployment plan schema.

Note that Geronimo JAAS configuration GBean will complain if the name of your own GenericSecurityRealm GBean is a duplicate of some other configuration entry name that is already deployed. To avoid this kind of problems, use unique Security Realm names. Refer to Component Configuration, Configuring Security Realm section for the details how to configure your own GenericSecurityRealm.

Back to Top

Example of the Web application deployment with web-container neutral schema

To better understand this example make sure you read the Component Configuration, Configuring Security Realm section before.

Note that realm-principal and domain-principal wrap an instance of the class that implements Principal interface.

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0">
   ...
   <security-realm-name>geronimo-properties-realm</security-realm-name>
   <security:security 
      xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1">

      <default-principal>
         <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"
                designated-run-as="true"/>
      </default-principal>

      <role-mappings>
         <role role-name="admin">
            <login-domain-principal domain-name="geronimo-properties-realm"
                name="admin" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"/>
         </role>
      </role-mappings>
   </security:security>
   ...
</web-app>

This example defines principal as the default principal for the application and mapped J2EE admin role to the login-domain-principal named admin that wraps the org.apache.geronimo.securityrealm.providers.GeronimoGroupPrincipal class. In other words we maped J2EE admin role to the admin group from the
geronimo-login-domain Login Domain.

In the example above, the Security Realm is presumed to be deployed elsewhere. For example org/apache/geronimo/Security configuration deploys geronimo-properties-realm: geronimo.server:J2EEApplication=null,J2EEModule=org/apache/geronimo/Security,J2EEServer=geronimo,j2eeType=SecurityRealm,name=geronimo-properties-realm

Back to Top

Deploying Web application on Jetty container

Jetty container deployment plan namespace is http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.0
As far as security configuration is concerned it allows the same structure as the container-neutral schema:

<xs:schema targetNamespace="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.0"  
	xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1">
	<xs:complexType name="web-appType">
	....
		<xs:sequence minOccurs="0">
    			<xs:element name="security-realm-name" type="xs:string"/>
    			<xs:element ref="security:security" minOccurs="0"/>
		</xs:sequence>
	...
	</xs:complexType>
</xs:schema>

And security definition will be the same as in the container-neutral schema.

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.0">
   ...
   <security-realm-name>geronimo-properties-realm</security-realm-name>
   <security:security 
      xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1">

      <default-principal>
         <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"
                designated-run-as="true"/>
      </default-principal>

      <role-mappings>
         <role role-name="admin">
            <login-domain-principal domain-name="geronimo-properties-realm"
                name="admin" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"/>
         </role>
      </role-mappings>
   </security:security>
   ...
</web-app>

Back to Top

Deploying Web application on Tomcat container

Tomcat container deployment plan namespace is http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.0.
As far as security configuration is concerned it allows the same structure as container-neutral schema:

<xs:schema targetNamespace="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.0"
	xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1">
	<xs:complexType name="web-appType">
	....
		<xs:sequence minOccurs="0">
    			<xs:element name="security-realm-name" type="xs:string"/>
    			<xs:element ref="security:security" minOccurs="0"/>
		</xs:sequence>
	...
	</xs:complexType>
</xs:schema>

And security definition will be the same as in the container-neutral schema.

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.0">
   ...
   <security-realm-name>geronimo-properties-realm</security-realm-name>
   <security:security 
      xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1">

      <default-principal>
         <principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="system"
                designated-run-as="true"/>
      </default-principal>

      <role-mappings>
         <role role-name="admin">
            <login-domain-principal domain-name="geronimo-properties-realm"
                name="admin" class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"/>
         </role>
      </role-mappings>
   </security:security>
   ...
</web-app>

Back to Top