Configuring JAAS Login Modules

JAAS 1.0 is part of J2SE platform. This section shows how to configure JAAS login module. This configuration can be used by not only by Geronimo but also by other servers or containers (such as JBoss, WebLogic, Tomcat, or Jetty).

J2SE JAAS Login Modules Configuration

Typically, when using the J2SE platform, JAAS login modules are configured in a configuration file, named either login-config.conf or jaas.conf. The configuration entries in this file have the following syntax:

 <name used by application to refer to this entry> {     <LoginModule> <flag> <LoginModule options>;     <optional additional LoginModules, flags and options>;     };

For more information on this syntax, see”JAAS Login Configuration File,” at http://java.sun .com/j2se/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html.

The flag represents the module behavior (Required, Requisite, Sufficient, and Optional), while the set of options is specific to that LoginModule. Following is an example of how this file may look when populated:

 MyConfig {    example.module.MyLoginModule  required debug=true; }; MySQLConfig {    Example.module.MyDBLoginModule  required              connection="jdbc:mysql://localhost:3306/sample"; };

This file is typically specified through the java.security.auth.login.config property when starting the JVM. For example:

java –Djava.security.auth.login.config=c:\\login-config.conf MyContainer

Some application servers will implement configured JAAS login modules through this file, and some will have their own proprietary ways of configuring these entries (such as with an XML file, or through programmatic means).

JBoss uses a login-config.xml file, and BEA Weblogic uses MBeans and MBean Definition Files. Geronimo has its own way to configure login modules. It is done through the configuration of specialized GBeans in deployment plans.

Configuration JAAS Login Modules in Geronimo

In Geronimo, you can configure login modules by first specifying a GeronimoLoginConfiguration GBean in the deployment plan. This GBean will build a JAAS configuration. A typical GeronimoLoginConfiguration entry may look like this:

 <gbean name="LoginConfiguration" >         <references name="Configurations">             <pattern><type>SecurityRealm</type></pattern>             <pattern><type>ConfigurationEntry</type></pattern>         </references>     </gbean>

The GeronimoLoginConfiguration GBean manages each of the JAAS configuration entries. This GBean builds a complete JAAS configuration, and, in fact, extends the javax.security.auth.login .Configuration class, which is the JAAS representation of the login configuration presented in the last section. This GBean’s primary responsibility is to collect and build a JAAS configuration.

During run time, the GeronimoLoginConfiguration GBean looks for other GBeans of certain types that represent the actual configuration entries. In Geronimo, configuration entries are represented by objects that implement the ConfigurationEntryFactory interface.

For example, as shown in the previous configuration segment, GeronimoLoginConfiguration looks for other GBeans that represent the type of SecurityRealm and ConfigurationEntry. These two J2EE component object types usually represent GBeans in the system that implements the ConfigurationEntryFactory interface. The <pattern> element tells Geronimo to match for any objects of type that matches the specified pattern.

GBeans that implement the ConfigurationEntryFactory interface represent the actual configuration entry and minimally will contain the necessary information to produce a JAAS configuration. This includes an application name and a reference to a LoginModule (which usually is yet another GBean).

The ConfigurationEntryFactory is then capable of returning the entire configuration in an object known as a JaasLoginModuleConfiguration. Geronimo offers three different types of GBeans that implement the ConfigurationEntryFactory interface:

• DirectoryConfigurationEntry

• ServerRealmConfigurationEntry

• GenericSecurityRealm

The following sections examine each of these GBeans in turn.

DirectConfigurationEntry

The DirectConfigurationEntry GBean is a configuration entry that allows you to have a direct link to a single LoginModule. Nothing will go through the JaasLoginService GBean to use the Geronimo Login API, nor will a JaasLoginCoordinator be used to proxy the LoginModule’s access. It essentially does what the name of the GBean states - provides a direct link to a configuration with a single LoginModule. It’s a way to create a simple login configuration.

The following plan snippet shows a DirectConfigurationEntry set up with a Derby LoginModule that handles authentication based on a Derby database. The application configuration is called myApplication and sets the LoginModule’s control flag to REQUIRED. It references a LoginModule named DerbyLoginModule. (See the highlighted code in the following listing.)

 <gbean name="MyApplicationDirectConfigurationEntry"        >   <attribute name="applicationConfigName">myApplication</attribute>   <attribute name="controlFlag">REQUIRED</attribute>   <reference name="Module">     <name>DerbyLoginModule</name>   </reference> </gbean>  <gbean name="DerbyLoginModule"       >     <attribute name="loginModuleClass">       org.apache.geronimo.security.realm.providers.SQLLoginModule</attribute>     <attribute name="serverSide">true</attribute>     <attribute name="options">       jdbcUser=system       jdbcPassword=manager       jdbcURL=jdbc:derby:net://localhost:1527/SystemDatabase;       jdbcDriver=com.ibm.db2.jcc.DB2Driver       userSelect=select user, pswd from myapp.users       groupSelect=select role, user from myapp.userroles     </attribute>     <attribute name="loginDomainName">derby-login-realm</attribute> </gbean>

Don’t worry too much about the LoginModule configuration at this point; it will be discussed in great detail later in the chapter.

The DirectConfigurationEntry GBean allows you to create a simple configuration entry wired to a single LoginModule. Table 15-1 shows the DirectConfigurationEntry GBean’s attributes.

Table 15-1: DirectConfigurationEntry GBean
Open table as spreadsheet

Type	Name	Req	Description
A	applicationConfigName	Yes	The name of the configuration entry.
A	controlFlag	Yes	One of the four control flags used for the LoginModule. REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL.
R	Module	Yes	References the name of a LoginModule GBean.
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

