Creating file realm users in JBoss

As promised in an earlier post, I'll show you how to create file realm users in the JBoss application server. A realm is a database that contains user, password, and role information. The application server can use this information to identify users in order to provide container managed security to applications. Realm information can be stored and retrieved in various ways:

• JDBC
  
• Datasource
  
• JNDI
  
• File (JBoss calls this MemoryRealm)
  
• JAAS
  

We'll be only discussing File realm for this blogpost. When you use File realm, the information is stored in a plain text file.

1. Create a realm
The first step is to create a realm by editing server.xml in your deployment directory of your server. For this example, we'll use the default server configuration in the directory: <JBOSS_DIR>/server/default/deploy/jbossweb.sar. Decide if the realm is shared by applications. You can share it at three different levels:

• Shared across all applications on all virtual hosts (<Engine>)
  
• Shared across all applications on a particular host (<Host>)
  
• Not shared, only used by one application (<Context>)
  

Create and place the <realm>-element nested in one of the elements mentioned above. Example: if you want the realm to be shared for all applictions on a host, you nest the <realm>-element in <host>.

<realm
 className="org.apache.catalina.realm.MemoryRealm"
 digest="" pathname="conf/users.xml" />

It is recommended to specify a digest to store the passwords encrypted, otherwise the passwords will be stored in clear text. If the attribute pathname is not specified, the default file conf/tomcat-users.xml is used.

2. Create file with users
Create the file specified in the realm configuration, and add users to the file in the following format:

<tomcat-users>
  <user name="john"
   password="secret"
   roles="user" />
  <user name="peter"
   password="secret"
   roles="admin"  />
  <user name="carol"
   password="secret"
   roles="role,role2" />
</tomcat-users>

3. Restart JBoss
The realm becomes active when JBoss is restarted.

Securing JAX-WS web services in Eclipse

In this tutorial, we're going to secure the web service created in previous blogposts. If you don't have done that already, please go through the previous two blogposts, because this blogpost will build on the web service created there. We're using container managed security to achieve security. The tutorial consists of three parts. In the first part, we will implement BASIC authentication. In the second part we extend BASIC authentication with Secure Socket Layer (SSL). In the third part, we replace BASIC authentication with mutual authentication using certificates.

PART 1: BASIC authentication

Steps:

1. Create realm users
   
2. Modify server application for BASIC authentication
   
3. Modify client application for BASIC authentication
   

1. Create realm users
In this step we're creating users that are authorized to use the web service. The steps described here are only applicable for the Glassfish application server. I will describe the steps needed for the JBoss application server in a future blogpost.

First, make sure Glassfish is running, and go to the admin console or interface. Use the menu tree on the left to browse to: Security -> Realm -> file



Now in the next screen, click on "Manage Users".



This will take you to the screen "File Users". Click on "New..." to create a new user. In this example, create an user "peter" in the group "wsusers". The password is "qwerty1".



Finally, click "Finish". Now, we have completed creating an user in Glassfish.

2. Modify server application for BASIC authentication
In this step, we have to modify two files: web.xml and sun-web.xml. If you don't have these files, just create them under the WEB-INF directory. In the web.xml file, we protect the web service by adding: a security constraint, login configuration, and roles. To do this, we add the following code directly nested in <web-app>:

<!-- Security constraint for resource only accessible to role -->
<security-constraint>
  <display-name>WebServiceSecurity</display-name>

  <web-resource-collection>
    <web-resource-name>Authorized users only</web-resource-name>
    <url-pattern>/ExampleWSService</url-pattern>
    <http-method>POST</http-method>
  </web-resource-collection>

  <auth-constraint>
    <role-name>user</role-name>
  </auth-constraint>

</security-constraint>  

<!-- BASIC authorization -->
<login-config>
  <auth-method>BASIC</auth-method>
</login-config>

<!-- Definition of role -->
<security-role>
  <role-name>user</role-name>
</security-role>

In the file sun-web.xml, we map the user group created in the application server to the role "user". Put the following code directly under <sun-web-app>:

<security-role-mapping>
  <role-name>user</role-name>
  <group-name>wsusers</group-name>
</security-role-mapping>

At this point, you can deploy the application and test it with the web service client. If correct, a 404-authorization error will be displayed when the client tries to connect to the web service.

3. Modify client application for BASIC authentication
In this step, we're going to supply an username and password when connecting to a web service in the client. The altered start() method in the file WebServiceClient.java should look like this:

public void start() {
    // This statement is not needed when run in container.
    service = new ExampleWSService();
    ExampleWS port = service.getExampleWSPort();

    // Authentication
    BindingProvider bindProv = (BindingProvider) port;
    Map<String, Object> context = bindProv.getRequestContext();
    context.put("javax.xml.ws.security.auth.username", "peter");
    context.put("javax.xml.ws.security.auth.password", "qwerty1");

    System.out.println(port.greet("Peter"));
    System.out.println(port.multiply(3, 4));
}

