Introduction to Security in the Jakarta EE Platform

The security behavior of a Jakarta EE environment may be better understood by examining what happens in a simple application with a web client, a user interface, and enterprise bean business logic.

In the following example, which is taken from the Jakarta EE Specification, the web client relies on the web server to act as its authentication proxy by collecting user authentication data from the client and using it to establish an authenticated session.

A properly implemented security mechanism will provide the following functionality:

Ideally, properly implemented security mechanisms will also be

Jakarta EE applications consist of components that can contain both protected and unprotected resources. Often, you need to protect resources to ensure that only authorized users have access. Authorization provides controlled access to protected resources. Authorization is based on identification and authentication. Identification is a process that enables recognition of an entity by a system, and authentication is a process that verifies the identity of a user, device, or other entity in a computer system, usually as a prerequisite to allowing access to resources in a system.

Authorization and authentication are not required for an entity to access unprotected resources. Accessing a resource without authentication is referred to as unauthenticated, or anonymous, access.

The characteristics of application security that, when properly addressed, help to minimize the security threats faced by an enterprise include the following.

Java SE provides support for a variety of security features and mechanisms.

Java SE also provides a set of tools for managing keystores, certificates, and policy files; generating and verifying JAR signatures; and obtaining, listing, and managing Kerberos tickets.

For more information on Java SE security, visit https://docs.oracle.com/javase/8/docs/technotes/guides/security/.

Jakarta EE security services are provided by the component container and can be implemented by using declarative or programmatic techniques (see Securing Containers). Jakarta EE security services provide a robust and easily configured security mechanism for authenticating users and authorizing access to application functions and associated data at many different layers. Jakarta EE security services are separate from the security mechanisms of the operating system.

Jakarta Authentication defines a model for securing messages sent between a client and server in which the sender of a message "secures" it, and the receiver "validates" it. The details of how messages are secured and validated are undefined by the model; support for securing and validating particular types of messages is provided by "auth modules" — implementations of the Authentication ClientAuthModule and ServerAuthModule interfaces — that support particular protocols or message types, and that plug in to the Authentication framework. (Note that it is not necessary for a client and server to both use Authentication, as long as both sides process messages correctly for a given protocol.)

Authentication defines two "profiles" for integrating Authentication auth modules into Jakarta EE containers: the Servlet Container Profile, and the SOAP Profile. Each specifies how Authentication message processing must be integrated into the request processing flow of the container in question to validate incoming requests and secure outgoing responses.

In the case of the Servlet Container Profile, if a ServerAuthModule is configured/available for a given application context, then the modules’s validateRequest() method must be invoked (and succeed) before authorizing access and calling the target servlet, and the module’s secureResponse() method must be called before returning a response. Typically, a ServerAuthModule written for the Servlet Container Profile looks for user credentials or tokens in an incoming request, and then uses them to authenticate the caller and establish the caller’s identity. A ServerAuthModule may also engage in a challenge/response protocol with the client, or negotiate with a third party to establish/verify the client’s identity.

As with the Servlet Container Profile, the SOAP Profile requires that validateRequest() be called and succeed before proceeding to authorize access and perform any further processing of an incoming message, and that secureResponse() is called for the response before it is sent. In contrast to the Servlet Container Profile, validateRequest() processing for SOAP messages typically involves verifying signatures on signed elements, decrypting encrypted elements, and/or establishing the identity of a SOAP actor based on a token included in the message, while secureResponse() typically involves signing and/or encrypting elements of the outbound message.

Authentication does not define any standard or built-in ServerAuthModules; they must be provided either by the application using the module, or as a non-standard extension of a particular vendor’s Jakarta EE product. ServerAuthModules can sometimes be directly configured for an application in a vendor-specific way, but the standard mechanism for making a ServerAuthModule available to an application is to register a corresponding AuthConfigProvider with the global AuthConfigFactory. An AuthConfigProvider makes a ServerAuthModule available to the container, via a series of intermediary objects, for runtime message processing.

Jakarta Security defines the following authentication-related plugin SPIs:

Implementations of these SPI interfaces are CDI beans, and, as such, applications can provide implementations that support application-specific authentication mechanisms, or validate user credentials against application-specific identity stores, simply by including them in a bean archive that is part of the deployed application. There are also several standard, built-in implementations of HttpAuthenticationMechanism and IdentityStore that provide configurable support for common authentication and credential validation use cases, without the need to write custom implementations.

Because these SPIs, related annotations, and the CDI deployment mechanism are all part of standard Jakarta EE, implementations are completely portable (to the extent they do not rely internally on platform-specific APIs or libraries) and can be portably deployed to any Jakarta EE server.

Annotations enable a declarative style of programming and so encompass both the declarative and programmatic security concepts. Users can specify information about security within a class file by using annotations. GlassFish Server uses this information when the application is deployed. Not all security information can be specified by using annotations, however. Some information must be specified in the application deployment descriptors.

Specific annotations that can be used to specify security information within an enterprise bean class file are described in Securing an Enterprise Bean Using Declarative Security. Getting Started Securing Web Applications, describes how to use annotations to secure web applications where possible. Deployment descriptors are described only where necessary.

For more information on annotations, see Further Information about Security.

Declarative security can express an application component’s security requirements by using deployment descriptors. Because deployment descriptor information is declarative, it can be changed without the need to modify the source code. At runtime, the Jakarta EE server reads the deployment descriptor and acts upon the corresponding application, module, or component accordingly. Deployment descriptors must provide certain structural information for each component if this information has not been provided in annotations or is not to be defaulted.

