9.4. Enabling Security for Applications

9.4. Enabling Security for Applications
	Chapter 9. Security Configuration [DRAFT (1.0-pre)]

Once the security realm is running, it's time to hook up individual applications and modules to use it. There are two steps to this; first, we must make sure that whenever you authenticate, you ultimately hit the new realm. Second, we must tell each application module which principals are allowed to access it.

9.4.1. Selecting the Realm to Authenticate Against

There are generally three ways for an application user to authenticate:

A J2EE application client (running in the Geronimo client container) may authenticate in order to invoke a secure resource on the server (such as an EJB)
A "plain Java" application client may authenticate in order to invoke a secure resource on the server
A web client (a user with a browser) may authenticate using the web application authentication features (basic, form-based, etc.)

Selecting a realm for the first two (application client) scenarios is addressed in Chapter 14, Client Applications (Client JARs) [IN PROGRESS]. Selecting a realm for a web application is addressed in Section 11.4, “Web Application Login”.

9.4.2. Mapping Roles to Principals

Each J2EE application module declares the application roles it uses in its J2EE deployment descriptor (such as web.xml for web modules). To map these to principals provided by the security realm, you'll add settings to the Geronimo deployment plan for the module. For each application role, you'll list the principals that should be members of that role. The same settings are used in the deployment plan for each module type. An example is given in Example 9.7, “Role Mapping” and the full details are provided in Section 11.3.5, “Security Settings”, Section 12.3.8, “Security Settings”, and Chapter 14, Client Applications (Client JARs) [IN PROGRESS].

	Note
	The principal entries in the Geronimo deployment plan are normally identified by their principal class and principal name. Both values must match in order for the principal to successfully qualify for the application role. However, if the Support Advanced Mapping flag is enabled for the login modules in the realm, principals are also identified by their login domain name and realm name, and the security mapping process can distinguish based on those characteristics of the principal as well.

Example 9.7. Role Mapping

A web application declares a single role like this:

WEB-INF/web.xml

<web-app ...>
  <security-role>
    <role-name>NormalUser</role-name>
  </security-role>
</web-app>

In the Geronimo deployment plan, you map that to multiple principals in one of three ways. Normally, the simple mapping based on principal class (essentially, user or group) and principal name (the name of the user or group) will suffice. However, if you need to distinguish between principals in different login domains (that is, from different login modules in the same realm that happen to use the same principal classes), or between principals in different realms that use the same login domains, the more complex mapping types may be used.

WEB-INF/geronimo-web.xml using simple mapping

<web-app ...>
  <security
         xmlns="http://geronimo.apache.org/xml/ns/security-1.1">
    <role-mapping>
      <role name="NormalUser">
        <principal class="com.ldap.User" name="Aaron" />
        <principal class="com.ldap.Group" name="Developers" />
        <principal class="com.tribal.Clan" name="Developers" />
        <principal class="com.tribal.Chief" name="Erin" />
      </role>
    </role-mapping>
  </security>
</web-app>

WEB-INF/geronimo-web.xml using login domain specific mapping

<web-app ...>
  <security
         xmlns="http://geronimo.apache.org/xml/ns/security-1.1">
    <role-mapping>
      <role name="NormalUser">
        <login-domain-principal domain-name="LDAPdomain" 
               class="com.ldap.User" name="Aaron" />
        <login-domain-principal domain-name="LDAPdomain"
               class="com.ldap.Group" name="Developers" />
        <login-domain-principal domain-name="TRIBALdomain"
               class="com.tribal.Clan" name="Developers" />
        <login-domain-principal domain-name="TRIBALdomain"
               class="com.tribal.Chief" name="Erin" />
      </role>
    </role-mapping>
  </security>
</web-app>

WEB-INF/geronimo-web.xml using realm-specific mapping

<web-app ...>
  <security
         xmlns="http://geronimo.apache.org/xml/ns/security-1.1">
    <role-mapping>
      <role name="NormalUser">
        <realm-principal
               realm-name="LDAP" domain-name="LDAPdomain" 
               class="com.ldap.User" name="Aaron" />
        <realm-principal
               realm-name="LDAP" domain-name="LDAPdomain"
               class="com.ldap.Group" name="Developers" />
        <realm-principal
               realm-name="Tribal" domain-name="TRIBALdomain"
               class="com.tribal.Clan" name="Developers" />
        <realm-principal
               realm-name="Tribal" domain-name="TRIBALdomain"
               class="com.tribal.Chief" name="Erin" />
      </role>
    </role-mapping>
  </security>
</web-app>

In all of these cases, the configuration selects the role NormalUser, and then picks two LDAP principals and two "Tribal" principals to count as members of that role. The principal class is specific to the security realm; in this case one realm uses the classes User and Group whereas the other realm uses the classes Clan and Chief.

Note that there's a Developers principal in both LDAP and Tribal login domains. One is a "User" while the other is a "Clan". Using the simple mapping style, only the principal class distinguishes the two Developers principals, and if two login domains used the same principal classes, the Developers principals from the two would be indistinguishable. Using the login domain specific mapping, you can also specify that the Developers principal must come from the login domain LDAPdomain or TRIBALdomain, though if two different realms used the same login domain names and the same principal classes then the Developers principals from each realm might still overlap. Finally, when using realm-specific mapping, the principals can be distinguished even in that case.

	Tip
	Normally an application could only possibly see principals from a single Realm. For example, if a web application authenticates against the LDAP realm, there's no way that principals could be generated for the Tribal realm. It may be the case that application clients contacting EJBs login using one realm and a web application contacting the same EJBs uses a different login realm (so the EJBs might have security mappings for both realms), but this would be quite unusual.


9.3. Deploying a Security Realm		9.5. Using a Custom Login Module