If we run the client now, we notice that we can successfully connect to the web service without getting authorization errors.

PART 2: Implementing Secure Socket Layer (SSL)

Now, we continue to add Transport Level Security (TLS) using SSL to encrypt the transportation channel. This will prevent eavesdropping and tampering communication data between client and server.

Steps:

1. Export server certificate from server keystore
   
2. Create client truststore and import server certificate
   
3. Modify server application for SSL
   
4. Modify client application for SSL
   

1. Export server certificate from server keystore
Open a command prompt and navigate to the root directory of the client. Create a new directory called "server" with the command "mkdir server" and navigate into it. This will be our working directory when manipulating the server keystore/truststore. Copy the following files from the Glassfish_installation/domains/domain1/config directory to the newly created server directory: cacerts.jks (truststore) and keystore.jks (keystore).

Now, we can use the keytool to export the server certificate from the server keystore using the default store password "changeit":

keytool -export -alias s1as -keystore keystore.jks
        -storepass changeit -file server.cer

The exported server certificate is now written to the file server.cer.

2. Create client truststore and import server certificate
The next step is to create the client truststore and import the server certificate to it. Create a "client" directory in the root directory of the client, and navigate to it using the command prompt. Now use the keytool to create the client truststore and import the server certificate:

keytool -import -v -trustcacerts -alias s1as -keypass changeit
        -file ../server/server.cer -keystore client_cacerts.jks
        -storepass changeit

When prompted to trust the certificate, type "yes" and press enter to accept.


3. Modify server application for SSL
Add the following code under the <security-constraint>-element in web.xml to enable SSL:

<user-data-constraint>
  <transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>

When you run the client now, you'll get a 302-error, indicating that the resource has moved.

4. Modify client application for SSL
Edit ExampleWSService.java (generated by wsimport) and lookup the WSDL-URL in the code. Replace the URL with:

https://localhost:8181/webservice/ExampleWSService?wsdl

Save and use the following VM parameters to run the client:

-Djavax.net.ssl.trustStore=client/client_cacerts.jks
-Djavax.net.ssl.trustStorePassword=changeit

You can configure the VM parameters in Eclipse here: Run -> Run Configurations



PART 3: Mutual authentication

In the final part, we're replacing the BASIC authentication with mutual authentication with certificates.

Steps:

1. Create client keystore
   
2. Export client certificate
   
3. Import client certificate into server truststore
   
4. Modify server application for mutual authentication
   
5. Modify client application for mutual authentication
   
6. Configure Glassfish for mutual authentication
   

1. Create client keystore
Now, create a client keystore to store its own certificate.

keytool -genkey -alias client -keypass changeit
        -storepass changeit -keystore client_keystore.jks

Use the following values to answer questions when prompted:



2. Export client certificate
Navigate to the "client" directory with the command prompt. The client certificate is needed on the server side. So we need to export it from the client keystore using the following command:

keytool -export -alias client -keystore client_keystore.jks
        -storepass changeit -file client.cer

3. Import client certificate into server truststore
Navigate to the "server" directory and import the client certificate with the command:

keytool -import -v -trustcacerts -alias client
        -keystore cacerts.jks -keypass changeit
        -file ../client/client.cer

Use the default password "changeit" when asked, and finally type "yes" to accept the certificate.

4. Modify server application for mutual authentication
The file web.xml has to be changed for mutual authentication configuration. Lookup the <auth-method>-element and replace BASIC with CLIENT-CERT.

The sun-web.xml file has also to be modified. Instead of mapping the role to a realm group, we have to map the role to a certificate with the <principal-name>-element:

<sun-web-app>
  <security-role-mapping>
    <role-name>user</role-name>
      <!-- <group-name>wsusers</group-name> -->
    <principal-name>CN=Name, OU=Department,
     O=Organization, L=City, ST=State,
     C=nl</principal-name>
  </security-role-mapping>
</sun-web-app>

5. Modify client application for mutual authentication
The username and password we used in the client code for part 1 are not used anymore. So we can remove that part.

The client is now finished, and can be run with the following VM-settings:

-Djavax.net.ssl.keyStore=client/client_keystore.jks
-Djavax.net.ssl.keyStorePassword=changeit

6. Configure Glassfish for mutual authentication
If you experience connection problems when using the client, you're probably using the default Glassfish installation. By default, mutual authentication is disabled. To enable mutual authentication, go to: Configuration -> Network Listeners -> http-listener-2. Click the SSL tab. Make sure "SSL3" is not checked. The checkboxes "TLS" and "Client Authentication" should be checked.



Everything should be working now. In a future blogpost, I will show you how to configure realm users for JBoss.

Web service client with JAX-WS in Eclipse

