14.5. About Java Authentication and Authorization Service (JAAS)

The security architecture of JBoss EAP 6 is comprised of the security configuration subsystem, application-specific security configurations which are included in several configuration files within the application, and the JAAS Security Manager, which is implemented as an MBean.
Domain, Server Group, and Server Specific Configuration

Server groups (in a managed domain) and servers (in a standalone server) include the configuration for security domains. A security domain includes information about a combination of authentication, authorization, mapping, and auditing modules, with configuration details. An application specifies which security domain it requires, by name, in its jboss-web.xml.

Application-specific Configuration

Application-specific configuration takes place in one or more of the following four files.

Table 14.1. Application-Specific Configuration Files

File Description
ejb-jar.xml
The deployment descriptor for an Enterprise JavaBean (EJB) application, located in the META-INF directory of the EJB. Use the ejb-jar.xml to specify roles and map them to principals, at the application level. You can also limit specific methods and classes to certain roles. It is also used for other EJB-specific configuration not related to security.
web.xml
The deployment descriptor for a Java Enterprise Edition (EE) web application. Use the web.xml to declare the security domain the application uses for authentication and authorization, as well as resource and transport constraints for the application, such as limiting which types of HTTP requests are allowed. You can also configure simple web-based authentication in this file. It is also used for other application-specific configuration not related to security.
jboss-ejb3.xml
Contains JBoss-specific extensions to the ejb-jar.xml descriptor.
jboss-web.xml
Contains JBoss-specific extensions to the web.xml descriptor..

Note

The ejb-jar.xml and web.xml are defined in the Java Enterprise Edition (Java EE) specification. The jboss-ejb3.xml provides JBoss-specific extensions for the ejb-jar.xml, and the jboss-web.xml provides JBoss-specific extensions for the web.xml.
The JAAS Security Manager MBean

The Java Authentication and Authorization Service (JAAS) is a framework for user-level security in Java applications, using pluggable authentication modules (PAM). It is integrated into the Java Runtime Environment (JRE). In JBoss EAP 6, the container-side component is the org.jboss.security.plugins.JaasSecurityManager MBean. It provides the default implementations of the AuthenticationManager and RealmMapping interfaces.

The JaasSecurityManager MBean integrates into the EJB and web container layers based on the security domain specified in the EJB or web deployment descriptor files in the application. When an application deploys, the container associates the security domain specified in the deployment descriptor with the security manager instance of the container. The security manager enforces the configuration of the security domain as configured on the server group or standalone server.
Flow of Interaction between the Client and the Container with JAAS

The JaasSecurityManager uses the JAAS packages to implement the AuthenticationManager and RealmMapping interface behavior. In particular, its behavior derives from the execution of the login module instances that are configured in the security domain to which the JaasSecurityManager has been assigned. The login modules implement the security domain's principal authentication and role-mapping behavior. You can use the JaasSecurityManager across different security domains by plugging in different login module configurations for the domains.

To illustrate how the JaasSecurityManager uses the JAAS authentication process, the following steps outline a client invocation of method which implements method EJBHome. The EJB has already been deployed in the server and its EJBHome interface methods have been secured using <method-permission> elements in the ejb-jar.xml descriptor. It uses the jwdomain security domain, which is specified in the <security-domain> element of the jboss-ejb3.xml file. The image below shows the steps, which are explained afterward.
Authentication steps for an EJB

Figure 14.1. Steps of a Secured EJB Method Invocation

  1. The client performs a JAAS login to establish the principal and credentials for authentication. This is labeled Client Side Login in the figure. This could also be performed via JNDI.
    To perform a JAAS login, you create a LoginContext instance and pass in the name of the configuration to use. Here, the configuration name is other. This one-time login associates the login principal and credentials with all subsequent EJB method invocations. The process does not necessarily authenticate the user. The nature of the client-side login depends on the login module configuration that the client uses. In this example, the other client-side login configuration entry uses the ClientLoginModule login module. This module binds the user name and password to the EJB invocation layer for later authentication on the server. The identity of the client is not authenticated on the client.
  2. The client obtains the EJBHome method and invokes it on the server. The invocation includes the method arguments passed by the client, along with the user identity and credentials from the client-side JAAS login.
  3. On the server, the security interceptor authenticates the user who invoked the method. This involves another JAAS login.
  4. The security domain under determines the choice of login modules. The name of the security domain is passed to the LoginContext constructor as the login configuration entry name. The EJB security domain is jwdomain. If the JAAS authentication is successful, a JAAS Subject is created. A JAAS subject includes a PrincipalSet, which includes the following details:
    • A java.security.Principal instance that corresponds to the client identity from the deployment security environment.
    • A java.security.acl.Group called Roles, which contains the role names from the user's application domain. Objects of type org.jboss.security.SimplePrincipal objects represent the role names. These roles validate access to EJB methods according to constraints in ejb-jar.xml and the EJBContext.isCallerInRole(String) method implementation.
    • An optional java.security.acl.Group named CallerPrincipal, which contains a single org.jboss.security.SimplePrincipal that corresponds to the identity of the application domain's caller. The CallerPrincipal group member is the value returned by the EJBContext.getCallerPrincipal() method. This mapping allows a Principal in the operational security environment to map to a Principal known to the application. In the absence of a CallerPrincipal mapping, the operational principal is the same as the application domain principal.
  5. The server verifies that the user calling the EJB method has the permission to do so. Performing this authorization involves the following steps:
    • Obtain the names of the roles allowed to access the EJB method from the EJB container. The role names are determined by ejb-jar.xml descriptor <role-name> elements of all <method-permission> elements containing the invoked method.
    • If no roles have been assigned, or the method is specified in an exclude-list element, access to the method is denied. Otherwise, the doesUserHaveRole method is invoked on the security manager by the security interceptor to check if the caller has one of the assigned role names. This method iterates through the role names and checks if the authenticated user's Subject Roles group contains a SimplePrincipal with the assigned role name. Access is allowed if any role name is a member of the Roles group. Access is denied if none of the role names are members.
    • If the EJB uses a custom security proxy, the method invocation is delegated to the proxy. If the security proxy denies access to the caller, it throws a java.lang.SecurityException. Otherwise, access to the EJB method is allowed and the method invocation passes to the next container interceptor. The SecurityProxyInterceptor handles this check and this interceptor is not shown.
    • For web connection requests, the web server checks the security constraints defined in web.xml that match the requested resource and the accessed HTTP method.
      If a constraint exists for the request, the web server calls the JaasSecurityManager to perform the principal authentication, which in turn ensures the user roles are associated with that principal object.