ServerRealmConfigurationEntry

The ServerRealmConfigurationEntry GBean is a special component that allows you to create a new configuration name to be used with an existing, configured security realm (GenericSecurityRealm).

Typically, a GenericSecurityRealm will have the realm name configured as the application configuration name. However, the ServerRealmConfigurationEntry allows you to reuse an already configured security realm and add an application configuration name to the realm. This is essentially an alias to another name to the security realm. The following is a snippet from the Geronimo default security plan that allows the geronimo-properties-realm to be aliased to the name JMX:

 <gbean name="JMX"         >   <attribute name="applicationConfigName">JMX</attribute>   <attribute name="realmName">geronimo-properties-realm</attribute>   <reference name="LoginService"><name>JaasLoginService</name></reference> </gbean>

The reason you may wish to do this is to avoid duplicating a full security realm. A perfectly good use case for this is what is representative of this in the previous example. The Geronimo security configuration needs to allow for JMX remoting of the geronimo-properties-realm, or basically allow another application the ability to reference this realm by the JMX name. This snippet leverages reuse of the geronimo-security-realm and additionally allows the configuration to be referenced with the JMX application configuration name.

Another use case may be that you have several applications that require different names for the security realm, but you may want to have the same security realm implementation. In this case, you simply create an alias (using a ServerRealmConfigurationEntry) for each application.

The ServerRealmConfigurationEntry GBean allows you to attach an application configuration name to an already existing security realm. Table 15-2 shows the ServerRealmConfigurationEntry GBean’s attributes and descriptions.

Table 15-2: ServerRealmConfigurationEntry GBean
Open table as spreadsheet

Type	Name	Req	Description
A	applicationConfigName	Yes	The name of the configuration entry.
A	realmName	Yes	Name of an existing security realm.
A	wrapPrincipals	No	May be true or false. Defaults to false. If set to true, all principals will be wrapped with a DomainPrincipal and RealmPrincipal. This is used to help differentiate between the same principal that is added by two different login modules.
R	LoginService	Yes	References the name of the JaasLoginService GBean.
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

GenericSecurityRealm

The GenericSecurityRealm represents a Geronimo security realm, explored earlier in the section “Security Realms and Login Domains.” Technically, a GenericSecurityRealm GBean implements the SecurityRealm Java interface. Translated, it means that you can use this component to configure a security realm. GenericSecurityRealm allows you to configure login module chaining, enabling authentication policy that utilizes multiple LoginModules.

In Geronimo, a security realm minimally involves three GBeans:

• GenericSecurityRealm - The main security realm GBean.

• JaasLoginModuleUse - A wrapper GBean that takes a reference to a LoginModuleGbean, and provides for setting the LoginModule’s control flag and reference additional JaasLoginModuleUse GBeans for LoginModule chaining. Typically, each LoginModuleGbean will have one JaasLoginModuleUse GBean referencing it.

• LoginModuleGbean - The GBean referenced by the JaasLoginModuleUse GBean. This is a GBean that wraps an actual LoginModule class.

The LoginModuleGBean and JaasLoginModuleUse GBeans will be explained in detail later in this chapter. This section concentrates on the GenericSecurityRealm.

The Listing 15-1 code snippet comes from the default security configuration in Geronimo. This is an example of how the geronimo-properties-realm security realm configuration was configured in the j2ee-security plan.

Important

You can only see this plan by looking at the Geronimo source because it is distributed as a compiled CAR file in the binary distribution.

Listing 15-1: Example Realm Configuration of a geronimo-properties-realm

     <gbean name="geronimo-properties-realm"         >         <attribute name="realmName">geronimo-properties-realm</attribute>         <reference name="LoginModuleConfiguration">              <name>properties-login</name>        </reference>         <reference name="ServerInfo"><name>ServerInfo</name></reference>         <reference name="LoginService"><name>JaasLoginService</name></reference>     </gbean>     <gbean name="properties-login" >          <attribute name="controlFlag">REQUIRED</attribute>          <reference name="LoginModule">              <name>properties-login</name>          </reference>      </gbean> <gbean name="properties-login"         >         <attribute name="loginModuleClass">org.apache.geronimo.security.realm.providers.PropertiesFile LoginModule</attribute>         <attribute name="serverSide">true</attribute>         <attribute name="options">             usersURI=var/security/users.properties             groupsURI=var/security/groups.properties         </attribute>         <attribute name="loginDomainName">geronimo-properties-realm</attribute>     </gbean>

Make note of the geronimo-properties-realm GBean that is of GenericSecurityRealm type. The realmName attribute represents the name of the realm, as well as representing the application configuration name. It’s this name that you would reference in your applications when you want to use this realm. It is important to remember that with a GenericSecurityRealm, the realmName is the JAAS application configuration name.

Also remember from the last section that, if you want to decouple the realm name and the application configuration name (or to create an alias), you can use an additional ServerRealmConfigurationEntry GBean to reference this realm.

The LoginModuleConfiguration reference will refer to the name of the JaasLoginModuleUse GBean, which is a wrapper to the LoginModuleGBean.

Important

In Listing 15-1, the plan contains GenericSecurityRealm a reference to the LoginService GBean and refers to it in the following manner:

 <reference name="LoginService">     <name>JaasLoginService</name> </reference>

Improtant

It is important to remember that this reference was only valid when it was in the same plan as the LoginService GBean. When you write your own plans to be deployed in Geronimo, be sure to declare your dependency on the j2ee-security plan so that it can find it, as follows:

 <environment> <dependencies>    <dependency>        <groupId>geronimo</groupId>        <artifactId>j2ee-security</artifactId>        <type>car</type>    </dependency> </dependencies> </environment> <reference name="LoginService">     <name>JaasLoginService</name> </reference>