In this blogpost, I will use JAX-WS to show how easy it is to create a simple client that makes use of the web service we created in the previous blogpost. The client can be implemented in various ways, like a web application or an EJB. In both mentioned ways, you run the client in a Java container. Therefore, you can take advantage of the resource injection facility provided by the container. This means you can use annotations to automatically inject the web service object where needed. We start out by creating a standard client, which does not run in a container.

Let's get started by creating a standard Java project in Eclipse. When done, start up a command prompt and navigate it to the root directory of the newly created project. Use the wsimport command to generate the classes you need to access the web service. You need the URL of the WSDL for this to work. The following command generates the sources and classes, and place them in the default Eclipse directories.

wsimport -s src
         -d bin
         http://localhost:8080/webservice/ExampleWSService?wsdl

Now, create a new class, which acts as the client. An example client:

package com.javaeenotes;

import javax.xml.ws.WebServiceRef;


public class WebserviceClient {

    // This annotation only has effect in a container.
    @WebServiceRef(
        wsdlLocation =
        "http://127.0.0.1:8080/webservice/ExampleWSService?wsdl"
    )
    private static ExampleWSService service;

    public static void main(String[] args) {
        WebserviceClient wsc = new WebserviceClient();
        wsc.start();
    }

    public void start() {
        // This statement is not needed when run in container.
        service = new ExampleWSService();
        ExampleWS port = service.getExampleWSPort();
        System.out.println(port.greet("Peter"));
        System.out.println(port.multiply(3, 4));
    }
}

The resource injection annotation is not necessary here, because the client does not run in a container. I left it here to show how to use annotation to inject the resource into your class when run in a container.

Web service with JAX-WS in Eclipse

In this tutorial, I'll show you how to use JAX-WS to build a web service in Eclipse. JAX-WS stands for Java API for XML Web Services. You can use it to build web services and clients that communicate using XML messages. We are not using the built-in web service generation tool provided by Eclipse. How to build a sample client will be explained in a future blog post.

The basic steps for building a web service:

1. Code the implementation class
   
2. Annotate the class
   
3. Use wsgen to generate web service artifacts
   
4. Deploy in Glassfish from Eclipse
   

1. Code the implementation class

First create a dynamic web project in Eclipse. I called my project webservice, but you call your project anything you like. Make sure the target runtime is Glassfish, and select Minimal Configuration in the configuration screen.



In the next screen, accept the default output folder or choose a custom one. Memorize the output folder, because we need this when we generate the web service artifacts.




You don't have to select the last checkbox to auto generate the web.xml deployment descriptor, but you'll need it when your application is also a web application.



Click finish, and your project is ready to use.
Create a new class in the newly created project. This will be the implementation class of the web service. I called mine ExampleWS.



2. Annotate the class

Now it's time to complete the class and use JAX-WS annotation to make it a valid web service.

package com.javaeenotes;

import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService
public class ExampleWS {
    
    @WebMethod
    public int sum(int a, int b) {
        return a + b;
    }

    @WebMethod
    public int multiply(int a, int b) {
        return a * b;
    }

    @WebMethod
    public String greet(String name) {
        return "Hello " + name + "!";
    }
}

3. Use wsgen to generate web service artifacts

Start a command prompt and navigate to the root of the project directory. Make sure the JDK is in your PATH, or else you can't execute the wsgen command. Create a wsdl directory in WebContent/WEB-INF/ or else wsgen will complain. Use the wsgen command to generate the artifacts like this:

wsgen -classpath build/classes/ -wsdl
      -r WebContent/WEB-INF/wsdl -s src
      -d build/classes/ com.javaeenotes.ExampleWS

This command will generate the source, class files, and WSDL file for the web service implemented as com.javaeenotes.ExampleWS. When wsgen complains about not finding the class, you have to build the project first. When the command is successful, you can refresh the project and you'll find the artifacts in your project tree.

The generated WSDL-file needs some editting, before you can use it. Open the WSDL-file and search for REPLACE_WITH_ACTUAL_URL. Replace this string with the web service URL: http://127.0.0.1:8080/webservice/ExampleWSService, and save the file.

4. Deploy in Glassfish from Eclipse

I assume you have Glassfish integrated in Eclipse, or else you have to build a WAR-file using ANT and manually deploy it into Glassfish. There is a blog post about integrating Glassfish into Eclipse. You can use the search engine to find it.

Deploy the project in Glassfish by right-clicking the project, click Run As, and finally Run on Server. Select the Glassfish server in the selection screen, and complete this step. When the configuration is finished, Eclipse tries to open a web page, which fails with a 404 error. Don't worry, this is normal, because we just created a web application without pages. Our project contains only a web service.

We can test the newly created web service by using SOAP-UI or the integrated Web Services Explorer in Eclipse. To use the Web Sercice Explorer in Eclipse, browse to the WSDL-file, right-click on it, select Web Services, and click on Test with Web Services Explorer. This will present you the web services test screen, which is pretty easy to use.