Chapter 9. Security Configuration [DRAFT (1.0-pre)]

Table of Contents

9.1. Geronimo Security Concepts
9.1.1. Login: Authentication and Principals
9.1.2. Security Realms
9.1.3. JAAS Login Modules
9.1.4. JAAS Configuration Entries
9.1.5. Authorization
9.1.6. One Login, Multiple Destinations
9.2. Security Realm Configuration
9.2.1. Easy Configuration and Deployment using the Console
9.2.2. Manual Security Realm Configuration
9.2.3. Configuration Options for Standard Login Modules
9.3. Deploying a Security Realm
9.3.1. Server-Wide Security Realms
9.3.2. Application-Scoped Security Realms
9.4. Enabling Security for Applications
9.4.1. Selecting the Realm to Authenticate Against
9.4.2. Mapping Roles to Principals
9.5. Using a Custom Login Module
9.5.1. Implementing a Custom LoginModule
9.5.2. Packaging and Deploying a Custom LoginModule
9.6. Configuring SSL/HTTPS
9.6.1. Keystore Configuration
9.6.2. HTTPS Connector Configuration
9.6.3. HTTPS Connector Deployment

In Geronimo, you can define and activate multiple security realms. Each security realm can authenticate users (validate their login), and provide a set of Principals used to authorize those users (control which services they can access). Since each secured J2EE application module provides a list of roles applicable to that module, you can specify which users or groups should be considered to have each application role. Finally, if certain resources (such as legacy database connections) require separate logins, it's also possible to map each user in the Geronimo security realm to a different account to be used with those resources.

Since there are a number of security-related options and a number of configuration points to straighten them all out, this chapter begins with a more extensive walkthrough of all the security concepts and their relations to each other, and then covers the configuration options for each.

9.1. Geronimo Security Concepts

9.1.1. Login: Authentication and Principals

A user may login to Geronimo in several ways, including:

  • A user visits a web application requiring authentication

  • A client application requires the user to authenticate in order to access a secured server-side resource (such as an EJB)

  • The server administrator is required to authenticate to use administrative tools to connect to the server

  • An application deployer is required to authenticate in order to deploy to a running server

In any of those cases, the user will be authenticated by a Geronimo security realm. In the common case, that means validating a username and password, though Geronimo can also handle Kerberos authentication and Client Certificate authentication as well.

When a security realm authenticates a user, it will provide one or more objects for the user. Each principal typically represents a user or group, so the most likely case is that a security realm would return a single user principal and a number of group principals for the user who just logged in. However, Geronimo doesn't restrict principals to users and groups -- a security realm may provide principals representing anything at all. For example, a site that tracks your school classmates might provide a principal for each school you attended, or a site that tracks pets may return a principal indicating whether you own dogs, cats, or goldfish. While it would be possible to represent these all as "groups", such as a group called "DogOwners", it may be less cumbersome for the realm to just represent this as a PetOwnerPrincipal with the name "dog"

Since Geronimo doesn't know exactly what kind of principals will be returned by any particular security realm, it falls on you to configure a list of which Principals from the realm get which access rights in the server.

9.1.2. Security Realms

Geronimo security realms are built around the Java Authentication and Authorization Service (JAAS). A Geronimo security realm uses one ore more JAAS LoginModules to process authentication requests, and a Geronimo security realm can also itself be exposed as a JAAS LoginModule to outside applications that want to validate against the Geronimo realm (such as application clients).

Internally, the security realm basically identifies a list of configured LoginModules, says what order they should be processed in, which ones must agree to the login to allow it to proceed, and so on. The bulk of the work takes place within the individual LoginModules. The LoginModules configured for a security realm may do things like:

  • Authenticate based on a username and password, certificate, or Kerberos credentials

  • Record all login attempts

  • Reject a login after a certain number of failures for that user

  • Add extra credentials when a user logs in, allowing them to transparently sign on to a different resource with a different username and password (for example, a database or J2EE connector)