Failure to do so will result in a deployment error.

The GenericSecurityRealm GBean allows you to configure a security realm that may be made up of one or more chained LoginModules. Table 15-3 lists the GenericSecurityRealm GBean configuration attributes and references.

Table 15-3: GenericSecurityRealm GBean
Open table as spreadsheet

Type	Name	Req	Description
A	realmName	Yes	The name and is also the JAAS application configuration name.
A	defaultPrincipal	No	Represents a default principal to use when the client is unauthenticated. Not normally needed unless you need a principal to be used for when an unauthenticated user needs to access your applications and needs principal representation.
A	restrictPrincipalsToServer	No	true or false. If set to true, clients will not be able to obtain principals generated by this realm from the login service. If false, clients will be able to receive all principals generated by this realm. Default is false.
A	wrapPrincipals	No	May be true or false. Defaults to false. If set to true, all principals will be wrapped with a DomainPrincipal and RealmPrincipal. This is used to make the principals unique so that they do not clash with other LoginModules’ principals that may use the same principal type.
R or X	LoginModuleConfiguration	No	When used as a reference, this will be the name reference to a JaasLoginModuleUse GBean. When used as an XML reference, will contain the XML to configure a full LoginModule based on the login-config schema. Although configuring a LoginModule is not necessary, it is recommended, since the security will be useless without one.
R	ServerInfo	Yes	Name reference to the ServerInfo GBean.
R	LoginService	Yes	Name reference to the JaasLoginService GBean.
Legend Type: (A) - Attribute, (R) - Reference to GBean, (X) - Contains an XML configuration Req: (Yes) - parameter is required, (No) - not required

Login Modules

LoginModules are configured with the LoginModuleGBean. This GBean is a wrapper for the actual JAAS login module itself. Configuration attributes include which LoginModule class to use, as well as the options that are to be set. Refer to the section “J2SE JAAS Login Modules Configuration” earlier in this chapter to see the corresponding login module configuration attributes.

The following is an example LoginModuleGBean configuration that sets up org.apache.geronimo .security.realm.providers.LDAPLoginModule, which is one of Geronimo’s included LoginModules in the ldap-demo example included with the Geronimo source code:

 <gbean name="ldap-login"         >         <attribute name="loginModuleClass">org.apache.geronimo.security.realm.providers.LDAPLoginModul e</attribute>         <attribute name="serverSide">true</attribute>         <attribute name="options">           initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory           connectionURL=ldap://localhost:1389           connectionUsername=uid=admin,ou=system           connectionPassword=secret           connectionProtocol=           authentication=simple           userBase=ou=users,ou=system         userSearchMatching=uid={0}         userSearchSubtree=false         roleBase=ou=groups,ou=system         roleName=cn         roleSearchMatching=(uniqueMember={0})         roleSearchSubtree=false         userRoleName=      </attribute>   <attribute name="loginDomainName">ldap-realm</attribute> </gbean>

Notice the loginModuleClass attribute references the LoginModule’s LDAP class, and the options are each listed on a different line in the options attribute. The serverSide attribute is a flag that states that all of the processing will occur on the server. This means that the client will be authenticated through the server and that the server will process the authentication. It is highly recommended that you leave this parameter as true, since a majority of the time you will have the server process the authentication.

The LoginModuleGBean GBean represents a LoginModule configuration. Table 15-4 describes the LoginModuleGBean attributes.

Table 15-4: LoginModuleGBean GBean
Open table as spreadsheet

Type	Name	Req	Description
A	loginModuleClass	Yes	The name of the actual LoginModule class.
A	serverSide	Yes	May be true or false. Should be set to true. If true, it handles all of the authentication on the server side.
A	options	No	Sets options that are specific to the login module. Each option should be on its own line within the attribute.
A	wrapPrincipals	No	May be true or false. Defaults to false. If set to true, all principals will be wrapped with a DomainPrincipal and RealmPrincipal. This is used to make the principals unique so that they do not clash with other LoginModules’ principals that may use the same principal type.
A	loginDomainName	Yes	Unique name for the LoginModule. Usually a good idea to name it after the login domain, such as mysql-realm.
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

At this point, you are probably looking at the LoginModuleGBean and the login configuration and are wondering about a key missing component. The control flag in this GBean is configured in other GBeans. The reason is that the LoginModules are meant be reusable. You may have more than one security realm or configuration use a LoginModule, yet the control flags can change based on the realm. One realm may have a requirement (REQUIRE) that the LoginModule succeed, where another realm may make this optional (OPTIONAL).

When using a DirectConfigurationEntry GBean, you can set the control flag for the LoginModule in its controlFlag attribute. The ServerRealmConfigurationEntry does not have one, since it just allows the ability to rename the configuration. But the GenericSecurityRealm configuration refers to a special type of GBean, called a JaasLoginModuleUse, which allows you to set the controlFlag attribute for the LoginModule. The GenericSecurityRealm does not ever directly refer to a LoginModule, but uses JaasLoginModuleUse the instead.

JaasLoginModuleUse GBean

The JaasLoginModuleUse GBean is a wrapper for the LoginModuleGBean, which has a special function. Not only does it add an abstraction to be able to reuse a LoginModule (so that the controlFlag can be changed for different security realms), but it also allows you to configure LoginModule chaining. This means that your security realm can have the ability to use multiple LoginModules as part of a single configuration.

