| Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3.0) Part Number B28967-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3.0) Part Number B28967-02 |
|
|
View PDF |
This chapter contains advice for using web services with ADF projects, and general advice for creating and using web services in JDeveloper
This chapter includes the following sections:
Web services is the term for a technology that consists of a set of messaging protocols and programming standards that expose business functions over the Internet using open XML-based standards, and an individual web service is a discrete, reusable software component that is accessed programmatically over the Internet, using HTTP or sometimes SMTP, to return a response.
Web services allow enterprises to expose business functionality irrespective of the platform or language of the originating application because the business functionality is exposed in such a way that it is abstracted to a message composed of standard XML constructs that can be recognized and used by other applications.
Oracle ADF has built in support to use web services as business service providers in applications. For example, an application could:
Use some functionality in an application run by another company and exposed as a web service to provide business-to-business e-commerce.
Use web service made available through a site such as Xmethods.com to provide some standard functionality.
Find a web service that provides the specified functionality in a UDDI registry and use it at runtime.
You can use Oracle ADF to build applications that target one or all of the tiers in the J2EE platform using your choice of implementation technologies. Using ADF to implement your business services, you gain the additional flexibility to be able to expose parts of your application as web services at any time without code changes.
Factors influencing the decision to deploy a component as a web service are:
Web services separate the application from the underlying architecture.
Web services are lightweight, which can result in improved performance across the Internet or an intranet.
Web services technology is designed to use the Web infrastructure, including HTTP.
It is useful to describe the XML standards on which web services are based.
The Simple Object Access Protocol (SOAP) is a lightweight XML-based protocol that is used for the sending and receiving over messages of a transport protocol, usually HTTP or SMTP. The SOAP specification, which you can see at web site of the World Wide Web Consortium, provides a standard way to encode requests and responses. It describes the structure and data types of message payloads using XML Schema.
A SOAP message is constructed of the following components:
A SOAP envelope that contains the SOAP body, the important part of the SOAP message, and optionally a SOAP header.
A protocol binding that specifies how the SOAP envelope is sent, that in the case of web services generated in JDeveloper, is via HTTP.
Web services use SOAP, the XML protocol for expressing data as XML and transporting it across the Internet using HTTP, and SOAP allows for more than one way of converting data to XML and back again. JDeveloper supports SOAP RPC encoding, SOAP RPC-literal style, and document-literal style (also known as message style).
The web services you create in JDeveloper can be either for deployment on Oracle SOAP, which is based on Apache SOAP 2.2 and is part of the Oracle Application Server, or to the SOAP server, which is one of the OC4J containers in Oracle Application Server.
The Web Services Description Language (WSDL) is an XML language used to describe the syntax of web service interfaces and their locations. You can see the WSDL v1.1 specification at the web site of the World Wide Web Consortium. Each web service has a WSDL document that contains all the information needed to use the service, the location of the service, its name, and information about the methods that the web service exposes. When you use one of JDeveloper's web service publishing wizards to produce your web service, the WSDL document for your service is automatically generated.
Universal Description, Discovery and Integration (UDDI) provide a standards-based way of locating web services either by name, or by industry category. UDDI registries can be public, for example the public UDDI registries that are automatically available from JDeveloper, or private, such as a UDDI registry used within an organization. This version of JDeveloper only supports web service discovery using UDDI, however future versions will provide full support for UDDI registration. You can see the UDDI v2 specification at http://www.uddi.org/.
JDeveloper's UDDI browser, in the Connections Navigator, stores information about a UDDI registry and allows you to search a UDDI registry using search criteria that you specify to find web services that are described by WSDLs.
You can create your own registry connections to another public UDDI registry, or to a private UDDI registry within your organization. This creates a connection descriptor properties file that contains the enquiry endpoint and the business keys of the registry. You can find this file at <JDEV_INSTALL>/system<release_and_build_number>/uddiconnections.xml, where <JDEV_INSTALL> is the root directory in which JDeveloper is installed.
JDeveloper's Find Web Service wizard browses UDDI registries to find web services by either name or category. You must have an appropriate connection from your machine so that JDeveloper can make a connection to the UDDI registry you select, for example, a connection to the internet if you want to search a public UDDI registry, and you can only generate a stub to a web service that has a tick in the Is WSDL? column that identifies the registry entry as being defined by a WSDL document.
When you use UDDI registries a term you will come across, and that you may be unfamiliar with, is tModel, short for Technical Model. This represents the technical specification of a web service, and when you search for a web service using the Find Web Service wizard, the wizard also displays other web services that are compatible with the same tModel.
The data structure types used in UDDI are:
Service Details This section gives information about the service, including the name.
Business Entity This is the top-level data structure called businessEntity that contains information about the business providing the web service.
Service Bindings contains the bindingTemplate, that contains information about the service access point, and the tModel that gives the technical specification of the web service.
When the Find Web Services wizard finds a web service, it lists all web services that are compatible with the same tModel.
A key issue facing web services is how interoperable web services actually are. The key feature of web services is that they use common standards to avoid the problems that earlier solutions to getting different applications to be able to use each other's components, for example CORBA, had. However the standards themselves have been being written at the same time as the organizations have been starting to write, deploy and use web services. This has led to interoperability issues such as web services being written using different standards, for example, not using WSDL to provide web service information.
The Web Services-Interoperability Organization (WS-I) was formed by Oracle and other industry leaders to address these issues of interoperability, and to provide tools so that web services can be tested to see how well they interoperate. JDeveloper helps you to test the interoperability of web services by analyzing a web service for conformity to the WS-I Basic Profile 1.0. First you have to download a WS-I compliant analyzer. There are a number of these available from independent vendors, and one from the WS-I web site. A set of test assertions is used to find out how well a web service conforms to the basic profile, and information is recorded for the following artifacts:
Discovery when a web service has been found using a UDDI registry. If the service has not been found using the Find Web Services wizard, this section of the report returns errors in the Missing Input section.
Description of a web service's WSDL document, where the different elements of the document are examined and non-conformities are reported. An example of a failure in this section is a failure of assertion WSI2703, that gives the message "WSDL definition does not conform to the schema located at http://schemas.xmlsoap.org/wsdl/soap/2003-02-11.xsd for some element using the WSDL-SOAP binding namespace, or does not conform to the schema located at http://schemas.xmlsoap.org/wsdl/2003-02-11.xsd for some element using the WSDL namespace."
Message that tests the request and response messages when the connection is made to the web service and it sends its reply.
For more information about WS-I including the specification, see the web site of The Web Services-Interoperability Organization (WS-I) at ws-i.org.
The most common way of using web services in an application developed using Oracle ADF is to create a data control for an external web service, and a usual reason for this is to add functionality that is readily available as a web service but which would be time consuming to develop with the application, or to access an application that runs on a different architecture.
Also, you can re-use components created by Oracle ADF to make them available as web services for other applications to access.
JDeveloper allows you to create a data control for an existing web service using just the WSDL for the service. You can browse to a WSDL on the local file system, locate one in a UDDI registry, or enter the WSDL URL directly.
Note:
If you are working behind a firewall and you want to use a web service that is outside the firewall, you must configure the Web/Browser Proxy settings in JDeveloper. Refer to the JDeveloper online help for more information.
To create a web service data control:
In the Application Navigator, right-click an application and choose New.
In the New Gallery, expand Business Tier in the Categories tree, and select Web Services.
In the Items list, double-click Web Service Data Control.
Follow the wizard instructions to complete creating the data control.
Alternatively, you can right-click on the WSDL node in the navigator and choose Create Data Control from the context menu.
Web services allow applications to exchange data and information through defined application programming interfaces. SSL (Secure Sockets Layer) provides secure data transfer over unreliable networks, but SSL only works point to point. Once the data reaches the other end, the SSL security is removed and the data becomes accessible in its raw format. A complex web service transaction can have data multiple messages being sent to different systems, and SSL cannot provide the end-to-end security that would keep the data invulnerable to eavesdropping.
Any form of security for web services has to address the following issues:
The authenticity and integrity of data
Data privacy and confidentiality
Authentication and authorization
Non-repudiation
Denial of service attacks
The WS-Security specification unifies multiple security technologies to make secure web services interoperable between systems and platforms. The specification can be viewed at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.
WS-Security addresses the following aspects of web services security issues:
Authentication and Authorization
The identity of the sender of the data is verified, and the security system ensures that the sender has privileges to perform the data transaction.
The type of authentication can be a basic username password pair transmitted in plain text, or trusted X509 certificate chains. SAML assertion tokens can also be used to allow the client to authenticate against the service, or allow it to participate in a federated SSO environment, where in authenticated details are be shared between domains in a vendor independent manner
Data Authenticity, Integrity and Non-Repudation
XML digital signatures, which use industry standard messages, digest algorithms to digitally sign the SOAP message.
Data Privacy
XML encryption that uses industry standard encryption algorithms to encrypt the message.
Denial of Service Attacks
Defines XML structures to time stamp the SOAP message. The server uses the time stamp to invalidate the SOAP message after a defined interval.
Throughout this section the "client" is the web service data control, which sends SOAP messages to a deployed web service. The deployed web service may be:
a web service deployed on OC4J for testing purposes.
web service running on Oracle Application Server.
A web service running anywhere in the world that is accessible through the Internet
An ADF 10.1.3 Web Services data control can be configured for message level security using either Java Key Store (JKS), or the Oracle Wallet. For information on setting up and using Oracle Wallet, see the Oracle Technology Network at www.oracle.com/technology.This section describes:
Creating a keystore using the J2SE 1.4 Keytool utility
Building a keystore private/public key pairs, which are used for encryption and signing.
How to obtain a Certificate to issue digital signatures from a root certificating authority.
How to import the Certificate into the keystore.
How to export the Certificate with the public key for encryption.
This is illustrated by creating two keystores, one to be configured on the server side, and the other on the client side (the data control side).
Note:
The steps outlined in this section for requesting digital certificates is for test purposes only. Deployments intending to use Web Services data control with digital signatures enabled must ensure that trusted certificates are generated compliant to the security policies of the deployment environment.To create a public private key pair that can be used by the client for encryption and signing, at the command prompt run the following:
Example 21-1 Command to Create a Keystore
keytool -genkey -alias clientenckey clientsignkey -keyalg RSA -sigalg SHA1withRSA -keystore client.jks
The keystore utility will prompt you for the keystore password, and then asks questions to determine the distinguished name (DN), which is a unique identifier and consists of the following components:
CN= common name. This must be a single name without spaces or special characters.
OU=organizational unit
O=organization name
L=locality name
S=state name
C=country, a two letter country code
After you answer the questions, the Keytool utility will prompt you for the key password. If the key password is the same as the keystore password, press Enter without entering a value. Otherwise, enter the key password. After you enter the key password, the keystore file client.jks is created in the current directory. It contains a single key pair with the alias clientenckey which can be used to encrypt the SOAP requests from the data control.
Next, create a key pair for digitally signing the SOAP requests made by the data control. At the command prompt run the command again, but use clientsignkey for the alias of the signing key pair.
To list the key entries in the keystore, run the following:
The Keytool utility will prompt you for the store password. Enter the password that was used to create the keystore. Repeat the commands to create a keystore for the server side, and use serverenckey for the encryption key pair, and serversignkey for the signing key pair.
The keytool, by default, generates a self-signed certificate, that is a certificate whose issuer is the same as the generator of the key.
If your public key is to be distributed to the outside world, to allow verification of the digital signatures you have issued, then a trusted Certificate Authority (CA) must issue a certificate vouching your identity on your public key. To do this, create a Certificate request file for the signature key pair you have created and submit the request file to a CA.
At the command prompt, run the following:
Example 21-3 Command to Create a Certificate Request File
keytool -certreq -file clientsign.csr -alias clientsignkey -keystore client.jks
The Keytool utility will prompt you for the store and key passwords. After you enter the passwords, a certificate request is generated in a file called clientsign.csr for the public key aliased by clientsignkey.
When you are developing your application, you can use a CA such as Verisign to request trial certificates. Go to www.verisign.com, navigate to Free SSL Trial Certificate and create a request. You must enter the same DN information you used when you created the keystore. Verisign's certificate generation tool will ask you to paste the contents of the certificate request file generated by the keytool (in this case, clientsign.csr). Once all the information is correctly provided, the certificate will be sent to the email ID you have provided, and you have to import it into the keystore.
Open the contents of the certificate in a text editor, and save the file as clientsign.cer.
You also have to import the root certificate issued by Verisign into the keystore. The root certificate is needed to complete the certificate chain up to the issuer.
The root certificate vouches the identity of the issuer. Follow the instructions in the email you received from Verisign to access the root certificate, and paste the contents of the root certificate into a text file called root.cer.
Once you have the root.cer and clientsign.cer files created, run the following command to import the certificates into your keystore:
The Keytool utility will prompt you for the store password. Next you must import your public key certificate.
Import your public key certificate next.
Example 21-5 Importing the Public Key Certificate
keytool -import -file clientsign.cer -alias clientsignkey -keystore client.jks
The Keytool utility will prompt you for the store and key password. After entering the passwords, execute the same commands to set up the trusted certificate chain in the server keystore.
Perform the same commands steps to set up the trusted certificate chain in the server keystore.
Once the certificate chains are set up, the client and sever are ready to issue digitally signed SOAP requests.
Note:
Trusted certificates are mandatory when issuing digital signatures on the SOAP message. You cannot issue digital signatures with self-signed/untrusted certificates in your keystore.
The server must export its public key to the client so the client can encrypt the data it sends to the server. The server can then use its corresponding private key to decrypt the data. The server's public key certificate is imported into the client keystore.
At the command prompt, run the following:
Example 21-6 Command to Export the Server's Public Key Certificate
keytool -export -file serverencpublic.cer -alias serverenckey -keystore server.jks
The Keytool utility will prompt you for the store password.
In this example, clientencpublic.cer contains the public key certificate of the client's encryption key. To import this certificate in the server's keystore, run the following:
Example 21-7 Command to Import Client's Encription Key
keytool -import -file serverencpublic.cer -alias serverencpublic -keystore client.jks
The Keystore utility will prompt you for the store password.
Similarly, the client must export its public key so that it can be imported into the server's keystore.
Example 21-8 Command to Export the Client's Public Key Certificate
keytool -export -file clientencpublic.cer -alias clientenckey -keystore client.jks
The Keytool utility will prompt you for the store password.
Example 21-9 Command to Import the Public Key Certificate
keytool -import -file clientencpublic.cer -alias clientencpublic -keystore server.jks
The server and client keystores are now ready to be used to configure security for the web service data control.
The Keytool utility will prompt you for the keystore password.
Once you have a web services data control in a JDeveloper project, you can define security using the Data Control Security wizard.
To invoke the data control security wizard:
Select the web service data control in the Application Navigator.
In the Structure window, right-click the web service data control, and choose Define Web Service Security.
Consult the following sections for more information, or click F1 or Help in the wizard for detailed information about a page of the wizard.
WS-Security allows for service level authentication by using either username tokens or binary tokens. In addition to these, the web service client can issue SAML assertion tokens that can be used for server side authentication, or for participation in a federated SSO environment.
Oracle's WS-Security implementation is integrated with JAZN (JAAS) to achieve the authentication. How authentication using a certificate is done depends on the implementation and integration with the platform security system. This section discusses configuring OC4J as the server where the application is deployed.
Note:
When the application is deployed to Oracle Application Server, the administrator should use the security editing tool to add users to the security system, grouping them in the appropriate role and granting appropriate privileges. This example of manually editing
system-jazn-data.xml is just for testing, and not recommended for working applications.For Username Token authentication, username/password pair must be a trusted user entry in the JAZN repository.
For X509 Token authentication, the CN (Common Name) on whom the Certificate is issued must be a trusted user in the JAZN repository.
For SAML authentication, the user must be a valid user in the JAZN repository.
To edit the JAZN repository:
Open <JDEV_INSTALL>/J2EE/home/system-jazn-data.xml and enter the authentication details. For example, for X509 authentication, make an entry under the <users> section similar to:
<user>
<name>King</name>
<display-name>OC4J Administrator</display-name>
<description>OC4J Administrator</description>
<credentials>{903}/LptVQLDeA5sgZFLL5TKlr/qjVFPxB42</credentials>
</user>
Username tokens provide basic authentication of a username/password pair. The passwords can be transmitted as plain text or digest.
Note:
This is not the same as HTTP basic or digest authentication. The concept is similar, but it differs in that the recipient of HTTP authentication is the HTTP server, whereas for the web service data control, the username tokens are passed with the message, and the recipient is the target web service.Oracle's WS-Security implementation is integrated with JAZN (JAAS) to achieve the authentication. The username/password pair must be a trusted user entry in the JAZN repository.
To use username tokens for authentication:
In the Authentication page of the wizard, under Available Operations, select one or more ports or operations to apply the authentication to.
Select the authentication type as the Username Token.
Enter the remaining information required for username authentication.
An X509 certificate issued by a trusted CA is a binary security token which can be used to authenticate the client. The client sends its X509 certificate with a digital signature, which is used by the server for authentication. The X509 certificate chain associated with signature key is used for authentication.
You must have the keystore file, with the root certificate of the CA, installed on the server.
Note:
An X509 certificate can only be configured at port level, unlike the other authentication types that can be configured at port or operation level.To use X509 certificate authentication:
In the Authentication page of the wizard, select the authentication type as the X509 Token.
In the Keystore page of the wizard, and specify the location of the keystore file, and enter the signature key alias and password.
SAML assertion tokens can be used to allow client to authenticate against the web service, or allow the client to participate in a federated SSO environment, where authenticated details can be shared between domains in a vendor independent manner.
Note:
SAML Assertions will not be issued if the user identity cannot be established by JAZN.To use SAML authentication:
In the Authentication page of the wizard, select the authentication type as the SAML Token.
The Subject Name is the username name against which the SAML Assertions will be issued.
You can choose Confirmation method as SENDER-VOUCHES or SENDER-VOUCHES-UNSIGNED:
ISENDER-VOUCHES (default). The SAML tokens must be digitally signed. This is the preferred method to issue SAML tokens. If you choose this confirmation technique, then you must configure a keystore and enter keystore and signature key information on the Keystore page of the wizard.
SENDER-VOUCHES-UNSIGNED. The SAML tokens are transmitted without any digital signatures. If you choose this confirmation technique, then you need not configure a keystore and signature key.
You can configure digital signatures on the outgoing SOAP messages, and verify digital signatures on the incoming message from the web service your application is contacting. You can also enforce an expiration window for the digital signatures.
You can set a digital signature on the outgoing SOAP message at port or operation level in the Message Integrity page of the wizard, and verify the digital signatures from the incoming message of the web service.
To sign the SOAP request, and verify the signature of the SOAP response:
In the Message Integrity page of the wizard, select the appropriate options.
In the Keystore page of the wizard, and specify the location of the keystore file, and enter the signature key alias and password.
When you create a web service in JDeveloper, you can set security options in the Web Services Editor. These are then applied at the server side once the web service is deployed. Refer to the JDeveloper online help for complete information.
Before deploying the web service, run the editor and configure encryption and decryption details on the web service. Ensure that you have specified the client's (that is, the data control's) public key to be used for encryption.
You can encrypt and outgoing SOAP message at port or operation level in the Message Confidentiality page of the wizard, and decrypt the incoming message from the web service.
To encrypt the SOAP request, and decrypt the SOAP response:
In the Message Confidentiality page of the wizard, select the appropriate options. The encryption algorithm you select must be the same as that configured on the server side when the web service was deployed.
Enter the server's public key alias to allow the data control to encrypt the key details using the server's public key. In this example, serverencpublic is the server's public key certificate that imported in the key store configuration.
If the web service uses incoming message encryption, select Decrypt Incoming SOAP Response.
In the Keystore page of the wizard, and specify the location of the keystore file, and enter the encryption key alias and password.
Section 21.3.2.1, "How to Create a Keystore" described setting up keystores for the client (the web service data control) and for the server (a deployed web service). In the Configure Key Store page of the Data Control Security wizard you enter the information needed for the keystore to be used for data control security.
The final stage of configuring WS-Security for a data control based on a web service is to specify the keystore details. Enter the information to access the client keystore here, and when the wizard is finished the keys configured in the store will be available for signatures and encryption for all requests generated by the data control and all responses processed by the data control.
To set key store access information:
In the Configure Key Store page of the wizard, enter the appropriate values.