Additionally, third-party or custom JAAS LoginModule can be added to a Geronimo security realm and will work as-is (no Geronimo-specific code is necessary). Default Security Realm

Geronimo does not have a server-wide default security realm. Any number of security realms may be configured in the server, and each application module should specify the name of the security realm it wants to use. In some cases, application deployments may be rejected if the J2EE deployment descriptor includes security settings but the Geronimo deployment plan omits the specify a security realm or other security settings.

9.1.3. JAAS Login Modules

A JAAS LoginModule provides the basic capabilities of prompting the user (typically for a username and password), validating the information they provide, and then creating a Subject containing the Principal entries for that user. Some other part of the system can then examine the principals in that subject, and decide whether to permit the user to access secured resources. As far as the login module is concerned, it is communicating directly with a user, so it can provide a prompt (or Callback) for the user to supply a username, password, and any other important information, and it expects the user to fill out the correct values. In practice, in a Geronimo security realm, it is Geronimo that actually gathers authentication information from the user, so the login module sends callbacks to Geronimo, and Geronimo populates them on behalf of the user. The login module's behavior is unchanged, though -- it still produces a subject for a successful login, and Geronimo will use the principals included in that subject to decide which services and resources the user should have access to.

Note that login modules can also take other action, with a Subject or Principal or otherwise. For example, an auditing LoginModule may simply record the username and time of every login attempt, without changing the Subject or Principals for the login attempt.

Geronimo ships with login modules that handle many common cases:

  • Authenticating against a list of users and groups stored in properties files on the server's filesystem.

  • Authenticating against a database holding the users and groups

  • Authenticating via Kerberos

  • Authenticating via SSL client certificates, where a properties file maps certificate names to users and groups

  • Auditing (recording all login attempts) to a file

  • Rejecting logins for a user after too many login failures in a certain period of time

  • Storing the login username and password in the Subject for future access

9.1.4. JAAS Configuration Entries

When a JAAS client attempts to log in, it identifies the login module to use by specifying a configuration name. That configuration name must correspond to a configuration that JAAS is aware of, so JAAS can delegate to the correct underlying LoginModules.

In a typical JAAS environment, there is a file listing all the configurations. However, Geronimo needs more control over the JAAS configuration process (because, for instance, Geronimo security realms can be added and removed at runtime). So in Geronimo, there are ConfigurationEntry GBeans that define the available login modules. When a new security realm is deployed, it actually needs to include one GBean for the realm and another GBean with the JAAS configuration entry for the realm. That way, the JAAS configuration system is made aware of new security realms as they are added.


The details of the configuration entries are not typically important for end users, but may be relevant for securiry administrators with more advanced needs.

9.1.5. Authorization

Application modules in Geronimo may be secured to limit access to members of a certain application role. Once a user has logged in and been authenticated by a login module, the server has a set of principals for the user, but it's still not clear which principals qualify for which roles. To resolve this, the Geronimo deployment plan for a module can list the principals from each security realm that should count as members of each role. With this information, Geronimo can list the principals for the current user, and then compare that to the set of principals for each role that's allowed to access the protected resource, and see if there are any principals in common. If any of the user's principals are the same as any of the required principals, then the access is allowed.

9.1.6. One Login, Multiple Destinations

Geronimo does not natively support web-based single sign-on across web sites. However, it is possible for a user to achieve some level of single sign-on within the Geronimo server. For example, a user "joe.smith" may log in to a web application, using that same account to access a secure EJB. However, that secure EJB may access a database or other back-end system that requires a different sign-on, perhaps "jsmith" with a separate password.

To accommodate this, it's possible to add two LoginModules to a security realm where the first validates in the initial (in this case web) login, and the second notices the successful login and adds a separate username and password to the user's Subject such that if they end up accessing the back-end system the information for the second account will already be in the user's Subject and no additional authentication steps are required.