An example that was used earlier that could apply here is a single sign-on, where your realm will need to access an NTLM authentication, then also have it pass an LDAP authentication. To do this, these LoginModules would need to be chained. In this example, the NTLM GBean would be first, then chained to the LDAP GBean. The following snippet shows how this type of configuration would look:

 <gbean name="ntlm-login"       >   <attribute name="controlFlag">REQUIRED</attribute>   <reference name=" LoginModule">     <name>ntlm-login</name>   </reference>   <reference name="Next">     <name>ldap-login</name>   </reference> </gbean> <gbean name="ldap-login"       >   <attribute name="controlFlag">REQUIRED</attribute>   <reference name=" LoginModule">     <name>ldap-login</name>   </reference> </gbean>

The actual LoginModuleGBean configurations are not shown here for brevity, just the JaasLoginModuleUse GBeans. Notice how the Next reference for the ntlm-login JaasLoginModuleUse GBean refers to the ldap-login, making a chain. The fact that the ldap-login JaasLoginModuleUse GBean does not have a Next reference means it is the end of the chain.

The JaasLoginModuleUse GBean allows you to chain LoginModules when used with a GenericSecurityRealm configuration entry. Table 15-5 describes this GBean’s attributes.

Table 15-5: JaasLoginModuleUse GBean
Open table as spreadsheet

Type	Name	Req	Description
A	controlFlag	Yes	One of the four control flags used for the LoginModule. REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL
R	LoginModule	Yes	Named reference to the name of a LoginModuleGBean GBean
R	Next	No	Named reference of another JaasLoginModuleUse GBean that represents the next LoginModule in the chain
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

Included Login Modules

LoginModules can authenticate to many login domains, including LDAP, a database, a flat file, certificates, and so on. Luckily, you do not need to write LoginModules to enable these capabilities. Geronimo comes with a set of LoginModules that should fit most of your authentication needs. The full suite of Geronimo LoginModules are found in the org.apache.geronimo.security.realm.providers package:

• PropertiesFileLoginModule

• SQLLoginModule

• LDAPLoginModule

• CertificateChainLoginModule

• CertificatePropertiesFileLoginModule

Geronimo also includes login modules that do not even have anything to do with authentication but act as a utility when used with other LoginModules in a chain with a GenericSecurityRealm. These types of modules act as utilities and can do things such as audit logging of security or lock out a user after a certain number of failed attempts, or even gather passwords and credentials to be accessed by other parts of the application. These utility LoginModules include the following:

• FileAuditLoginModule

• GeronimoPasswordCredentialLoginModule

• RepeatedFailureLockoutLoginModule

Table 15-6 lists all of the included LoginModules that come with Geronimo, as well as a description of their configuration options.

Table 15-6: Geronimo-Included LoginModules
Open table as spreadsheet

LoginModule	Description	Option	Req	Description
PropertiesFileLogin Module	LoginModule that uses user and group property files for a domain.	usersURI	Yes	The URI to a properties file that consists of user/password name/ value pairs in the format of user=password.
		groupsURI	Yes	The URI to a properties file that consists of group/users name/value pairs in the format of group=user1,user2,user3, … where each group is followed by the user list that belongs in that group. Each user is delimited by a comma.
SQLLoginModule	LoginModule that allows you to authenticate against a database domain.	jdbcDriver	No	Class driver used. Only needed if not using a dataSourceName.
		jdbcURL	No	JDBC Database connection URL. Only needed if not using a dataSourceName.
		jdbcUser	No	The user to be used to login to the database. Only needed if not using a dataSourceName.
		jdbcPassword	No	The password to be used to login to the database. Only needed if not using a dataSourceName.
		dataSourceName	No	The name of a configured data-source to use as the basis of the connection parameters. This is the recommended way to use this LoginModule so that it can leverage database pools. Using this parameter will ignore the JDBC parameters if set.
		dataSource Application	No	Only used if the dataSourceName is set. The configurationId of the application module for which the dataSourceName was configured. Do not include or set to null for a systemwide configuration.
		userSelect	Yes	A SQL select statement, that returns the username and pass-word, in that order, and should include a (?) parameter in the where clause that does a lookup of the username. Example: select username, password from users where username = ?
		groupSelect	Yes	A SQL select statement, that returns the username and group, in that order, and should include a (?) parameter in the where clause that does a look up of the username. Example: select user, group from groups where username = ?
LDAPLoginModule	LoginModule that authenticates against a LDAP domain.	initialContext Factory	Yes	The InitialContext factory to use. Usually should be com.sun .jndi.ldap.LdapCtxFactory.
		connectionURL	Yes	URL of the LDAP server to connect to. For a production LDAP this will be ldap://[your server’s LDAP host address]:389.
		connection Username	Yes	The distinguished name (DN) of the user to bind. Should be administrator or directory manager that has access to examine passwords.
		connection Password	Yes	Password of user to bind.
		connection Protocol	Yes	String that determines the security protocol, such as SSL. Valid options are up to the service provider. An empty setting such as connectionProtocol= is an acceptable entry.
		authentication	Yes	Usually one of several protocols. Typically will be “none”, “simple”, or “strong”.
		userBase	Yes	Base of the LDAP search string for the users.
		userSearch Matching	Yes	The LDAP attribute search string to find the user. Use {0} as your substitution parameter. Example: uid={0}
		userSearch Subtree	Yes	true or false. If true, the search will encompass the entire subtree. If false, it will only be at the level of the search.
		roleBase	Yes	LDAP string specifying the base objects from which to search for group/role.
		roleName	Yes	Attribute name that references the role name.
		roleSearch Matching	Yes	The LDAP search string to find the user. The value here depends on how your group schema is configured. Generally, the role will have many attributes that are the same, but with different values. An example is memberUID for LDAP authentication for UNIX systems. In this scenario, the value of the roleSearchMatching would be (memberUID={0}).
		roleSearch Subtree	Yes	Base of the LDAP search string for the roles.
		userRoleName	Yes	This attribute should list the name of the roles LDAP attribute if the roles information is carried in the user schema. Typically, the user information is set within the memberUID of the roles schema. However, to support the roles listed in a user schema, where this schema contains something like a memberOf attribute, it lists those roles. An empty setting such as userRoleName= is an acceptable entry. An empty setting means it is not used and is mutually exclusive of the roleSearchMatching.
