Glassfish Custom Login Module and Realm Configuration

I wanted to create a custom login module and realm for Glassfish to implement a new authentication and authorization. I have taken the sun document but I "missed" - in fact parts of the info was there but hidden very well - some information and decided to share those here. I am focusing only on the missing parts. Rest is written in the document.

The first thing is point 3. To me it did not work to place class files into directory appserver-domain-dir/lib/classes. I created a jar file from my classes and put that into glassfish/lib and it worked after a server restart.

The next info what I missed is what jaas-context-name should be in login.conf and how it works later. So the jaas-context-name can be anything you want BUT you have to pass it to your Realm module as a parameter. Lets say you call you jaas-context-name as "customRealm".
So you have in login.conf:

customRealm{
org.CustomLogin required;
}


Then when you create your realm via the gui or any other way you must specify this as a parameter of the realm. The name of the parameter MUST BE jaas-context. To be precise it depends on the code. With the given code this is true. Otherwise depends on the following two lines:

       String jaasCtx = props.getProperty(IASRealm.JAAS_CONTEXT_PARAM);
     this.setProperty(IASRealm.JAAS_CONTEXT_PARAM, jaasCtx); 

And JAAS_CONTEXT_PARAM inherited from super has a value "jaas-context".


Now you have a mapping between realm and login module.

But how to use the realm from NetBeans?
If you create a Web Application or Enterprise application the web part has a web.xml and a sun-web.xml file in the "Configuration Files" directory. Open web.xml and select security part. Here open the Login Configuration and if you select Basic the Realm Name: must be the name of the realm created before. This is not the jaas-context name. You have to create security roles and security constraints what I will explain later.
So now you have a realm which is using basic authentication and the Realm Name is set to custom-realm.
The result in web.xml is:

<login-config>
   <auth-method>BASIC</auth-method>
   <realm-name>custom-realm</realm-name>
</login-config>  

This realm has a parameter jaas-context which specifies which login module must be used.
The realm and the login module receives the user name and password typed in and returns the list of user groups to the container.
But what to return and how to specify who has rights to do what?
In the web.xml you specified you want to use a realm but under that in Netbeans you can specify which Role has access to which url via which way. You have to create security roles. This is like a group BUT this is not necessarily the group returned by the Realm Module. This is an internal application level group. If you create something like user and admin it is a good basis.
Below that you have to specify security constraints. This is where you can specify which URL is accessible to which Role in which way. Take a look and you will understand. (When you specify the url you do not have to type the application name only the path under the context. For example if you have a jsp page as server:8080/Application/faces/user/Index.jsp you have to type in only /faces/user/* and you have to miss Application.)
Here is an example constraint:

  <security-constraint>
      <display-name>Application User</display-name>
      <web-resource-collection>
          <web-resource-name>Application User Pages</web-resource-name>
          <description/>
          <url-pattern>/faces/user/*</url-pattern>
          <http-method>GET</http-method>
          <http-method>POST</http-method>
          <http-method>HEAD</http-method>
          <http-method>PUT</http-method>
          <http-method>OPTIONS</http-method>
          <http-method>TRACE</http-method>
          <http-method>DELETE</http-method>
      </web-resource-collection>
      <auth-constraint>
          <description/>
          <role-name>Application-user</role-name>
          </auth-constraint>
      <user-data-constraint>
          <description/>
          <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
      </security-constraint>

One missing thing is how to map Authentication Groups to Application Roles. If the Realm returns the same name as group as an existing role this is mapped automatically but this is not the usual case. If user is for example in Administrator group and application has an Admin role you need a mapping between these. You can specify these in sun-web.xml Open and do it. It is self evident.
<security-role-mapping>
<role-name>application-admin</role-name>
<group-name>Administrator</group-name>
</security-role-mapping>


So the whole procedure is when somebody calls your application via an url container checks if there is a security-constraint on the url and which Security Role you need to have to access it. The container also know which Realm is responsible to authenticate the users in this application. Makes the authentication and send this info to your module. The login module is taken based on the jaas-context parameter of the Realm. Your module returns list of user groups if user is authenticated. If the user is in the group which is mapped to the necessary Security Role access is granted. That is all.