This page talks about how to use the security realm ${realm.name} from a J2EE application. The example here is a web application, but other application modules would work similarly.

WEB-INF/web.xml

The web.xml should have

• One or more security-constraint blocks designating the protected pages or URLs
• A login-config section configuring the login style for the application
• One or more security-role blocks listing the security roles used by the application

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4">

  <!--  servlets and mappings and normal web.xml stuff here -->

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Protected</web-resource-name>
            <url-pattern>/protected/*</url-pattern>
            <http-method>GET</http-method>
            <http-method>POST</http-method>
        </web-resource-collection>
        <auth-constraint>
            <role-name>admin</role-name>
        </auth-constraint>
    </security-constraint>
    <login-config>
        <auth-method>FORM</auth-method>
        <realm-name>This is not used for FORM login</realm-name>
        <form-login-config>
            <form-login-page>/login.jsp</form-login-page>
            <form-error-page>/loginerror.jsp</form-error-page>
      </form-login-config>
    </login-config>
    <security-role>
        <role-name>admin</role-name>
    </security-role>
</web-app>

WEB-INF/geronimo-web.xml

To configure the security realm and the members of each role, the web application needs to have a geronimo-web.xml deployment plan. That may be packaged in the WAR in the WEB-INF directory, or it may be provided separately on the command line to the deploy tool.

The geronimo-web.xml plan should have a security-realm-name element indicating which realm will be used to authenticate logins to the web application. It also needs to have a security element listing the users or groups who should be members of each security-role listed in web.xml.

<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1">
    <environment>
        <moduleId>
            <artifactId>MyWebApp</artifactId>
        </moduleId>
    </environment>

    <context-root>/MyWebApp</context-root>

    <security-realm-name>${realm.name}</security-realm-name>
    <security>
        <default-principal>
            <principal name="anonymous"
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
            />
        </default-principal>
        <role-mappings>
            <role role-name="admin">
                <principal name="administrators" designated-run-as="true"
class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
                />
                <principal name="root"
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
                />
            </role>
        </role-mappings>
    </security>
</web-app>

This example indicated that ${realm.name} will be used to handle all logins to the web application. Then it maps the admin role to a combination of one user (root) and one group (administrators), using a combination of the principal classes and principal names. (Note that if ${realm.name} uses a custom login module, the principal classes may be different, but the ones listed above are used for users and groups by all the standard Geronimo login modules.)

It's also possible to configure separate login modules to use separate login domain names, and then use the login domain names in the role mapping (so a user "root" from login domain "Foo" is different from a user "root" from login domain "Bar"), but this is only important if you have multiple login modules assigning principals to the users.

Finally, if the security section is declared in an EAR application.xml deployment descriptor, there's no need to repeat it in any of the modules inside the EAR -- they'll all share the same role mapping information.

Application Code

No special application code is required to work with security roles.

If an application calls HttpServletRequest.getUserPrincipal(), Geronimo will return a principal where the principal class implements GeronimoCallerPrincipal -- normally a username (since GeronimoUserPrincipal implements GeronimoCallerPrincipal). If you're using a custom login module and getting the wrong results for getUserPrincipal, try making your user principal class implement GeronimoCallerPrincipal.

If an application calls HttpServletRequest.isUserInRole(role), Geronimo will return true or false depending on whether any of the principals assigned to that user by the realm's login modules were listed in the role mapping above.

">Return to list