This part of the tutorial does not document how to create deployment descriptors; it describes only the elements of the deployment descriptor relevant to security. NetBeans IDE provides tools for creating and modifying deployment descriptors.

Different types of components use different formats, or schemas, for their deployment descriptors. The security elements of deployment descriptors discussed in this tutorial include the following.

Programmatic security is embedded in an application and is used to make security decisions. Programmatic security is useful when declarative security alone is not sufficient to express the security model of an application. The API for programmatic security consists of methods of the Jakarta Security SecurityContext interface, and methods of the enterprise bean EJBContext interface and the servlet HttpServletRequest interface. These methods allow components to make business-logic decisions based on the security role of the caller or remote user.

Programmatic security is discussed in more detail in the following sections:

A realm is a security policy domain defined for a web or application server. A realm contains a collection of users, who may or may not be assigned to a group. Managing users in GlassFish Server is discussed in Managing Users and Groups in GlassFish Server.

An application will often prompt for a user name and password before allowing access to a protected resource. After the user name and password have been entered, that information is passed to the server, which either authenticates the user and sends the protected resource or does not authenticate the user, in which case access to the protected resource is denied. This type of user authentication is discussed in Specifying an Authentication Mechanism in the Deployment Descriptor.

In some applications, authorized users are assigned to roles. In this situation, the role assigned to the user in the application must be mapped to a principal or group defined on the application server. Figure 6, “Mapping Roles to Users and Groups” shows this. More information on mapping roles to users and groups can be found in Setting Up Security Roles.

The following sections provide more information on realms, users, groups, and roles.

Follow these steps for managing users before you run the tutorial examples.

When you design an enterprise bean or web component, you should always think about the kinds of users who will access the component. For example, a web application for a human resources department might have a different request URL for someone who has been assigned the role of DEPT_ADMIN than for someone who has been assigned the role of DIRECTOR. The DEPT_ADMIN role may let you view employee data, but the DIRECTOR role enables you to modify employee data, including salary data. Each of these security roles is an abstract logical grouping of users that is defined by the person who assembles the application. When an application is deployed, the deployer will map the roles to security identities in the operational environment, as shown in Figure 6, “Mapping Roles to Users and Groups”.

For Jakarta EE components, you define security roles using the @DeclareRoles and @RolesAllowed metadata annotations.

The following is an example of an application in which the role of DEPT-ADMIN is authorized for methods that review employee payroll data, and the role of DIRECTOR is authorized for methods that change employee payroll data.

The enterprise bean would be annotated as shown in the following code:

For a servlet, you can use the @HttpConstraint annotation within the @ServletSecurity annotation to specify the roles that are allowed to access the servlet. For example, a servlet might be annotated as follows:

These annotations are discussed in more detail in Specifying Security for Basic Authentication Using Annotations and Securing an Enterprise Bean Using Declarative Security.

After users have provided their login information and the application has declared what roles are authorized to access protected parts of an application, the next step is to map the security role to the name of a user, or principal.

When you are developing a Jakarta EE application, you don’t need to know what categories of users have been defined for the realm in which the application will be run. In the Jakarta EE platform, the security architecture provides a mechanism for mapping the roles defined in the application to the users or groups defined in the runtime realm.

The role names used in the application are often the same as the group names defined in GlassFish Server. Jakarta Security requires that group principal names are mapped to roles of the same name by default. Accordingly, the Default Principal To Role Mapping setting is enabled by default on the Security page of the GlassFish Server Administration Console. All the tutorial security examples use default principal-to-role mapping. With that setting enabled, if the group name defined on GlassFish Server matches the role name defined in the application, there is no need to use the runtime deployment descriptor to provide a mapping. The application server will implicitly make this mapping, as long as the names of the groups and roles match.

If the role names used in an application are not the same as the group names defined on the server, use the runtime deployment descriptor to specify the mapping. The following example demonstrates how to do this mapping in the glassfish-web.xml file, which is the file used for web applications:

A role can be mapped to specific principals, specific groups, or both. The principal or group names must be valid principals or groups in the current default realm or in the realm specified in the login-config element. In this example, the role of Mascot used in the application is mapped to a principal, named Duke, that exists on the application server. Mapping a role to a specific principal is useful when the person occupying that role may change. For this application, you would need to modify only the runtime deployment descriptor rather than search and replace throughout the application for references to this principal.

Also in this example, the role of Admin is mapped to a group of users assigned the group name of Director. This is useful because the group of people authorized to access director-level administrative data has to be maintained only in GlassFish Server. The application developer does not need to know who these people are, but only needs to define the group of people who will be given access to the information.

The role-name must match the role-name in the security-role element of the corresponding deployment descriptor or the role name defined in a @DeclareRoles annotation.

As a general rule, you must address the following issues to enable SSL for a server.

An SSL HTTPS connector is already enabled in GlassFish Server.

For testing purposes and to verify that SSL support has been correctly installed, load the default introduction page with a URL that connects to the port defined in the server deployment descriptor:

The https in this URL indicates that the browser should be using the SSL protocol. The localhost in this example assumes that you are running the example on your local machine as part of the development process. The 8181 in this example is the secure port that was specified where the SSL connector was created. If you are using a different server or port, modify this value accordingly.

The first time that you load this application, the New Site Certificate or Security Alert dialog box appears. Click Next to move through the series of dialog boxes, and click Finish when you reach the last dialog box. The certificates will appear only the first time. When you accept the certificates, subsequent hits to this site assume that you still trust the content.