Custom Realm for SJSAS 9.x using JAAS documentation too vague

Question

Hello there,
I am trying to implement a custom realm for a particular web application on my SJSAS 9.x server. So far I have been unsuccessful and receive the following message in my server.log:
[#|2006-10-20T13:51:56.390-0300|INFO|sun-appserver-pe9.0|javax.enterprise.system.core.security|_ThreadID=11;_ThreadName=httpWorkerThread-8080-1;javious;|SEC5046: Audit: Authentication refused for [javious].|#]
The documentation I have been using for reference is at:
http://docs.sun.com/app/docs/doc/819-3659/6n5s6m58k?a=view#beabs
However, I have a number of questions.
First of all, this section referenced by the URL above is identified as "Creating a custom realm". Then the second sentence of this section states "Note that client-side JAAS login modules are not suitable for use with the Application Server". Does this not mean that JAAS login modules are not suitable for use with SJSAS web applications since they are components of the Application Server? Is there a reason for providing information on creating a custom realm for this application server in which it is not suitable for? Why isn't it suitable for the application server? What if I want to implement my own realm for my web application so that I can maintain my application users separately in another application?
Secondly, this section explains that I can create a custom realm simply by creating a custom JAAS login module and a custom realm class. It then goes on to explain how to construct these classes and what to include in them. Notably, the documentation states the following:
The authenticateUser() method must end with the following sequence:
String[] grpList;
// populate grpList with the set of groups to which
// _username belongs in this realm, if any
return commitUserAuthentication(_username, _password,
  _currentRealm, grpList);Having looked at the API for authenticateUser I discovered that it is a void method, however the documentation states to return a value from "commitUserAuthentication(..). Also, my commitUserAuthentication method only excepts a single argument of type String[] representing a list of group names, therefore I am unable to supply the additional arguments as documented. This is confusing.
Once finished reading the documentation, I am left hanging with hardly a clue as to what to do with these two new classes. Now having implemented a custom login module on Tomcat 5.x in earlier days, I did happen to have some experience to know to edit the security.properties, policy, and login.conf files. So anyhow from here I end up stumbling blindly through configuration of my domain1/login.conf and domain1/server.policy files. I also attempted to add my new realm within the admin console under security/realms and dropped my new jar file (with two classes) into the app server lib directory.
All in all, this completely fails to work. I have even placed System.out.println statements in all of my implemented methods and none of this actually shows up in my server.log file. Why is this section so vague? Why isn't there a step-by-step example from start to finish of how to implement a simple custom realm in SJSAS9?
Does anybody have any helpful suggestions?

Answer 1

Well, once again, I'm going to have to provide my own answer.
After much waiting and then deciding to invest much time researching documentation and tracking down information to assist in my solution, I have manage to find the golden egg for my own recipe of a solution.
In addition to the very helpful info I have found at:
http://developers.sun.com/prodtech/appserver/reference/techart/as8_authentication/index.html
I have mange to get my custom realm to work with the additional configuration of my sun-application.xml for my ear file. Even though I only wanted to specify my custom realm for my web.xml file, it turns out that in addition to this, I had to also define it in my sun-application.xml file (manually in XML text mode - within Netbeans 5.5) as follows:
<sun-application>
    <realm>mycustrealm</realm>
    <security-role-mapping>
        <role-name>mycust_role</role-name>
        <group-name>mycust_group</group-name>
    </security-role-mapping>
</sun-application>