CertificateProperties FileLoginModule	Reads a list of groups and users form properties files and checks that there is an SSL certificate that matches the user. The authentication is actually handled by the SSl layer to verify user ID and password. If a principal is delivered via the certificate, it is accepted and the group is handled via a lookup from the property file.	usersURI	Yes	The URI to a properties file that consists of a user list of valid users in the format of each user on each line.
		groupsURI	Yes	The URI to a properties file that consists of group/users name/value pairs in the format of group=user1,user2,user3,… where each group is followed by the user list that belongs in that group. Each user is delimited by a comma.
CertificateChainLogin Module	Authenticates users against a chain of certificates, validating that the certificate(s) has(have) a principal. This is usually used in server-to-server communication, where one server may present a chain of certificates to although it could be used for a Web client as well. This LoginModule does not do any actual authentication, but instead assumes that the certificate chain is acceptable, since it has already been used to construct a clientcertificate-authenticated SSL connection. It simply extracts the principal from the first certificate-distinguished name and additionally wraps it in a GeronimoUserPrincipal so getUserPrincipal() can work correctly.
FileAuditLoginModule	Writes authentication requests and attempts to write to an audit file. This module is not for authentication but is instead used in a LoginModule chain after another LoginModule that is responsible for the actual login. Since this must be used in a chain, it must be used with a GenericSecurityRealm configuration entry. To use, the primary LoginModule’s control flag should be set to REQUIRED or OPTIONAL, while the control flag for this module can be set to any of the settings.	file	Yes	The URI of the log file to create and use. Relative paths are relative to $GERONIMO_HOME. Example: var/log/securityautit.log
GeronimoPassword CredentialLoginModule	Allows you to keep track of a user’s credentials or password and is stuffed as a GeronimoPasswordCredential object in the subject’s private creden- tial set if the login is successful. This allows your applications the ability to retrieve the paswords when they would normally be lost after authen- tication. This module is not for authentication but is instead used in a LoginModule chain after another LoginModule that is responsible for the actual login. Since this must be used in a bchain, it must e used with a GenericSecurityRealm configuration entry. To use, the primary LoginModule’s control flag should be set to REQUIRED or OPTIONAL, while the control flag for this module should be set to REQUISITE.
RepeatedFailure LockoutLoginModule	Tracks and controls a user’s num- ber of failures within a period of time and can lock that user out from logging in for a specified length of time. This module is not for authentication, but is instead used in a LoginModule chain after another LoginModule that is responsible for the actual login. Since this must be used in a chain, it must be used with a GenericSecurityRealm con- figuration entry. To use, the primary LoginModule’s control flag, should be set to REQUIRED or OPTIONAL, while the control flag for this module should be set to REQUISITE.	failureCount	No	Number of failures allowed within the periods of time. Defaults to 5.
		failurePeriod Secs	No	Failure period in seconds. Represents the time period win- dow for which failures can occur. Defaults to 300 seconds, or 5 minutes.
		lockout DurationSecs	No	Amount of time in seconds that the user will be locked out based upon exceeding the failureCount. Defaults to 1800 seconds, or 30 minutes.

Simplifying LoginModule Configuration with the xml-reference login-config

You should notice that wiring a GenericSecurityRealm and a LoginModule took a minimum of three GBeans. Once you begin chaining LoginModules, the number of GBeans will escalate by two for each LoginModule in to your realm. This will also include editing your JaasLoginModuleUse GBeans to add the next attribute to point to your newly chained LoginModule. It can quickly get unwieldy, and there is a much simpler way to wire up a GenericSecurityRealm configuration with a LoginModule by using the xml-reference login configuration.

The xml-reference login configuration allows you to embed an XML login module configuration inside the GenericSecurityRealm GBean. This configuration can have as many login modules as you want as a part of your chain, and this will all involve setting up only a single GBean.

How this works is the LoginModuleConfiguration reference in the GenericSecurityRealm GBean will take two types of references: a reference to a JaasLoginModuleUse GBean, or an xml-reference configuration. If the LoginModuleConfiguration is tagged as an xml-reference, then it will contain a login-config xml login-config.

Listing 15-2 shows a GenericSecurityRealm GBean configuration that it set up to use the xml-reference for the LoginModuleConfiguration, and contains two LoginModules: PropertiesFileLoginModule and FileAuditLoginModule.

Listing 15-2: Example Realm Configuration Using an xml-reference

 <environment> <dependencies>       <dependency>        <groupId>Geronimo</groupId>        <artifactId>j2ee-security</artifactId>        <type>car</type>       </dependency> </dependencies> </environment> ...  <gbean name="one-gbean-properties-realm"          >     <attribute name="realmName">one-gbean-properties-realm</attribute>     <xml-reference name="LoginModuleConfiguration">     <lc:login-config xmlns:lc="http://geronimo.apache.org/xml/ns/loginconfig">       <lc:login-module control-flag="REQUIRED" server-side="true">         <lc:login-domain-name>one-gbean-properties-realm</lc:login-domain-name>         <lc:login-module-class> org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule</lc:login- module-class>         <lc:option name="usersURI">var/security/users.properties</lc:option>         <lc:option name="groupsURI">var/security/groups.properties</lc:option>       </lc:login-module>       <lc:login-module control-flag="REQUISITE" server-side="true">            <lc:login-domain-name>one-gbean-properties-realm</lc:login-domain-name>         <lc:login-module-class> org.apache.geronimo.security.realm.providers.FileAuditLoginModule</lc:login-module- class>         <lc:option name="file">var/log/securityaudit.log</lc:option>       </lc:login-module>     </lc:login-config>     </xml-reference>     <reference name="ServerInfo">       <name>ServerInfo</name>      </reference>     <reference name="LoginService">        <name>JaasLoginService</name>     </reference>   </gbean> 

