Security realms

A security realm is a composition of one or more login modules and is equivalent to a JAAS LoginContext. By using a combination of authenticating login modules and special purpose login modules discussed earlier, you can create security realms that can not only be used to authenticate users, but can also be used to enable special features such as auditing and lockout on repeated failed login attempts. In this section, we will see how to create and deploy a security realm in Geronimo.

Creating a security realm

There are two ways to create a security realm in Geronimo. They are:

  • By using the Security Realms portlet in the Administration Console

  • By deploying a security realm plan

Using the Security Realms portlet

The Security Realms portlet in the Administration Console provides a step-by-step process to easily create a security realm, as follows:

  1. The process of creating a security realm is initiated by clicking on the Add new security realm link in the portlet. Then, you enter a name for your security realm and select the Realm Type, as shown in the following screenshot:

    The Name of Security Realm should be different to any of the existing security realms on the server. Select the Realm Type based on the data store containing the user credential information. The available options are:

    • Properties File Realm: Uses a PropertiesFileLoginModule for authenticating users

    • Database (SQL) Realm: Uses the SQLLoginModule for authenticating users

    • LDAP Realm: Uses an LDAPLoginModule for authenticating users

    • Certificate Properties File Realm: Uses a CertificatePropertiesFileLoginModule for authenticating users

    • Other: Select this option if you want to create a security realm based on your own custom login module implementation

  2. In the second step, you configure the options for the login module selected in Step 1.The next screenshot shows Step 2 of creating a Properties File Realm.

    In this example, in Step 2, we configure the two properties files used by the PropertiesFileLoginModule.

    Make sure that you copy the packt-users.properties and packt-groups.properties files provided in the samples to the <GERONIMO_HOME>/var/security directory. Otherwise, the current example security will fail to authenticate users.


  3. In Step 3, you can enable Advanced Configuration for the security realm, as shown in the following screenshot:

    The explanations of the features in Advanced Configuration are as follows:

    • Enable Auditing: Selecting this feature results in a FileAuditLoginModule being added to the login modules for the realm

    • Enable Lockout: Selecting this feature results in a RepeatedFailureLockoutLoginModule being added to the login modules for the realm

    • Store Password: Selecting this feature results in a GeronimoPasswordCredentialLoginModule being added to the login modules for the realm

    • Named Credential: Selecting this feature results in a NamedUsernamePasswordCredentialLoginModule being added to the login modules for the realm

At this stage, you have the option of testing your security realm or you can deploy the realm without testing or show the realm plan that could then be used to deploy the realm using any of the Geronimo deployment options.

The following is the security realm deployment plan for packt-properties-realm generated for our current example:

<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.2">
<environment>
<moduleId>
<groupId>console.realm</groupId>
<artifactId>packt-properties-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>
</dependencies>
</environment>
<gbean name="packt-properties-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">packt-properties-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>packt-properties-realm </log:login-domain-name>
<log:login-module-class>org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule</log:login-module-class>
<log:option name="usersURI">var/security/ packt-users.properties</log:option>
<log:option name="groupsURI">var/security/ packt-groups.properties</log:option>
</log:login-module>
<log:login-module control-flag="OPTIONAL" wrap-principals="false">
<log:login-domain-name>packt-properties-realm- Password</log:login-domain-name>
<log:login-module-class>org.apache.geronimo.security.realm.providers.GeronimoPasswordCredentialLoginModule</log:login-module-class>
</log:login-module>
<log:login-module control-flag="OPTIONAL" wrap-principals="false">
<log:login-domain-name>packt-properties-realm- Audit</log:login-domain-name>
<log:login-module-class>org.apache.geronimo. security.realm.providers.FileAuditLoginModule</log:login-module-class>
<log:option name="file">var/log/packt-login- attempts.log</log:option>
</log:login-module>
<log:login-module control-flag="REQUISITE" wrap-principals="false">
<log:login-domain-name>packt-properties-realm- Lockout</log:login-domain-name>
<log:login-module-class>org.apache.geronimo.security.realm.providers.RepeatedFailureLockoutLoginModule</log:login-module-class>
<log:option name="failureCount">5</log:option>
<log:option name="failurePeriodSecs">60 </log:option>
<log:option name="lockoutDurationSecs">300 </log:option>
</log:login-module>
<log:login-module control-flag="OPTIONAL" wrap-principals="false">
<log:login-domain-name>packt-properties-realm- NamedUPC</log:login-domain-name>
<log:login-module-class>org.apache.geronimo.security.realm.providers.NamedUsernamePasswordCredentialLoginModule</log:login-module-class>
<log:option name="Name">packt-secret</log:option>
</log:login-module>
</log:login-config>
</xml-reference>
</gbean>
</module>

The security realm can be deployed or the generated deployment plan can be copied to a file and then deployed by using any of the deployment options. The security realm will be deployed under the module name console.realm/packt-properties-realm/1.0/car. During realm creation using the Security Realms portlet, you can test a login and observe the GeronimoUserPrincipal and GeronimoGroupPrincipal(s) added to the JAAS subject.

Security realm deployment plan

Let us examine the structure of the security realm deployment plan. Important points to observe in the deployment plan are as follows:

  • The module has a dependency on org.apache.geronimo.framework/j2ee-security//car defined in the <environment> element. See Appendix A, Deployment Plans, for details on the <environment> element.

  • The plan defines a GBean of type GenericSecurityRealm by using a <gbean> element. The name of the GBean defined in the name attribute of the GBean element and the realmName attribute of the GBean defined using <attribute> element under <gbean> are both in the packt-properties-realm.

  • The security realm GBean has a reference named LoginModuleConfiguration defined using an <xml-reference> element, which defines the login modules that constitute the security realm.

  • The login module configuration defines five login modules, one corresponding to the Realm Type and one corresponding to each of the following advanced features selected:

    • Each login module is defined using a <login-module> element. The control-flag attribute of the <login-module> element defines the JAAS control-flag for the login module in the login configuration.

    • The <login-domain-name> element is used to define a login domain to which the authentication corresponds. This information is used for advanced authorization using principal wrapping.

    • The <login-module-class> element is used to specify the fully-qualified name of the login module class.

    • The <option> element is used to specify the options used by login module implementation. The option name is specified by using the name attribute.

  • The control-flag for authenticating the login module, in this case, PropertiesFileLoginModule, is "REQUIRED". The control-flag for RepeatedFailuresLockoutLoginModule is "REQUISITE", as this login module influences the overall authentication in addition to the authenticating login module.

Principal wrapping

We have observed that upon a successful login, the authenticating login module implementations add GeronimoUserPrincipal and GeronimoGroupPrincipal to the JAAS subject. Geronimo cannot distinguish between two different principals that have the same name and same principal class but were produced by two different login modules. To provide this distinction, Geronimo has a wrap-principals option. When this option is enabled, by setting the wrap-principals attribute in the login-module element to "true", Geronimo will "wrap" the principals to track which login module and security realm each principal came from. In the login module configuration, the login domain name is specified by using the login-domain-name child element of the login-module element. For each GeronimoUserPrincipal and GeronimoGroupPrincipal added by the authenticating login module, Geronimo will add one DomainPrincipal (wrapping the base principal along with the domain name) and one RealmPrincipal (wrapping the base principal with the domain name and the realm name) to the JAAS subject.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset