7.3. Security for Web Service Interactions
Developers that rely on JAX-RPC to exchange messages between Web service endpoints and clients leverage the security services provided by the J2EE platform. The J2EE platform supports the WS-I Basic Profile 1.0 specifications for secure interoperable Web service interactions. WS-I security compliance requires HTTPS and single hop security for a request and reply between a client and service. The Basic Profile requires that the transport layer of HTTPS be combined with additional mechanisms for basic and mutual authentication.
The J2EE platform provides Web tier and EJB tier endpoints with similar security mechanisms for Web services. Most J2EE developers should already be familiar with its security mechanisms, since the platform already provides transport layer security and authentication support for non-Web service interactions involving browsers and Web pages.
With Web service interactions, both the request and the reply may have security requirements. In addition, Web service endpoints must interact securely with other components and resources when processing requests. Developers may also leverage other J2EE platform security mechanisms, such as authorization, to design and build secure Web services.
7.3.1. Endpoint Programming Model
Let's first look at the endpoint programming model and see how to design and implement a secure Web service interaction on the J2EE platform, that is, how to authenticate and establish a secure HTTPS channel. As with any J2EE component, you can use declarative mechanisms to define the security for a Web service endpoint. Similarly, you may include programmatic security mechanisms in your Web service endpoints, and your service endpoint can leverage the platform's declarative mechanisms.
The key requirements for a secure Web service interaction are authentication and establishing a secure SSL channel for the interaction. Let's first examine how to secure the transport layer, and then we'll look at the available authentication mechanisms.
7.3.1.1. Securing the Transport Layer
SSL and Transport Layer Security (TLS) are key technologies in Web service interactions, and it is important to understand how to establish an SSL/TLS-protected interaction and authenticate clients. Note that TLS is an enhanced specification based on SSL. References to SSL refer to both SSL and TLS.
SSL is a standard mechanism for Web services that is available on virtually all application servers. This widely used, mature technology, which secures the communication channel between client and server, can satisfy many use cases for secure Web service communications. Since it works at the transport layer, SSL covers all information passed in the channel as part of a message exchange between a client and a service, including attachments.
Authentication is an important aspect of establishing an HTTPS connection. The J2EE platform supports the following authentication mechanisms for Web services using HTTPS:
The server authenticates itself to clients with SSL and makes its certificate available.
Mutual authentication with SSL, using the server certificate as well as the client certificate, so that both parties can authenticate to each other.
While browser-based Web applications rely on these same authentication mechanisms when accessing a Web site, Web services scenarios have some additional considerations. With Web services, the interaction use case is usually machine to machine; that is, it is an interaction between two application components with no human involvement. Machine-to-machine interactions have a different trust model from typical Web site interactions. In a machine-to-machine interaction, trust must be established proactively, since there can be no real-time interaction with a user about whether to trust a certificate. Ordinarily, when a user interacts with a Web site via a browser and the browser does not have the certificate for the site, the user is prompted about whether to trust the certificate. The user can accept or reject the certificate at that moment. With Web services, the individuals involved in the deployment of the Web service interaction must distribute and exchange the server certificate, and possibly the client certificate if mutual authentication is required, prior to the interaction occurrence. Since an interoperable standard for Web service certificate distribution and exchange does not exist, the J2EE platform does not require one. Certificates must be handled in a manner appropriate to the specific operational environment of the application.
A Web service can be implemented and deployed in either the Web tier or EJB tier. The security mechanisms are the same at the conceptual level but differ in the details. The endpoint type determines the mechanism for declaring that a Web service endpoint requires SSL. For a Web tier endpoint (a JAX-RPC service endpoint), you indicate you are using SSL by setting to CONFIDENTIAL the transport-guarantee subelement of a security-constraint element in the web.xml deployment descriptor. This setting enforces an SSL interaction with a Web service endpoint. (See Code Example 7.1.)
Code example 7.1. Requiring SSL for Web Tier Endpoints
Setting up SSL for EJB tier endpoints varies according to the particular application server. Generally, for EJB endpoints a developer uses a description subelement of the target EJB component to indicate that the component requires SSL when deployed. Although EJB endpoints are required to support SSL and mutual authentication, the specifications have not defined a standard, portable mechanism for enabling this. As a result, you must follow application server-specific mechanisms to indicate that an EJB endpoint requires SSL. Often, these are application server-specific deployment descriptor elements for EJB endpoints that are similar to the web.xml elements for Web tier endpoints.
7.3.1.2. Specifying Mutual Authentication
You can also specify HTTPS with mutual authentication for a Web service endpoint. For Web tier endpoints, you first specify a secure transport (see the previous section) and then, in the same deployment descriptor, set the auth-method element to CLIENT-CERT. (See Code Example 7.2.)
Code example 7.2. Requiring Mutual Authentication for Web Tier Endpoints
<login-config> <auth-method>CLIENT-CERT</auth-method> </login-config> |
The combination of the two settings—CONFIDENTIAL for transport-guarantee (see Code Example 7.1) and CLIENT-CERT for auth-method—enables mutual authentication. When set to these values, the containers for the client and the target service both provide digital certificates sufficient to authenticate each other. (These digital certificates contain client-specific identifying information.)
Specifying mutual authentication for EJB service endpoints is specific to each application server. Usually it is done in a similar manner to specifying mutual authentication for Web tier endpoints.
7.3.1.3. Specifying Basic and Hybrid Authentication
With basic authentication, a Web service endpoint requires a client to authenticate itself with a username and password. The type of the Web service endpoint determines how to specify requiring basic authentication for the service. For a Web tier (JAX-RPC) service endpoint, set the auth-method element to BASIC for the login configuration (login-config) element in the web.xml deployment descriptor, as shown in Code Example 7.3:
Code example 7.3. Requiring Basic Authentication for Web Tier Endpoints
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>some_realm_name</realm-name>
</login-config>
|
For a Web service with an EJB endpoint, you use the application server-specific mechanisms to require basic authentication. Often, each application server's deployment descriptor includes an element for authentication for an EJB service endpoint that is analogous to the web.xml auth-method element.
A Web service may also require hybrid authentication, which is when a client authenticates with basic authentication and SSL is the transport. The client authenticates with a username and password, the server authenticates with its digital certificate, and all of this occurs over a HTTPS connection. Hybrid authentication compensates for HTTP basic authentication's inability to protect passwords for confidentiality. This vulnerability can be overcome by running the authentication protocols over an SSL-protected session, essentially creating a hybrid authentication mechanism. The SSL-protected session ensures confidentiality for all message content, including the client authenticators, such as username and password.
Enabling hybrid authentication for a Web service endpoint generally requires two operations (both previously discussed): setting the transport to use the confidentiality mechanism of HTTPS and setting the authentication of the client to use basic authentication. For EJB endpoints, you use application server-specific mechanisms. For Web endpoints, you set deployment descriptor elements. Code Example 7.4 demonstrates how to configure hybrid authentication by combining the deployment descriptor choices for basic authentication and confidential transport.
Code example 7.4. Requiring SSL Hybrid Authentication for Web Tier Endpoints
When setting authentication requirements for a client, keep in mind that an endpoint can require a client to authenticate either by using basic authentication and supplying a username and password or by using mutual authentication with the client supplying a digital certificate. An endpoint cannot require a client to use both mechanisms.
When deploying an application that uses this type of hybrid authentication mechanism, it is important to properly set the security elements of the Web resource's deployment descriptor.
Ensure that you set up an SSL transport for each endpoint that requires basic authentication. Otherwise, the client authenticator is not fully protected. For example, for Web endpoints, ensure that the transport-guarantee element of each protected Web endpoint is set to CONFIDENTIAL for an application using a hybrid authentication mechanism.
7.3.1.4. Publicizing Security Policy
Just as it needs to describe its methods and related information in a WSDL document, a Web service endpoint also needs to describe its security policy and make that information available to clients. If the WSDL document does not express the policy information, then the service must use other means to make its requirements known so that clients can be designed and implemented with those requirements in mind and be able to interact with the service.
At the present time, a WSDL description contains minimal information about the security characteristics of an endpoint—just the HTTPS location specified in the endpoint URL. The security functionality specified by the WS-I Basic Profile 1.0 only requires that Web services using HTTPS have https in the URI of the location attribute of the address element in its wsdl:port description. See Code Example 7.5.
Code example 7.5. WSDL Security Description
Since current WSDL documents have no standard mechanism to indicate whether an endpoint requires basic or mutual authentication, such information needs to be made available through service-level agreements between the client and endpoint. Future versions of the WSDL description may be extended to include descriptions of endpoint security requirements, perhaps by using metadata or annotations similar to CSIv2.
Since the present WSDL description for security is limited, you need to consider what other mechanisms you can use today to define security policies for endpoints. Generally, you should try to use the security mechanisms included with a particular vendor's application server. You have available options such as providing some metadata in another location, making some security assumptions among your partners, including security descriptions as a nonstandard part of JAXR entries, or even extending the WSDL description yourself. Not only that, your application and its endpoints may have built-in implicit assumptions, and you may need to provide a description of these unique security requirements. Clients need to be aware of all the requirements of a service so that they can be designed and implemented to interact properly with the service.
It is recommended that you list security assumptions and requirements in the description elements that are part of a service component's deployment descriptor.
In addition, have available for endpoint developers a separate document that describes the security policy for an endpoint. In this document, clearly describe the information needed by a client.
7.3.2. Client Programming Model
Client developers must handle some security requirements for their applications. The mechanisms for handling security vary according to the type of client. We focus on J2EE components, including enterprise bean and servlet components, acting as clients of Web services. J2EE clients can take advantage of the J2EE platform mechanisms when interacting with a Web service endpoint. You design and implement security for J2EE clients in the same way regardless of whether they interact with Java-based or non-Java-based Web services.
Other types of clients, such as non-Java or stand-alone J2SE clients, since they are not run within a J2EE container generally cannot use the services of the J2EE platform. Stand-alone J2SE clients can use the JAX-RPC technology outside of the J2EE platform if they include the JAX-RPC runtime in their stand-alone environment. If you develop a stand-alone J2SE client to be a Web service client, keep in mind that the J2SE platform provides its own set of services and tools to help you. You can use the Java Authentication and Authorization Service (JAAS), along with tools such as keytool, to manage certificates and other security artifacts. As just noted, you can also include the JAX-RPC runtime, then use its mechanisms to set up username and password properties in the appropriate stubs and make calls to the Web service. It is important to have your client follow the WS-I interoperability requirements, since doing so ensures that your client can communicate with any Web service endpoint that also satisfies the WS-I interoperability requirements.
The J2EE container provides support so that J2EE components, such as servlets and enterprise beans, can have secure interactions when they act as clients of Web service endpoints. The container provides this support regardless of whether or not the accessed Web service endpoint is based on Java. Let's look at how J2EE components use the JAX-RPC client APIs to invoke Web service endpoints in a secure manner.
As indicated in the section “Endpoint Programming Model” on page 308, a target endpoint defines some security constraints or requirements that a client must meet. For example, the client's interaction with the service endpoint might require basic authentication and HTTPS, or the client must provide certain information to access the endpoint.
The first step for a client is to discover the security policy of the target endpoint. Since the WSDL document may not describe all security requirements (see “Publicizing Security Policy” on page 313), discovering the target endpoint's security policy is specific to each situation. Once you know the client's security requirements for interacting with the service, you can set up the client component environment to make available the appropriate artifacts. For example, if the Web service endpoint requires basic authentication, the calling client container places the username and password identifying information in the HTTP headers. Let's take a closer look at what happens with both basic and mutual authentication.
For HTTP basic authentication, application server-specific mechanisms, such as additional deployment descriptor elements, are used to set the client username and password. These vendor-specific deployment descriptors may statically define at deployment the username and password needed for basic authentication. However, at runtime this username and identifier combination may have no relation to the principal associated with the calling component. When the JAX-RPC call is made, the container puts the username and password values into the HTTP header. Keep in mind that the J2EE specifications recommend against using programmatic JAX-RPC APIs to set the username and password properties on stubs for J2EE components. Thus, J2EE application servers are not required to support components programmatically setting these identifier values.
If the endpoint requires mutual authentication, the application server instance environment is set at deployment with the proper certificates such that they are available to the J2EE container. Since a client component's deployment descriptors have no portable, cross-platform mechanism for setting these security artifacts, they must be set using the particular application server's own mechanisms. In other words, an enterprise bean or servlet component that interacts with a Web service requiring mutual authentication must, at deployment, make the appropriate digital certificates available to the component's host container. The client's container can then use these certificates when the component actually places the call to the service.
Once the environment is set, a J2EE component can make a secure call on a service endpoint in the same way that it ordinarily calls a Web service—it looks up the service using JNDI, sets any necessary parameters, and makes the call. (See Chapter 5 for details.) The J2EE container not only manages the HTTPS transport, it handles the authentication for the call using the digital certificate or the values specified in the deployment descriptor.
7.3.3. Propagating Component Identity
Web service endpoints and other components can be clients of other Web services and J2EE components. Any given endpoint may be in a chain of calls between components and Web service endpoints. Also, non-Web service J2EE components can make calls to Web services. Each call between components and endpoints may have an identity associated with it, and this identity may need to be propagated.
There are two cases of identity propagation, differentiated by the target of the call. Both cases start with a caller that is a J2EE component—including a component that is a Web service endpoint. In the first case, the J2EE component or endpoint calls a J2EE component that is not a Web service. In the second case, the J2EE component or Web service makes JAX-RPC calls to a Web service.
7.3.3.1. Propagating Identity to Non-Web Service Components
All J2EE components have an invocation identity, established by the container, that identifies them when they call other J2EE components. The container establishes this invocation identity using either the run-as(role-name) or use-caller-identity identity selection policy, both defined in the deployment descriptor. The container then uses either the calling component's identity (if the policy is to use the use-caller-identity) or, for run-as(role-name), a static identity previously designated at deployment from the principal identities mapped to the named security role.
Developers can define component identity selection policies for J2EE Web and EJB resources, including Web service endpoints. If you want to hold callers accountable for their actions, you should associate a use-caller-identity policy with component callers. Using the run-as(role-name) identity selection policy does not maintain the chain of traceability and may be used to afford the caller with the privileges of the component. Code Example 7.6 shows how to configure client identity selection policies in an enterprise bean deployment descriptor.
Code example 7.6. Configuring Identity Selection Policies for Enterprise Beans
Code Example 7.7 shows how to configure client identity selection policies in Web component deployment descriptors. If run-as is not explicitly specified, the use-caller-identity policy is assumed.
Code example 7.7. Configuring Identity Selection Policies for Web Components
<web-app>
<servlet>
<run-as>
<role-name> guest </role-name>
</run-as>
...
</servlet>
...
</web-app>
|
7.3.3.2. Propagating Identity to a Web Service
Protection domains help to understand how clients set identity for Web service calls. (See “Protection Domains” on page 300.) Recall that a protection domain establishes an authentication boundary around a set of entities that are assumed to trust each other. Entities within this boundary can safely communicate with each other without authenticating themselves. Authentication is only required when the boundary is crossed. However, Web services are considered outside of any protection domain.
When calling a Web service, be prepared to satisfy its security requirements. Web services are loosely coupled and it is more likely that a call to a service will cross protection domains.
Since Web service calls are likely to cross protection domains, identity propagation mechanisms (such as run-as and use_caller_identity) and security context are not useful and are not propagated to service endpoints. When a J2EE component acting as a Web service client specifies the run-as identity or the use-caller-identity, the container applies that identity only to the component's interactions with non-Web service components, such as enterprise beans. Some vendors may provide mechanisms to propagate identity across protection domains, but these mechanisms may not be portable.
This brings us to the question of how to establish identity for Web services. For the client making calls to a service that requires authentication, the client container provides the necessary artifacts, whether username and password for basic authentication or a digital certificate for mutual authentication. The container of the target Web service establishes the identity of calls to its service endpoint. The Web service bases this identity on the mapping principals designated by when the service was deployed, which may be based on either the client's username and password identity or the digital certificate attributes supplied by the client's container. However, since no standard mechanism exists for a target Web service to map an authenticated client to the identity of a component, each application server handles this mapping differently.
For example, Figure 7.4 illustrates how a caller identifier is propagated from clients to Web service endpoints and J2EE components. The initial client makes a request of Web service endpoint X. To fulfill the request, endpoint X makes a call on entity bean J, which in turn invokes a method on entity bean K. The client caller identifier A propagates from the endpoint through both entity beans. However, when entity bean K calls a method on service endpoint Y, since the Web service is not in the same protection domain, reauthentication must occur. Similarly, when endpoint X calls endpoint Z, the caller identifier cannot be propagated.
Applications can also use programmatic APIs to check client identity, and use that client identity to make identity decisions. For example, a Web tier endpoint, as well as other Web components, can use the getUserPrincipal method on the HttpServletRequest interface. An EJB endpoint, just like other enterprise bean components, can use the EJBContext method getCallerPrincipal. An application can use these methods to obtain information about the caller and then pass that information to business logic or use it to perform custom security checks.
7.3.4. Handling Authorization
Web service endpoints can restrict access to resources using the same declarative authorization mechanisms available to other J2EE components. From a security point of view, this capability facilitates integrating Web services with J2EE applications since the standard J2EE authorization mechanisms can be leveraged. When a Web service is called—and the calling client has been authenticated and its identity established—the container has the capability to check that the calling principal is authorized to access this service endpoint. A Web service is also free to leave its resources unprotected so that anyone can access its service.
Furthermore, components and resources accessed by the Web service endpoint may have their own access control policies, and these may differ from the endpoint's policies. The service endpoint's interaction with other components and resources is handled by the same mechanisms used by any J2EE component. That is, the authorization mechanisms for Web service endpoints are the same as for other components in the J2EE platform.
The tier on which your endpoint resides determines how you specify and configure access control. In general, to enable access control you specify a role and the resource you want protected. Components in both tiers specify a role in the same manner, using the security-role element as shown in Code Example 7.8. With Web tier endpoint components, access control entails specifying a URL pattern that determines the set of restricted resources. For EJB tier endpoints, you specify access control at the method level, and you can group together a set of method names that you want protected.
Code example 7.8. Configuring a Role for an Authorization Constraint
<security-role> <role-name>customer</role-name> </security-role> |
What does this mean in terms of a Web service's access control considerations? Your Web service access control policy may influence whether you implement the service as a Web tier or an EJB tier endpoint. For Web tier components, the granularity of security is specific to the resource and based on the URL for the Web resource. For EJB tier components, security granularity is at the method level, which is typically a finer-grained level of control.
Let's consider a Web service with an interface containing multiple methods, such as the one shown in Code Example 7.9, where you want different access policies for each method. For a service endpoint interface such as this you might want to permit the following: Any client can browse the catalog of items available for sale, only authorized customers—for example, those clients who have set up accounts—can place orders, and only administrators can alter the catalog data. If you implement the service with a Web tier endpoint, then each method has the same protection because access control is the same for all methods that are bound to the port at the endpoint's URL. To handle a service with an interface containing multiple methods and different access policies, consider creating separate Web services where each service handles a different set of authorization requirements.
You have more flexibility if you implement the same Web service that has an interface containing multiple methods with an EJB endpoint. By using an EJB endpoint, you can set different authorization requirements for each method. See the next section, “Controlling Access to Web Tier Endpoints,” and “Controlling Access to EJB Tier Endpoints” on page 323.
Code example 7.9. Interface Methods Requiring Different Access Control
Keep in mind, however, that both Web and EJB tier endpoints can use programmatic APIs for finer-grained security. If you are willing to write code for access control, then both types of endpoints can be designed to handle the same security capabilities. However, it is generally discouraged to embed security code and use the programmatic security APIs in a component. A better approach keeps the security policy externalized form the application code and uses the declarative services with deployment descriptors.
If you require finer-grained control for your access control policy, consider using an EJB endpoint, since it utilizes method-level control.
7.3.4.1. Controlling Access to Web Tier Endpoints
To control access to a Web component such as a Web service endpoint, the Web deployment descriptor specifies a security-constraint element with an auth-constraint subelement. Code Example 7.10 illustrates the definition of a protected resource in a Web component deployment descriptor. The descriptor specifies that only clients acting in the role of customer can access the URL /mywebservice. Note that this URL maps to all the methods in the service endpoint interface. Hence, all methods have the same access control.
Code example 7.10. Web Resource Authorization Configuration
In addition to controlling access to Web components, an application can provide unrestricted access to unprotected resources, such as a Web service endpoint, by omitting an authentication rule. Omitting authentication rules allows unauthenticated users to access Web components.
7.3.4.2. Controlling Access to EJB Tier Endpoints
The EJB deployment descriptors define security roles for an enterprise bean. These descriptors also specify, via the method-permission elements, the methods of a bean's home, component, and Web service endpoint interfaces that each security role is allowed to invoke.
Code Example 7.11 shows how to configure method-level access. The example specifies that the method submitOrder, which occurs on an interface of an enterprise bean Web service endpoint, requires that a caller belonging to the customer role must have authenticated to be granted access to the method. It is possible to further qualify method specifications so as to identify methods with overloaded names by parameter signature or to refer to methods of a specific interface of the enterprise bean. For example, you can specify that all methods of all interfaces (that is, remote, home, local, local home, and service) for a bean require authorization by using an asterisk (*) for the value in the method-name tag.
Code example 7.11. Enterprise Bean Authorization Configuration
Some applications also feature unprotected EJB endpoints and allow anonymous, unauthenticated users to access certain EJB resources. Use the unchecked element in the method-permission element to indicate that no authorization check is required. Code Example 7.12 demonstrates the use of the unchecked element.
Code example 7.12. Enterprise Bean Unchecked method-permission
<method-permission>
<unchecked/>
<method>
<ejb-name>PurchaseOrder</ejb-name>
<method-name>getCatalogInfo</method-name>
</method>
<method>
...
</method-permission>
|
In addition to defining authorization policy in the method-permission elements, you may also add method specifications to the exclude-list. Doing so denies access to these methods independent of caller identity and whether the methods are the subject of a method-permission element. Code Example 7.13 demonstrates the use of the exclude-list.
Code example 7.13. Enterprise Bean Excluded method-permission
<exclude-list>
<method>
<ejb-name>SpecialOrder</ejb-name>
<method-name>*</method-name>
</method>
<method>
...
</exclude-list>
|
7.3.5. JAX-RPC Security Guidelines
In addition to the guidelines noted previously, the following general guidelines sum up the JAX-RPC authentication and authorization considerations.
Apply the same access control rules to all access paths of a component. In addition, partition an application as necessary to enforce this guideline, unless there is some specific need to architect an application in a different fashion. When designing the access control rules for protected resources, take care to ensure that the authorization policy is consistently enforced across all the paths by which the resource may be accessed. Be particularly careful that a less-protected access method does not undermine the policy enforced by a more rigorously protected method.
Declarative security is preferable to programmatic security. Try to use declarative access control mechanisms since these mechanisms keep the business logic of the application separate from the security logic, thus making it easier for the deployer to understand and change the access policy without tampering with the application code. Generally, programmatic security is hard to maintain and enhance, plus it is not as portable as declarative security. Security programming is complex and difficult to write correctly, leading to a false sense of security. Use programmatic mechanisms for access control only when extra flexibility is required.
If you have multiple Web tier endpoints with varying authentication requirements, consider bundling them in different .war files. An application (deployed within an .ear file) may use multiple Web service endpoints. It is possible that you may require different authentication for these endpoints—some endpoints may require basic authentication, others may require a client certificate. Since a web.xml file can have only one type of authentication associated with its login configuration, you cannot put endpoints that require different authentication in a single .war file. Instead, group endpoints into .war files based on the type of client authentication they require. Because the J2EE platform permits multiple .war files in a single .ear file, you can put these .war files into the application .ear file.
Provide security policy descriptions in addition to those that the standard WSDL file provides. The WSDL file is required to publish only a Web service's HTTPS URL. It has no standard annotation describing whether the service endpoint requires basic or mutual authentication. Use the description elements of the deployment descriptor to make known the security requirements of your endpoints.
Be careful with the username and password information, because these properties can create a vulnerability when configuring a client component to use HTTP basic authentication. Username and password are sensitive security data, and the security of your system is compromised if they become known to the wrong party. For example, do not store username and password values in the application code or the deployment descriptor, and if deployment descriptors do include a username and password, be sure to store the deployment descriptors in a secure manner.
Consider using a “guarding” component between the interaction and processing layers. Set up an application accessor component with security attributes and place it in front of a set of components that require protection. Then, allow access to that set of components only through the guarding or front component. A guarding component can make application security more manageable by centralizing security access to a set of components in a single component.