Notice that once the LoginModuleConfiguration is set to use the xml-reference, a login-config is a child of the xml-reference. The <login-config> element must start the configuration with a name space declaration to the loginconfig schema, or xmlns:lc="http://geronimo.apache.org/xml/ ns/loginconfig". In this example, lc is designated as the domain prefix for the rest of the configuration. This name space declaration is important, since it will help the deployer validate that your configuration is syntactically correct.

Login-config Tag

Inside the element, you can add one or more login modules. There are two ways to refer to a login module here. You can refer to another LoginModule by referring to it by its GBean reference (which allows you to reuse already configured LoginModules), or you can fully declare a LoginModule in its entirety.

 ... <lc:login-config xmlns:lc="http://geronimo.apache.org/xml/ns/loginconfig">   <lc:login-module-ref>     ...   </lc:login-module-ref>   <lc:login-module>     ...   </lc:login-module> </lc:login-config> ...

To refer to a login that has already been created, you use the <login-module-ref> element. To declare a new LoginModule, you use the <login-module> element.

Login-module-ref Element

The <login-module-ref> element is used to refer to another LoginModule that has already been declared. First, the element requires the control-flag attribute, which may contain one of the four control flags used for the LoginModule reference, REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL. The element must also contain a child <name> attribute that contains the named reference. It may also optionally consist of a number of additional elements that will help the deployer find the LoginModule. The following are a list of these elements:

• <domain> - The GBean domain component of the name. In a standard configuration, this would be (and should be) geronimo.server. This is an optional element, and it will default to the JSR-77 naming convention if it is not used. The default will typically be geronimo.server.

• <server> - The server component of the GBean name. In a standard configuration, this would be (and should be) geronimo. This is an optional element and it will default to the JSR-77 naming convention if it is not used. The default will typically be geronimo.

• <application> - The application component of the GBean name. It should usually reference the applicationId of an application module or configId if the applicationId is not used. If neither are used, then it should be null. This is an optional element, and it will default to null if it is not used.

• <module> - The module that the LoginModule resides. This will reference the configId of the module containing the LoginModule. This is an optional element, and it will default to the current plan’s configId if not used.

• <type> - Should be set to LoginModule since it will be referencing a LoginModule type. This is an optional element, and it will default to LoginModule if not used.

An example <login-module-ref> declaration would look like the following:

 ... <lc:login-module-ref control-flag="REQUIRED">   <lc:domain>geronimo.server</lc:domain>   <lc:server>geronimo</lc:server>   <lc:application>null</lc:application>   <lc:module>geronimo/j2ee-security/1.0/car</lc:module>   <lc:type>LoginModule</lc:type>   <lc:name>properties-login</lc:name> </lc:login-module-ref> ...

Login-module Element

The other way to declare a LoginModule with the login-config XML is with the <login-module> element. This allows you to fully configure and declare a LoginModule with all of the trimmings. Like the <login-module-ref> element, this also requires the control-flag attribute, but it also has the server- side attribute as well. This attribute means that the client will be authenticated through the server and that the server will process the authentication. It is highly recommended to set this parameter as true, since a majority of the time you will have the server process the authentication. The <login-module> element also has several child elements that match the standard GBean LoginModule configuration:

• <login-domain-name> - Unique name for the LoginModule. Usually it is a good idea to name it after the login domain, such as mysql-realm. This is a required element.

• <login-module-class> - The name of the actual LoginModule class. The full package name and class are required. An example is org.apache.geronimo.security.realm.providers .PropertiesFileLoginModule. This is a required element.

• <option name="Option Name"> - If your LoginModule has options for the class being used, you may have one or more options that need to be set. This element must use the name attribute for the name of the option, and the value will be in the body of the element. The requirement of this element is dependent on the LoginModule class that is used.

The following is an example <login-module> declaration using a PropertiesFileLoginModule:

 ... <lc:login-module control-flag="REQUIRED" server-side="true">   <lc:login-domain-name>one-gbean-properties-realm</lc:login-domain-name>   <lc:login-module-class>     org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule   </lc:login-module-class>   <lc:option name="usersURI">var/security/users.properties</lc:option>   <lc:option name="groupsURI">var/security/groups.properties</lc:option> </lc:login-module> ...

For those who prefer to view XML schemas, Listing 15-3 is the full XML schema for the embeddable login-config xml configuration. As you can see, configuring a GenericSecurityRealm with the xml-reference for LoginModules is much simpler, since you can clearly see and maintain the realm configuration in a single GBean.

