You can secure the deployed resources in the web server via basic authentication by making the appropriate security entries in the web.xml descriptor file and also in the container (vendor)-specific deployment descriptor file (glassfish-web.xml, in this example).

Let's say we want to use basic authentication for one of the JAX-RS sample web service applications that we built in the previous chapters.

The first step is to update the web descriptor web.xml file to look as follows. Note that web.xml is found in the WEB-INF folder of your web application; you should generate a new one if it is found to be missing:

<?xml version="1.0" encoding="UTF-8"?> 
<web-app ...> 
   
    <security-constraint> 
        <web-resource-collection> 
            <web-resource-name> 
                Protected resource 
            </web-resource-name> 
            <url-pattern>/*</url-pattern> 
            <http-method>GET</http-method> 
        </web-resource-collection> 
 
        <auth-constraint> 
            <!-- role name that authorized users belongs to--> 
            <role-name>APIUser</role-name> 
        </auth-constraint> 
        <!-- /added --> 
        <!-- Use it only if you use https --> 
        <user-data-constraint> 
            <transport-guarantee> 
              CONFIDENTIAL 
           </transport-guarantee> 
        </user-data-constraint>  
    </security-constraint> 
    
    <login-config> 
        <auth-method>BASIC</auth-method> 
        <!-- realm name used in GlassFish --> 
        <realm-name>file</realm-name> 
    </login-config> 
    <security-role> 
        <role-name>APIUser</role-name> 
    </security-role> 
</web-app> 

Here is a quick summary of the core elements that you saw in the preceding web.xml file:

• The <security-constraint> element in web.xml is used to secure a collection of resources by restricting the access to them with the appropriate URL mapping:
  • The <web-resource-collection> subelement describes the protected resources in the application, which are identified via URL patterns and HTTP methods.
  • The subelement, <auth-constraint>, defines the user roles that are authorized to access constrained resources.
  • The subelement, <user-data-constraint>, defines how the data is protected in the transmission channel. It takes the following values: CONFIDENTIAL, INTEGRAL, or NONE. CONFIDENTIAL and INTEGRAL are treated in the same way by the Java EE container, and these values imply the use of the Transport Layer Security (TLS) (HTTPS) to all incoming requests matching the URL patterns present in <web-resource-collection>.

• The element, <login-config>, defines the login configurations used in the application:
  • The subelement, <realm-name>, refers to a collection of security information checked for authenticating the user when a secured page (resource) is accessed at runtime. The realm name that you enter should match with the security realm that you configured on the server.
  • The subelement, <auth-method>, defines the authorization method used in the application. The possible values are as follows:
    • BASIC: This is the HTTP basic authentication that we discussed a while ago.
    • DIGEST: This is the same as HTTP basic authentication, except that instead of a password, the client sends a cryptographic hash of user credentials along with the username.
    • FORM: This uses an HTML form for login, with field names that match the specific convention. For instance, j_username and j_password are used as names for the username and password fields respectively.
    • CLIENT-CERT: This uses a client digital certificate or other custom tokens in order to authenticate a user.

• The element, <security-role>, defines all the security roles used in the application.

Let's get back to the configurations for basic authentication that we were discussing. The web.xml file that we used for this example is read by the web server to infer that the web application uses basic authentication and that any URI access must be authenticated for the role name, APIUser. This means that to access the URI, http://hostname:port/rest-chapter6-service/webresources/hr/departments, the user should belong to the APIUser role.

We have not yet finished the configuration entries for the web application. The following step is to map the role that we specified in web.xml (APIUser) to the user groups that we will define on the server. This configuration is done on the vendor-specific deployment descriptor, glassfish-web.xml:

<?xml version="1.0" encoding="UTF-8"?> 
<glassfish-web-app error-url=""> 
    <!-- Other entries go here --> 
    <security-role-mapping> 
        <!-- maps "Users" group to APIUser --> 
        <role-name>APIUser</role-name> 
        <group-name>Users</group-name> 
    </security-role-mapping>  
</glassfish-web-app> 

While configuring the security realm on the server, we should map the actual users of the application to the user groups as appropriate. This is explained in the next section. Though the basic concepts of the security configuration remain the same across various Java EE servers, the actual steps may vary. This example takes GlassFish as a server and explains the security configurations in the next section.