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

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 java.security.Principal 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.

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:

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).

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:

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.

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

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.

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.