The IBM® DB2® Web Service provider (or WORF - Web Services object runtime framework) lets users easily expose database data and stored procedures as Web Services. The user writes XML files containing the database operations that make up Web Service transactions. Such operations can be SELECT statements, INSERT/UPDATE/DELETE statements, stored procedures and XML Extender operations. This article describes how you restrict users access to these database operations that could update or retrieve data from the database.
Web Services are a message-oriented communication framework that is designed to be very interoperable and extensible.
Messages are exchanged in XML and specifically described by SOAP (Simple Object Access Protocol). SOAP messages consist of an envelope that contains a header and a body. The header can contain some metadata about the message, which could be a transaction ID or encryption keys. The body contains the actual message, which could be an order or an insurance quote.
The actual interface of a Web Service provider is described in the Web Service Description Language (WSDL). This is very similar to a header file in the C programming language. The WSDL tells a user the operations that a Web Service provider understands and what the inputs and outputs are for this operation. It also contains new type definitions specific to Web Service.
Knowing the WSDL, a user can create the XML for a SOAP request message. The user also knows what XML to expect from the SOAP response. There are usually tools used to construct the SOAP request and extract data from the SOAP response. Examples of these tools are WebSphere® Studio and Microsoft® Visual Studio .NET. See the references for an article that explains how to use the DB2 Web Service provider with Visual Studio .NET.
Usually SOAP messages are sent over HTTP, but there are other kinds of possible transports, such as WebSphere MQ.
Because of the extensive use of standards such as HTTP and XML the Web Services are very interoperable. You can mix an operation system, application server and development tools for both the server and the client side. You do not need to install client code such as a database driver, to access a Web Service.
The DB2 Web Service provider is an extension to Java™ application servers such as WebSphere Application Server and Jakarta Tomcat. The Web Service Provider will let you write the database operations in XML files and handles the transformation of these into a Web Service. An example of such an XML file, a DADX (document access definition extension) file, looks like this:
Listing 1. A simple DADX file
<?xml version="1.0"?>
<DADX xmlns="http://schemas.ibm.com/db2/dxx/dadx" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<documentation>List contents of DEPARTMENT table.</documentation>
<operation name="listDepartments">
<documentation>Lists each department.</documentation>
<query>
<SQL_query>SELECT * FROM DEPARTMENT WHERE deptno=:deptno</SQL_query>
<parameter name="deptno" type="xsd:string" kind="in" />
</query>
</operation>
</DADX>
|
The Web Service Provider runtime does the following things at runtime:
- Creates the WSDL from the DADX file
- Creates a browser based test environment from the DADX
- Uses the DADX file as the implementation of the Web Service.
Since the user just has to write the DADX file, the user does not need to understand the WSDL specification. A WSDL for a moderately complex DADX can be many pages long. The runtime will determine the parameters to an SQL operation (such as the deptno in the example) and also analyze metadata of the SQL resultset to create the right XML output types.
The user would complete the following steps to create a DADX application:
- Create a DADX file
- Create and deploy a Web application
- Access the browser-based Test environment, e.g., http://localhost:9080/services/sample/list.dadx/TEST
- Modify the DADX in the Web application and invoke tests again
The query in the DADX works as an implementation, because the runtime executes the query and formats the result in XML. This means that the user doesn't have to write code in a programming language and understand the programming model of the Web Service engine. If the user wanted to write a Web Service for WebSphere himself, he would need to write Java code or an Enterprise Java Bean (EJB) to invoke the SQL.
The URL that is used to access the test environment contains the the DADX name (e.g., list.dadx) and other parts. One other part is "services," which is the name or context root of the Web application the DADX lives in. The other part (mydatabase) is a group name. A group is a container for DADX files in a Web application. Groups share configuration settings, such as the database user that is used to connect to the database. We will see later how this database user is configured.
Security of a Web application or a Web Service application can consist of many parts. Many of these security aspects are known to a database administrator. This section explains how this works in WebSphere. The things we focus on here are:
- Identification/Authentication
- Authorization
- Integrity/Confidentiality
Identification means that you tell the service who you are. For example, you can connect as user "dirk." Of course that doesn't mean much without authentication where you supply a proof that shows that you really are who you claim you are. This proof could be a password or some security token. This is well known to database users in the SQL command "CONNECT TO sample USER dirk USING mypassword."
Authorization deals with allowing or disallowing certain things for users. In database systems this is done with "GRANT" statements. We will explain how the user would do something like "GRANT SELECT, INSERT ON CALENDAR TO USER PHIL" in the Web Service context.
Integrity is a means of ensuring that the message has not been tempered with. By using Confidentiality we can make sure that nobody can read the message that is sent over insecure communication channels. One example to ensure confidentiality is to use encryption.
You can achieve Web Services security two ways:
- Transport-level security
- Message-level security
Transport-level security means that security mechanisms are achieved with methods that the transport provides. For example, you can achieve confidentially by using HTTPS (secure HTTP). HTTPS will encrypt all the HTTP messages that are exchanged. If the Web Service switches to another transport such as insecure HTTP that does not have an encrypted communication channel, then the message is transmitted again in clear text.
This article explains how to set up transport-level security for the DB2 Web Service provider. There's no message-level security, but we are going to look at this upcoming feature.
Because you also want security on insecure transports you use message-level security mechanisms such as WS-Security. WS-Security allows the user to use a variety of security elements, such as user names, signature and encryption mechanisms and security tokens. In comparison to transport-level security WS-Security allows the user only to encrypt parts of the message (e.g., the credit card number) and not the whole communication between the client and server. It also allows for different identification and authentication mechanisms.
Figure 1. WS Security roadmap
As Figure 1 shows, WS-Security is a Web Service security standard on which other Web Services security standards are built. IBM and Microsoft published this roadmap to WS Security (see references section). The other standards can be briefly described, as following:
- WS-Policy: Describes the capabilities and constraints of the security (and other business) policies on intermediaries and endpoints (e.g., required security tokens, supported encryption algorithms, privacy rules).
- WS-Trust: Describes a framework for trust models that enables Web Services to securely interoperate.
- WS-Privacy: Describes a model for how Web Services and requestors state subject privacy preferences and organizational privacy practice statements..
- WS-SecureConversation: Describes how to manage and authenticate message exchanges between parties, including security context exchange and establishing and deriving session keys.
- WS-Federation: Describes how to manage and broker the trust relationships in a heterogeneous federated environment, including support for federated identities.
- WS-Authorization: Describes how to manage authorization data and authorization policies.
In the next section, we discuss the problems that arise with DB2 Web Service provider security and show how to address this in WebSphere.
Implementing Web Services security in WebSphere
Security problems with the DB2 Web Service provider
The problems of an administrator who sets up security for the DB2 Web Service provider are the problem of identification and authentication, which we have already mentioned. We are going to solve this by requiring the user to have the client authenticate with HTTP authentication. HTTP authentication means that the HTTP request has to have an HTTP header field with the userid and password. When you encounter a Web page in a browser that requires authentication you usually get a dialog box that lets you enter your userid and password for this Web page. In the case of SOAP, the client program has to be modified to send the userid and password.
We address authorization by using the J2EE (Java enterprise edition) mechanism of authorization for URLs. Since all of the Web Service requests are based on sending a message to a certain URL, we can configure the Web application so that only certain users can send requests to a certain URL. A URL could be either one DADX or a whole group of DADX files. We'll discuss in detail later.
Confidentiality and integrity can simply be solved by requiring the user to use HTTPS. This means that all network traffic is encrypted, and tampering with messages is also detected.
There is one last problem of mapping the users that authenticate with WebSphere to a database user that executes the statements in a DADX. Since our runtime cannot determine the userid and password that is used in HTTP authentication, we cannot use this to connect to the database. In some cases this is not even realistic if the application server users are different from database users. An example is the case that the application server and database server run on different machines and both use the operating system as a user registry. Instead, on a group (that contains multiple DADX files) you can specify one userid and password. This user will be used to execute all SQL statements in DADXes in that group. If you want to distinguish users who execute SQL, you can create a separate group, such as a group for users in accounting and one for users in engineering.
For the following steps we assume that you have extracted dxxworf.zip from the sqllib\samples\java\Websphere directory in your DB2 V8 installation to c:\worf as the installation recommends. You have also followed the installation instructions. You don't need to install the sample Web application services.war, since we modify that in the next steps. It is acceptable if you already deployed services.war, because we're going deploy the sample war as a different Web application.
We are going to use the Application Server Toolkit (ASTK) to modify the sample war file to add security constraints. ASTK is very similar to WebSphere Studio, so if users prefer WebSphere Studio they can use this. The first step is to import the sample war file into ASTK. This is described in Figure 2.
Figure 2. Import the sample war file
Enter the location of the war file that you want to add security constraints to.
Figure 3. Specify the war file location
We create a new Web application with the name "SecureDADX" that will contain the DADX files and other configuration files.
Figure 4. Specify a Web application name
Also migrate the sample war file that conforms from J2EE 1.2 to J2EE 1.3. Select the SecureDADX Web Module and do a right-click and select Migrate and J2EE Migration wizard. This allows us to use WebSphere 5 DataSources later.
Now that we have imported the Web application, we can modify it for security. The next step is the set up of the database connection in the war file.
The database user is configured for the whole group of DADX files. You can set up the database users either by entering the userid and password in clear text or base64-encoded in the configuration file called group.properties. But even with encoding, this provides no real security because the password is not encrypted. The remedy is to set up the Web Service Provider to use a DataSource and then set up the user for that DataSource in WebSphere. An additional advantage of this approach is that you can use connection pooling with DataSources.
As a next step open the group configuration file for the dxx_sample group as shown in Figure 5. You have to switch to the "Project Navigator" view on the left/middle of the window to see all the files in the project. The path to that file is "SecureDADX/Java Resources/groups.dxx_sample/group.properties". Modify the first two configuration parameters to this:
initialContextFactory=com.ibm.websphere.naming.WsnInitialContextFactory
datasourceJNDI=jdbc/sampleDataSource
The first parameter, "initialContextFactory," is needed to access the JNDI (Java Naming and Directory Interface) in WebSphere. The second parameter "datasourceJNDI" is the name of the datasource in JNDI. We will configure the datasource with that name later in WebSphere.
Figure 5. Modify the group.properties
We're going to complete the DataSource setup in WebSphere in a later step when we work with the WebSphere administration console.
The next steps modify the deployment descriptor of your Web application. Click on the J2EEHiearchy tab on the lower left-hand side of the window and then double-click on the Web application SecureDADX, as Figure 6 shows. This opens the Web application deployment descriptor editor. Click on the Security tab to edit security settings.
Figure 6. Open the Web application deployment descriptor
The next step creates a new role. A role is a collection of users similar to groups in operating systems. In this example we create one role, "DADXUser," to contain all the users that are allowed to access the DADXes. In a real-world application you would probably create roles like "accounting," "engineering" and "administrator" and then allow them to access different DADX files.
Figure 7. Add a role and name it
After you create the role, click on the Security constraints tab in the editor. Security constraints are similar to "GRANT" statements in the database. A difference is that they work on URLs instead of tables, stored procedures and other database objects. We create a security contstraint for a whole DADX group. That is why the URL pattern says "/db2sample/,*" which is the URL path for all URLs in the dxx_sample group (Note: there is a mapping from dxx_sample to the db2sample URL in the web.xml deployment descriptor file).
You can use other options for URL patterns, such as "/*" if you want to secure the whole Web application with the same constraint. Or you could use "/db2sample/myDADX.dadx/*" if you want to secure a certain DADX with that security constraint. You can have multiple security constraints, so it's possible to put all the read operations in one DADX file and the write operations in another and then require the user to be in a certain role to be allowed to do reads or updates.
The next 3 figures show how to add the security constraint (Figure 8), how to set the right URL and HTTP methods (Figure 9) and how to allow the role "DADXUser" for that constraint (Figure 10).
Figure 8. Add a security constraint
Figure 9. Add a new resource constraint
Figure 10. Set the authorized roles
The next step is to set the confidentiality for our Web application.
In the "User Data Constraints" section you can set the type to "Confidential". This means that all communication will be done with HTTPS. This will assure that nobody can read the message that is send over a public network.
Figure 10. Set confidentiality
The last step is to require users to authenticate whenever they refer to Web pages, WSDLs and Web Services in our Web application.
In the Web application deployment descriptor editor click on the "Pages" tab and set the authentication type to Basic. This means the Web Service client or Web browser needs to provide a userid and password in the HTTP headers.
Figure 11. Set authentication
In the final steps, we open the Enterprise Application deployment descriptor by double-clicking on "DefaultEAR", as shown in Figure 12.
Figure 12. Open the Application deployment descriptor
In the EAR deployment descriptor editor we first "Gather" the security roles from the web applications or war files that it contains (Figure 13) . After that we add a user to that role (Figure 14) by selecting "DADXUser" in the role list and then click on the "Add" button under "Users/Groups". It is also possible to put a group of users in a role that way. Note that if the EAR is deployed on multiple machines where users are not necessarily the same, you can still change the role to a user or group mapping at deployment time.
Figure 13. Gather roles
Figure 14. Add a user to a role
We have completed our EAR setup in ASTK. The only remaining step is save the EAR deployment descriptor and to export the EAR file to the files system for deployment in WebSphere.
Figure 15. Export the EAR file
Figure 16. Specify the EAR file name
The application setup is almost complete. We still need to configure security in WebSphere, deploy our application and then test it.
You configure WebSphere with the WebSphere administration console, which is browser based. If your installed WebSphere with the defaults, the location is http://localhost:9090/admin/. We are going to enable the security, finish the DataSource setup and finally deploy the EAR that we created. If you are doing this on a WebSphere installation it is a good idea to use the backupConfig utility to back up the old, working configuration. Please refer to your WebSphere documentation about this.
The first step is to switch on security in WebSphere. This will make WebSphere enforce all security constraints in Web applications. Navigate to the Security -> User Registries -> Local OS screen. Supply a userid and password that WebSphere can use to connect to the user registry. The default user registry is the operating system, but WebSphere also supports LDAP and user registries.
Figure 17. Set a userid for the OS user registry
Next Navigate to the Security -> Global Security section and click the Enabled checkbox, as shown in Figure 18. Please make sure that "Enforece Java 2 Security" is not enabled. If it were we would need to configure the Java virtual machine security profile with the files it is allowed to access (for example all the DADX files). Please also make sure that the "User registry" is the default value ("Local OS") or these instructions won't work.
Figure 18. Enable Global security
Click Apply and Save to Master configuration. Switching on security requires that you restart WebSphere. You can do this with these commands on a command line, assuming that you have the WebSphere directories on the PATH:
stopserver server1 -username wollsch -password mypasswd
startserver server1 -username wollsch -password mypasswd
After restarting, open the WebSphere administrative console. If the security setting was sucessful, you must now enter your userid and password when entering the WAS administration console.
Navigate to the Security -> JAAS Configuration -> J2C Authentication Data section and click on New. This will lead you to a screen, as shown in Figure 19. This will be the userid that is used to connect to the database for our DataSource.
Figure 19. Set userid and password for database user
Navigate to the Resources -> JDBC provider section and click New and select DB2 Legacy CLI-based Type 2 JDBC driver. Enter the location of the db2java.zip JDBC driver file as shown in Figure 20. Using the "Universal JDBC driver" or JCC JDBC driver is another option we have not chosen, because it means a bit more configuration.
Figure 20. JDBC provider configuration
To create a datasource navigate to the Resources -> JDBC providersection and select the DB2 Legacy CLI-based Type 2 JDBC driver that you created and click on Datasource and then on New. This will lead you to dialogs, as shown in Figures 20 and 21. You must provide a name (sampleDataSource) and a JNDI name (jdbc/sampleDataSource), as shown in Figure 20. The JNDI name must match the name that you specified in in your war file. Figure 21 shows how to associate a JAAS user with a datasource. All connections will be made with this user.
Figure 21. Datasource configuration - part 1
Figure 22. Datasource configuration - part 2
After creating the connection, test the connection as shown in Figure 23. This will make sure that you entered all the right database and user information. If something fails with the Datasource connection test or while invoking a DADX Web Service, open the WebSphere error logs. Open the logs\server1\SystemErr.log and SystemOut.log file, depending on where you installed WebSphere.
Figure 23. Test Datasource configuration
The final step in the WebSphere administrative console is to deploy the EAR file that we created. Figure 23 shows how to specify the EAR file location. You can either use all of the defaults on the following pages or modify the role to user mapping if users are different on the target machine.
Figure 24. Install the EAR file
To start the deployed application navigate to the Applications -> Enterprise Applications sections, select your application (DefaultEAR) and select Start.
Before creating a client, you can test the deployed application with the built-in browser test environment. Access http://localhost:9080/SecureDADX/index.html with a Web browser. You will likely get an error message that says that the certificate from the server is invalid. This is because WebSphere comes only with a self-signed certificate that the browser cannot validate if it is correct. You can either get an official certificate from a signing authority or ignore this message. Try out the list.dadx and see if you can connect with the user that you have allowed access, and also with a user that is not allowed to access the Web Service.
When you write a client program you must make sure that the client provides a userid and password when calling a secured Web Service. Depending on the API and programming environment you use, this may work differently and you must consult your documentation.
If you want to call a secured Web Service with JAX-RPC (Java API for XML-Based RPC), you can follow the instructions and use the example code from Sun's JAX-RPC tutorial (http://java.sun.com/webservices/docs/1.0/tutorial/doc/JAXRPC.html). Refer to the chapter "Security for JAX-RPC."
Acknowledgments The author would like to thank Ellen Patterson, Michael Schenker, and Joel Rolfe for their help and feedback to this article.
-
DB2 Information Center
DB2 Information Center
.
- DB2 developeworks webservices zone
DB2 developeworks webservices zone
- WebSphere 5 security redbook
WebSphere 5 security redbook
- WS-Security spec
WS-Security spec
- WS-Security roadmap
WS-Security roadmap
- Creating a .NET Client that Uses DB2 DADX Web Services
http://www.ibm.com/developerworks/db2/library/techarticle/0212yu/0212yu.html
- Access DB2 with Web services
https://www6.software.ibm.com/reg/devworks/dw-db2wsw5-i?S_TACT=103AMW11&S_CMP=;DB2DD
Table of contents
Next steps from IBM
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
