Configuring custom security realms in WebSphere Application Server Community Edition Version 2.x

Content

A custom security realm uses a user defined LoginModule for authentication. A custom security realm can be used when you require an authentication method different from the methods provided by WebSphere Application Server Community Edition v2.x:

• PropertiesFileLoginModule
• SQLLoginModule
• LDAPLoginModule
• CertificatePropertiesFileLoginModule

• You should have user implemented Login Module and Principal classes
• You should have Artifacts - Jar file with Login Module and Principal classes.
• You should use a Realm name that is different than the name for any other security realms in the server (no spaces in the name). Server components will use this name to refer to the security realm.
• You should use a fully-qualified Login Module Class name for the login module.

• As a top-level security realm
• Security module added to the web application
• Security module added to the enterprise application

1. Upload custom login module jar to repository.
1. Open the Administrative Console.
   
   
2. Click Repository from the left frame (In version 2.0.x it is Common Libs).
   
   
3. Browse your login module jar file and give group, artifact, version, and type values. For example:
   
   
   
4. Click Install to upload your jar in to the server repository.
   
   
2. Create a custom security realm plan. The following is a sample custom-realm-plan.xml file:
   
   

<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.2">     <environment>         <moduleId>             <groupId>tutorial</groupId>             <artifactId>custom-realm</artifactId>             <version>1.0</version>             <type>car</type>         </moduleId>         <dependencies>             <dependency>                 <groupId>org.apache.geronimo.framework</groupId>                 <artifactId>j2ee-security</artifactId>                 <type>car</type>             </dependency>             <dependency>                 <groupId>tutorial</groupId>                 <artifactId>myownloginmodule</artifactId>                 <version>1.0</version>                 <type>jar</type>             </dependency>         </dependencies>     </environment>     <gbean name="custom-realm" class="org.apache.geronimo.security.realm.GenericSecurityRealm" xsi:type="dep:gbeanType" xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">         <attribute name="realmName">custom-realm</attribute>         <reference name="ServerInfo">             <name>ServerInfo</name>         </reference>         <xml-reference name="LoginModuleConfiguration">             <log:login-config xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-2.0">                 <log:login-module control-flag="REQUIRED" wrap-principals="false">                     <log:login-domain-name>custom-realm</log:login-domain-name>                     <log:login-module-class>fullyqualified  class name for the login module</log:login-module-class>                     <log:option name="ignoreCase">true</log:option>                 </log:login-module>             </log:login-config>         </xml-reference>     </gbean> </module>

3. Deploy custom-realm-plan.xml using either of the following options:
• Use the HotDeployer utility. Drop the plan under the following directory:
  
  install_root/deploy
  
  
• Command line deployment:
  
  cd install_root/bin  java -jar deployer.jar
  deploy custom-realm-plan.xml
  
  
4. Verify deployed custom security realm in the server.
1. Open the Administrative Console.
   
   
2. Go to Security Realms in the left frame.
   
   
3. Verify the name custom-realm is listed.
   
   
5. Now your Web application can use the custom login module by modifying the geronimo-web.xml. Sample plans are shown below:
   
   geronimo-web.xml
   
   

<?xml version="1.0" encoding="UTF-8"?>        <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0"         xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.2"         xmlns:security="http://geronimo.apache.org/xml/ns/security-2.0"         xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.2">          <sys:environment>              <sys:moduleId>                    <sys:groupId>tutorial</sys:groupId>                    <sys:artifactId>simple-web-application</sys:artifactId>                    <sys:version>1.0</sys:version>                    <sys:type>war</sys:type>             </sys:moduleId>             <sys:dependencies>             </sys:dependencies>             <sys:hidden-classes/>             <sys:non-overridable-classes/>        </sys:environment>        <context-root>/SimpleWebApplication</context-root>        <security-realm-name>custom-realm</security-realm-name>         <security:security>              <security:role-mappings>                <security:role role-name="admin">                <security:realm realm-name="custom-realm">                   <security:principal class="org.apache.geronimo.security.realm.providers.                                                            GeronimoUserPrincipal" name="apcadmin"/>               </security:realm>           </security:role>           <security:role role-name="guest">         <security:realm realm-name="custom-realm">           <security:principal class="org.apache.geronimo.security.realm.providers.                                                             GeronimoUserPrincipal" name="guest"/>          </security:realm>        </security:role>     </security:role-mappings>   </security:security> </web-app>

web.xml

