9.3. Deploying a Security Realm

9.3. Deploying a Security Realm
	Chapter 9. Security Configuration [DRAFT (1.0-pre)]

A security realm may be deployed directly to the server (available to any application), or as part of a single application. Both styles use the same configuration syntax discussed previously; the difference is which file you put that information in.

9.3.1. Server-Wide Security Realms

To deploy a security realm to the server, you need to create a Geronimo deployment plan for the security realm GBean. This is just a thin wrapper around the GBean configuration. You can save this with any file name you like.

Example 9.5. Server-Wide Security Realm Deployment Plan

realm-plan.xml

<configuration
    xmlns="http://geronimo.apache.org/xml/ns/deployment"
    configId="MySecurityRealm"
    parentId="geronimo/j2ee-server/1.0/car">

<!-- standard realm GBean configuration -->
<gbean name="some-properties-file-realm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
  <attribute name="realmName">
    some-properties-file-realm
  </attribute>
  <reference name="ServerInfo">
    <application>null</application>
    <module>geronimo/j2ee-system/1.0/car</module>
    <name>ServerInfo</name>
  </reference>
  <xml-reference name="LoginModuleConfiguration">
    <login-config
           xmlns="http://geronimo.apache.org/xml/ns/loginconfig">
      <login-module control-flag="REQUIRED"
                       server-side="true">
        <login-domain-name>
          some-properties-file-login
        </login-domain-name>
        <login-module-class>
          org.apache.geronimo.security.realm.providers.
                                       PropertiesFileLoginModule
        </login-module-class>
        <option name="usersURI">
          var/security/some_users.properties
        </option>
        <option name="groupsURI">
          var/security/some_groups.properties
        </option>
      </login-module>
    </login-config>
  </xml-reference>
</gbean>

</configuration>

The new elements here are:

configuration: The parent element for a deployment plan that contains only GBeans (as opposed to application modules)
configuration:xmlns: Should always be set to http://geronimo.apache.org/xml/ns/deployment
configuration:configId: A unique name for this configuration. This can be passed on the server command line to activate this security realm when the server starts.
configuration:parentId: Identifies the parent configuration for this security realm (the value specified here should match the configId for that module). This should generally be set to geronimo/j2ee-server/1.0/car, since that configuration has the code for all the security realm classes and interfaces on its ClassPath, though it might be set to another sub-configuration of that to set up a chain of dependent configurations.

9.3.1.1. Deploying A Server-Wide Security Realm

To deploy a security realm, you can use the deploy tool and pass it the security realm deployment plan:

java -jar bin/deployer.jar deploy realm-plan.xml

That will install and start the realm (assuming the server is already running). For more information on the deploy tool, see Section 10.4, “The Deploy Tool”.

9.3.2. Application-Scoped Security Realms

Instead of deploying the security realm as a top-level service, you can deploy it within on application (or module). In this case, you'll add the security realm configuration information to the Geronimo deployment plan for the application (or module). For all the details on the structure of application deployment plans, see Part III, “J2EE Applications on Geronimo”. For example, including a realm in an application would look like this:

Example 9.6. Application-Scoped Security Realm Deployment Plan

META-INF/geronimo-application.xml

<application
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/application"
    configId="MyApplication"
    parentId="geronimo/j2ee-server/1.0/car">

<!-- standard Realm GBean configuration -->
<gbean name="some-properties-file-realm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
  <attribute name="realmName">
    some-properties-file-realm
  </attribute>
  <reference name="ServerInfo">
    <application>null</application>
    <module>geronimo/j2ee-system/1.0/car</module>
    <name>ServerInfo</name>
  </reference>
  <xml-reference name="LoginModuleConfiguration">
    <login-config
           xmlns="http://geronimo.apache.org/xml/ns/loginconfig">
      <login-module control-flag="REQUIRED"
                       server-side="true">
        <login-domain-name>
          some-properties-file-login
        </login-domain-name>
        <login-module-class>
          org.apache.geronimo.security.realm.providers.
                                       PropertiesFileLoginModule
        </login-module-class>
        <option name="usersURI">
          var/security/some_users.properties
        </option>
        <option name="groupsURI">
          var/security/some_groups.properties
        </option>
      </login-module>
    </login-config>
  </xml-reference>
</gbean>

</application>

Note that the parentId for the application should be geronimo/j2ee-server/1.0/car (or it should at least be one of the ultimate parents in the hierarchy), since that's where the security realm classes and interfaces live.

9.3.2.1. Deploying an Application-Scoped Security Realm

To deploy the security realm, just deploy the application like normal, and the realm will be deployed and started when the application is deployed and started. No extra steps are necessary.


9.2. Security Realm Configuration		9.4. Enabling Security for Applications