Listing 15-3: Login-config XML Schema

 <xsd:schema     xmlns:xsd="http://www.w3.org/2001/XMLSchema"     xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"     xmlns:geronimo="http://geronimo.apache.org/xml/ns/loginconfig-1.1"     targetNamespace="http://geronimo.apache.org/xml/ns/loginconfig-1.1"     xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"     elementFormDefault="qualified"     attributeFormDefault="unqualified"     version="1.0">     <xsd:import namespace="http://geronimo.apache.org/xml/ns/deployment-1.1" schemaLocation="geronimo-config-1.1.xsd"/>      <xsd:element name="login-config" type="geronimo:login-configType"/>     <xsd:complexType name="login-configType">     <xsd:annotation>       <xsd:documentation>         Defines the list of login modules for a login configuration         represented by a GenericSecurityRealm       </xsd:documentation>     </xsd:annotation>     <xsd:sequence>       <xsd:choice minOccurs="0" maxOccurs="unbounded">          <xsd:element name="login-module-ref" type="geronimo:login-module-refType"                  minOccurs="0" maxOccurs="unbounded"/>          <xsd:element name="login-module" type="geronimo:login-moduleType"                   minOccurs="0" maxOccurs="unbounded"/>        </xsd:choice>      </xsd:sequence>      </xsd:complexType>      <xsd:complexType name="abstract-login-moduleType" abstract="true">      <xsd:attribute name="control-flag" type="geronimo:control-flagType"                    use="required"/>     </xsd:complexType>      <xsd:complexType name="login-module-refType">        <xsd:complexContent>                     <xsd:extension base="geronimo:abstract-login-moduleType">            <xsd:sequence>                                <xsd:element name="domain" type="xsd:string" minOccurs="0"/>              <xsd:element name="server" type="xsd:string" minOccurs="0"/>              <xsd:element name="application" type="xsd:string" minOccurs="0"/>              <xsd:element name="module" type="xsd:string" minOccurs="0"/>              <xsd:element name="type" type="xsd:string" minOccurs="0"/>              <xsd:element name="name" type="xsd:string"/>          </xsd:sequence>         </xsd:extension>      </xsd:complexContent>      </xsd:complexType>      <xsd:simpleType name="control-flagType">        <xsd:restriction base="xsd:string">          <xsd:enumeration value="REQUIRED"/>          <xsd:enumeration value="REQUISITE"/>          <xsd:enumeration value="SUFFICIENT"/>          <xsd:enumeration value="OPTIONAL"/>        </xsd:restriction>         </xsd:simpleType>     <xsd:complexType name="login-moduleType">        <xsd:complexContent>          <xsd:extension base="geronimo:abstract-login-moduleType">            <xsd:sequence>              <xsd:element name="login-domain-name" type="xsd:string"/>              <xsd:element name="login-module-class" type="xsd:string"/>              <xsd:element name="option" type="geronimo:optionType" minOccurs="0"                            maxOccurs="unbounded"/>            </xsd:sequence>          <xsd:attribute name="server-side" type="xsd:boolean" use="required"/>        </xsd:extension>       </xsd:complexContent>     </xsd:complexType>      <xsd:complexType name="optionType">        <xsd:simpleContent>          <xsd:extension base="xsd:string">            <xsd:attribute name="name" type="xsd:string" use="required"/>          </xsd:extension>        </xsd:simpleContent>      </xsd:complexType> </xsd:schema>

Configuring Your Realm - The Really Easy Way

Now that you have seen two different ways to manually configure your security realm, you will see how the Geronimo Web console makes security realm configuration a snap. As usual, to access the Web console, you navigate your Web browser to http://localhost:8080/console. (If you are not running Geronimo on the same computer as your Web browser, replace localhost with whatever server name or IP address that Geronimo is running on.) When navigating to the console, you will be asked to log in as the administrator. The username is system and the password is manager (for a standard Geronimo configuration). After successfully logging in, the menus will be on the left side of the console. Select the Security Realms link, and you should see a screen that shows a list of all the configured security realms in Geronimo, as shown in Figure 15-4.

Figure 15-4: The Geronimo console’s Security Realms portlet

This Security Realms portlet allows you to add and edit security realms, all from the comfort of your own browser. This portlet additionally will show you usage examples, and it will come up with a final plan for you that you can deploy from your browser or cut and paste into your own plan.

To see how this works, let’s create a new Properties File Realm from the console and name it my-new- realm. On the Securty Realms portlet, select the “Add new security realm link.” This begins the Create Security Realm Wizard that steps you through the realm-creation process. The portlet will show the Step 1, which asks you for the name of your security realm and what type of realm you want to configure. The Portlet Wizard offers you five different types of realms that you can configure, which should support most of your needs.

From the console, you can select a Certificate Properties File Realm, Database (SQL) Realm, LDAP Realm, Properties File Realm, or Other. You can probably figure out which realms match which LoginModules that are included with Geronimo by their name. The Other type of realm is included so that you can configure LoginModules that you may have developed or included yourself. For this example, type in my-new-realm for the name of the security realm and select Properties File Realm from the Realm Type drop-down list, as shown in Figure 15-5.

Figure 15-5: Security Realm portlet Step 1

After entering the information, click the Next button and the wizard will take you to Step 2, Configure Login Module. Each Realm type (Properties, Certificate, LDAP, Database, and so on) has a different page for configuration. In this example, you should now be shown the page that shows the options for the Properties File Realm. From the section “Included Login Modules” earlier in this chapter, you can find out that for Properties File Realms, you have a usersURI and groupsURI options. You will set these options pointed to a users.properties and a groups.properties file, respectively.

The Step 2 screen shows you just that. It is requesting a Users File URI and a Groups File URI. Geronimo comes with a users.properties and groups.properties file already configured. (This is how you logged into the console to begin with, using these files for security.) So, you can reuse these. Type var/security/users.properties for the Users File URI and var/security/groups.properties for the Groups File URI, as shown in Figure 15-6.

Figure 15-6: Security Realm portlet Step 2