<?xml version="1.0" encoding="UTF-8"?> <web-app id="SimpleWebApp0" version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <display-name> SimpleWebApp</display-name>      <login-config>         <auth-method>FORM</auth-method>         <realm-name>Not required for FORM auth</realm-name>         <form-login-config>         <form-login-page>/login/login.jsp</form-login-page>             <form-error-page>/login/loginerror.jsp</form-error-page>         </form-login-config>     </login-config>     <security-role><role-name>admin</role-name></security-role>     <security-role><role-name>user</role-name></security-role>     <security-constraint>         <web-resource-collection>         <web-resource-name>resname</web-resource-name>         <url-pattern>/secure/*</url-pattern>         <http-method>GET</http-method>         </web-resource-collection>    <auth-constraint>    <role-name>admin</role-name>    </auth-constraint>     </security-constraint> </web-app>

1. Place the custom login module jar under WEB-INF/lib.
   
   
2. Modify WEB-INF/geronimo-web.xml file in your Web application and add security gbean element. Below is the sample geronimo-web.xml plan:
   
   

<?xml version="1.0" encoding="UTF-8"?><web:web-app xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-2.0" xmlns:client="http://geronimo.apache.org/xml/ns/j2ee/application-client-2.0" xmlns:conn="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2" xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2" xmlns:ejb="http://openejb.apache.org/xml/ns/openejb-jar-2.2" xmlns:name="http://geronimo.apache.org/xml/ns/naming-1.2" xmlns:pers="http://java.sun.com/xml/ns/persistence" xmlns:pkgen="http://openejb.apache.org/xml/ns/pkgen-2.1" xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0" xmlns:web="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">     <dep:environment>         <dep:moduleId>             <dep:groupId>tutorial</dep:groupId>             <dep:artifactId>simple-web-appplication</dep:artifactId>             <dep:version>1.0</dep:version>             <dep:type>war</dep:type>         </dep:moduleId>         <dep:dependencies>             <dep:dependency>                 <dep:groupId>org.apache.geronimo.framework</dep:groupId>                 <dep:artifactId>j2ee-security</dep:artifactId>                 <dep:type>car</dep:type>             </dep:dependency>         </dep:dependencies>         <dep:hidden-classes/>         <dep:non-overridable-classes/>     </dep:environment>     <web:context-root>/SimpleWebApplication/web:context-root>     <web:security-realm-name>custom-realm</web:security-realm-name>     <sec:security>         <sec:role-mappings>           <sec:role role-name="testRole">            <sec:realm realm-name="custom-realm">               <sec:principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="testUser"/>            </sec:realm>           </sec:role>       </sec:role-mappings>     </sec:security>     <dep:gbean class="org.apache.geronimo.security.realm.GenericSecurityRealm" name="custom-realm">         <dep:attribute name="realmName">custom-realm</dep:attribute>         <dep:reference name="ServerInfo">             <dep:name>ServerInfo</dep:name>         </dep:reference>         <dep:xml-reference name="LoginModuleConfiguration">             <login-config:login-config xmlns:login-config="http://geronimo.apache.org/xml/ns/loginconfig-2.0">                 <login-config:login-module control-flag="REQUIRED" wrap-principals="false">                     <login-config:login-domain-name>custom-realm</login-config:login-domain-name>                     <login-config:login-module-class>fully qualified class name for the login module</login-config:login-module-class>                     <login-config:option name="ignoreCase">true</login-config:option>        </login-config:login-module>    </login-config:login-config>         </dep:xml-reference>     </dep:gbean> </web:web-app>

1. Upload custom login module jar to repository as explained in the preceding section.
   
   
2. Modify META-INF/geronimo-application.xml file in your enterprise application and add the security gbean elements.
   
   
3. Add the dependency elements to your geronimo-application.xml. It should look similar to the plan shown below:
   
   

<?xml version="1.0" encoding="UTF-8"?> <application xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-2.0"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">     <dep:moduleId>       <dep:groupId>tutorial</dep:groupId>       <dep:artifactId>JAASLoginModuleEAR</dep:artifactId>       <dep:version>1.0</dep:version>       <dep:type>ear</dep:type>     </dep:moduleId> <dep:dependencies> <dep:dependency>                 <dep:groupId>geronimo</dep:groupId>                 <dep:artifactId>j2ee-security</dep:artifactId>                 <dep:type>car</dep:type>             </dep:dependency>             <dep:dependency>                 <dep:groupId>tutorial</dep:groupId>                 <dep:artifactId>myownloginmodule</dep:artifactId>                 <dep:version>1.0</dep:version>                 <dep:type>jar</dep:type>             </dep:dependency>     </dep:dependencies>     <dep:hidden-classes/>     <dep:non-overridable-classes/>   </dep:environment>   <module>     <web>simplewebapp4.war</web> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1" xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.2" xmlns:security="http://geronimo.apache.org/xml/ns/security-2.0" xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2"> <dep:environment>    <dep:moduleId>      <dep:groupId>tutorial</dep:groupId>      <dep:artifactId>simplewebapp4</dep:artifactId>      <dep:version>1.0</dep:version>      <dep:type>war</dep:type>    </dep:moduleId>    <dep:dependencies/> </dep:environment>  <context-root>/JAASLoginModuleEAR</context-root>         <security-realm-name>custom-realm</security-realm-name> </web-app>   </module>   <security:security>     <security:role-mappings>       <security:role role-name="admin">         <security:realm realm-name="custom-realm">           <security:principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="apcadmin"/>         </security:realm>       </security:role>       <security:role role-name="guest">         <security:realm realm-name="custom-realm">           <security:principal class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal" name="guest"/>         </security:realm>       </security:role>     </security:role-mappings>   </security:security>     <dep:gbean class="org.apache.geronimo.security.realm.GenericSecurityRealm" name="custom-realm">         <dep:attribute name="realmName">custom-realm</dep:attribute>         <dep:reference name="ServerInfo">             <dep:name>ServerInfo</dep:name>         </dep:reference>         <dep:xml-reference name="LoginModuleConfiguration">             <login-config:login-config xmlns:login-config="http://geronimo.apache.org/xml/ns/loginconfig-2.0">                 <login-config:login-module control-flag="REQUIRED" wrap-principals="false">                     <login-config:login-domain-name>custom-realm</login-config:login-domain-name>                     <login-config:login-module-class>fully qualified class name for the login module</login-config:login-module-class>                     <login-config:option name="ignoreCase">true</login-config:option>        </login-config:login-module>    </login-config:login-config>         </dep:xml-reference>     </dep:gbean> </application>

• Control Flag: The control flag for the login module, which controls what happens to the overall login processing if this login module succeeds or fails. See the Class javax.security.auth.login.Configuration for more details.
  
  
• Server-Side: Server-side login modules are run within the application server (this is normally correct). Client-side login modules are run in the client's environment, for example, in order to use single sign-on features of the client operating system.
  
  
• In the preceding example, the login module uses an option called "ignoreCase". This option ignores the case sensitivity of your authentication entries.