Click the Next button, which will bring you to Step 3, Advanced Configuration. When you saw the list of realm types to choose from, you probably noticed that it was missing several realms that come with Geronimo. In particular, you may have noticed that the utility LoginModules, such as the FileAudit LoginModule, the GeronimoPasswordCredentialLoginModule, and RepeatedFailureLockout LoginModule realm type equivalents, seemed to be missing. Step 3 allows you to set up these Login Modules in the chain.

The form on this portlet page is very simple. It offers you the ability to Enable Auditing, Enable Lockout, and Store Passwords. Of course, these correspond to the chained FileAuditLoginModule, Geronimo PasswordCredentialLoginModule, and RepeatedFailureLockoutLoginModule, respectively. You can select which one of the features you want to use, click its associated checkbox. When you enable the option, it will show additional information that it may need to complete the request. For this example, enable the Auditing and Lockout options. When you enable the Auditing, it will ask you for a log filename. Type var/log/securityaudit.log in the Log File field. When you enable the Lockout option, it will request three additional fields. Enter 3 in the failures field, 300 in the first “seconds” field, and 1800 in the last “seconds” field, as shown in Figure 15-7.

Figure 15-7: Security Realm portlet Step 3

At this point, you have three options for what you can do with your realm configuration. You can test a login, skip the test and directly deploy your new realm, or skip the test and just show the plan. These three options are shown as buttons at the bottom of the screen. In this example, you will try out your login to verify that it works. Press the Test a Login button, and you will be shown Step 4, Test Login.

This screen requests for a username and password to try out the authentication. The username and password should be ones that you know are already configured. If you created a Database SQL Realm, you would type in the username and passwords that are set up in your configured tables. In this example, since you are using the properties files that are included with Geronimo (users.properties and groups.properties), you know that a valid username is system and password is manager. Type these values into their respective fields and press the Next button, as shown in Figure 15-8.

Figure 15-8: Security Realm portlet Step 4

If you typed in everything correctly, you should see the screen as shown in Figure 15-9. It will tell you if you have succeeded, as well as the principals that it obtained during the authentication.

Figure 15-9: Security Realm portlet Step 5

At this point, you have the ability to test again, edit the realm, show the plan, or deploy the realm. Use the Test Again option if you want to try out different usernames and passwords. If you have problems with the authentication, or wish to make changed to the realm, you can select the Edit Realm option. To immediately deploy the new realm, you can select the Show Plan button.

In this example, press the Show Plan button, so that you may view the newly created realm’s plan. This will bring you to the portlet view as shown in Figure 15-10. This screen is one of the most helpful features of this tool. This portlet view lists how the configured realm would look if you had created a security realm plan. It actually creates the plan for you. You can copy and paste the new plan in its own file and follow the instructions on how to deploy this new plan. It also tells you how you can include the new plan within a geronimo-application.xml file that you can distribute with an EAR file.

Figure 15-10: Security Realm-Show Deployment Plan screen

You may be wondering why not just deploy the realm from this screen. There are several good reasons for this. You may wish to build an EAR file that you will distribute to multiple servers, for example in a cluster of Geronimo instances. You also may wish to keep a copy of the plan under source control to be a part of a distribution, such as the examples that come with Geronimo. In fact, it is recommended that you use this tool to produce the plan that you can copy/paste to a file when you develop production-level projects, so that you can keep an audit trail of changes that you make. However, you may deploy your realm directly from the console if you wish. On this screen, you have the option of pressing the Edit Settings button (which will bring you to a page that allows you to edit the realm) or pressing Deploy Realm (which will deploy and activate your new realm).

Editing the settings gives you some additional control over the settings of your login modules (such as the control flags and other attributes that were discussed in this chapter). You can always go back to the top-level Security Realm portlet and edit your settings from there with the Edit link next to your realm. Another very powerful tool you can use after you configure your realm is the Usage link, which is also next to your realm on the top-level Security Realms portlet. This link brings you to a screen that gives you some helpful hints on how to use your new realm in a Web application’s web.xml and geronimo- web.xml plans. It will even use your new realm as an example. It’s a great starting point to using your new realm in your applications.

As you can see, configuring your security realms through the Geronimo Web console can be a lot simpler than hand-coding the GBean configuration yourself. At the very minimum, it can be used as a starting point and generate security realm plan for you.

Deployment and the Server Security Plan

Up until now, a lot of ground was covered on the creation of security realms and the configuration of login modules. Outside of the console’s ability to deploy the security realm using a generated plan, there has not been any discussion on how to add realms to your own plans or how to manually deploy a realm from the command line. The rest of this chapter shows how the security realms you create can be used in deployment plans to secure your applications.

Typically, you will either have your security realm configuration in its own plan or include it within a geronimo-application.xml file. If it is in its own plan file, you need a <configuration> element that declares the deployment namespace as follows:

 <configuration         xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1"> ...    <!"GBean security realm goes here --> ... </configuration>

Embedding it within a geronimo-application.xml is similar. But in this instance, you use the <application> element and a reference to the application namespace.

 <application       xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"       > ...    <!"GBean security realm goes here --> ... </application>

Deploying a realm from a standalone plan will make your realm available to any resources or application that wishes to use it, and, therefore, is known as a serverwide deployment. If it’s within a geronimo- application.xml file, it is then the realm will only have visibility within the application itself.

Deploying your plan is the same as any other plan deployment in Geronimo. You can use the deploy.sh (or deploy.bat if on Windows) script to deploy, or use the raw Java command. The deploy.sh script is in the $GERONIMO_HOME/bin directory. To deploy a standalone plan file called myrealm.xml, using the deploy.sh script, execute the following command:

 deploy.sh –username system –password manager deploy myrealm.xml

To deploy using the Java command, execute the following command:

 java -jar bin/deployer.jar deploy myrealm.xml