Oracle® Application Server Web Services Security Guide 10g (10.1.3.5.0) Part Number E13983-01 |
|
|
View PDF |
This chapter provides the generalized steps for assembling a secure Web service. Oracle Application Server Web Services provides the WebServicesAssembler tool which enables you to assemble the service top down (from a WSDL) or bottom up (from Java classes, EJBs, or database resources). The tool can assemble your service either from Ant tasks in a build script or by entering commands on the command line.
See Also:
For a detailed description of using the WebServicesAssembler tool to build Web services, see the Oracle Application Server Web Services Developer's Guide.
Note:
The Oracle JDeveloper IDE and the Application Server Control tools can aid your development of secure Web services. You can use the Oracle JDeveloper IDE to build, configure, deploy, and test a secure Web service. You can also use Application Server Control tool to deploy, manage, and monitor it. For more information on using these tools to build and deploy Web services, see the topics Developing with Web Services in the Oracle JDeveloper on-line help and Web Services Page in the Application Server Control on-line help.In OracleAS Web Services Security, the security policies for a Web service are specified in XML configuration files. Some examples of the security policies they can describe include username token authentication and XML signature and encryption of the SOAP message body.
The WebServicesAssembler tool adds the policies declared in the configuration files to the Web service at assembly time. The policies can be assembled into the service by either the bottom up or top down approach. You must provide one configuration file for the server and a corresponding file for the client.
These sections describe how to assemble security into a Web service:
These sections describe how to create the files for the server and the client. They also describe how to specify their content to implement username authentication and the XML signature and encryption security policies:
The following steps provide a general outline of how to add a security configuration to a Web service application that is being assembled top down from an existing WSDL. To perform this assembly, the WebServicesAssembler tool provides the topDownAssemble
command. Only the steps that concern adding security are described in detail. If you need more information on an individual step, see "Assembling a Web Service from a WSDL" in the Oracle Application Server Web Services Developer's Guide.
Generate the service endpoint interface using WebServicesAssembler.
Provide a WSDL from which the Web service will be generated as input to the WebServicesAssembler genInterface
command.
Compile the generated interfaces and type classes from Step 1 using the Java compiler.
Implement the Java service endpoint for the Web service you want to provide.
The Java service endpoint must have a method signature that matches every method in the generated Java interface in Step 1.
Compile the Java service endpoint.
Create a server-side security configuration file.
The WebServicesAssembler tool uses this file to generate security information into the oracle-webservices.xml
server-side deployment descriptor. "Creating a Server-Side Security Configuration File" provides instructions on how to create this file.
(Optional) Create a keystore.
If you are signing or encrypting data, or verifying signatures or decrypting data, you must have a keystore to store trusted certificates and public and private keys. See "Creating a Keystore" for more information on creating a Oracle Wallet or JKS keystore.
(Optional) Bundle the keystore.
If your server-side security configuration contains a <decrypt>
, <verify-signature>
, <verify-x509-token>
, or <verify-saml-token>
element in the inbound policy, or if it contains an <encrypt>
, <x509-token>
, <saml-token>
, or <signature>
element in the outbound policy, then you must either bundle a keystore with your application or specify a global-level keystore.
To bundle a keystore with your application, follow these steps:
Assemble the service.
Assemble the Web service using the WebServicesAssembler topDownAssemble
command. This is where you generate the security configuration into the Web service. Note that the path to the serverConfig.xml
file, which contains the security configuration, is specified with the ddFileName
argument.
Command line:
java -jar wsa.jar -topDownAssemble -wsdl SecureService.wsdl -unwrapParameters false -className oracle.demo.security.SecureServiceImpl -input build/classes/service -output build -ear dist/secure_service.ear -packageName oracle.demo.security -fetchWsdlImports true -ddFileName serverConfig.xml -classpath ./build/classes/client/ : $OC4J_HOME/jlib/jaxen.jar : $OC4J_HOME/jlib/osdt_wss.jar : $OC4J_HOME/jlib/osdt_cert.jar : $OC4J_HOME/jlib/osdt_xmlsec.jar : $OC4J_HOME/jlib/osdt_core.jar : $OC4J_HOME/jlib/osdt_saml.jar : $OC4J_HOME/jlib/oraclepki.jar : $OC4J_HOME/j2ee/home/jazn.jar : $OC4J_HOME/j2ee/home/jazncore.jar : $OC4J_HOME/j2ee/home/jaznplugin.jar
Ant task:
<oracle:topDownAssemble appName="secure_service" wsdl="./wsdl/SecureService.wsdl" unwrapParameters="false" input="build/classes/service " output="build" ear="dist/secure_service.ear" packageName="oracle.demo.security" fetchWsdlImports="true" ddFileName=serverConfig.xml> <oracle:portType className="oracle.demo.topdowndoclit.service.DocLitLoggerImpl" </oracle:portType> <oracle:classpath> <pathelement location="build/classes/client/" /> <pathelement location="${OC4J_HOME}/jlib/jaxen.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_wss.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_cert.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_xmlsec.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_core.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_saml.jar" /> <pathelement location="${OC4J_HOME}/jlib/oraclepki.jar" /> <pathelement location="${OC4J_HOME}/j2ee/home/jazn.jar" /> <pathelement location="${OC4J_HOME}/j2ee/home/jazncore.jar" /> <pathelement location="${OC4J_HOME}/j2ee/home/jaznplugin.jar" /> </oracle:classpath> </oracle:topDownAssemble>
In this command and Ant task:
topDownAssemble
—Creates the required classes and deployment descriptors for a Web service based on a WSDL description. The files can be stored in either an EAR file, a WAR file, or a directory.
wsdl
—Specifies the absolute file path, relative file path, or URL to a WSDL document.
unwrapParameters
—When set to false
the generated service endpoint interface will be generated with wrappers around the input parameter and the return type.
className
—Specifies the name of the class (including the package name) that is the implementation class for the Web service.
input
—Specifies the directory or JAR containing the classes that should be copied to WEB-INF/classes
. This argument will be added to the classpath used by the WebServicesAssembler.
output
—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created.
ear
—Specifies the name and location of the generated EAR.
packageName
—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file.
fetchWsdlImports
—Indicates if you want to make a local copy of the WSDL and everything it imports.
ddFileName
—Specifies the oracle-webservices.xml
deployment descriptor that contains the settings you want to assign to the Web service.
classpath
—Specifies the classpath that contains any user-created classes given to WebServicesAssembler. One reason to specify this argument is if you have already created some value type classes or exceptions and you do not want WebServicesAssembler to overwrite them.
See Also:
"Using WebServicesAssembler", in the Oracle Application Server Web Services Developer's Guide for more detailed information on these arguments.
At a minimum, specify the name of the WSDL, the class name that implements the Service (generated in Step 3), and the name of the output directory. The WebServicesAssembler tool outputs an EAR file, and a WAR file within the EAR. The WAR file contains the service artifacts, the implementation classes, the Web deployment descriptor (web.xml
) and the JAX-RPC deployment descriptor (webservices.xml
) and oracle-webservices.xml
with the security configuration.
Note:
If you want to authenticate the user based on the username token, then a user entry must exist with the username and password sent by client. For information on creating a file-based repository of user entries, see the Oracle Containers for J2EE Security Guide.Deploy and bind the service into a running instance of OC4J.
You can deploy the service by using Application Server Control or by using admin_client.jar
on the command line. For more information on deployment, see Deploying an Application in the Application Server Control on-line help and the Oracle Containers for J2EE Deployment Guide.
Configure a security provider on the server-side to authenticate user data sent by the client.
For more information on configuring security providers, see the Oracle Containers for J2EE Security Guide.
(Optional) Check that deployment succeeded. OracleAS Web Services provides a Web Service Test Page for each deployed Web service.
For more information on the Web Service Test Page, see the Oracle Application Server Web Services Developer's Guide.
Create the client security configuration file.
Create a client configuration file that specifies the security that will be applied to your Web service client. In this example, the file is called clientConfig.xml
. The WebServicesAssembler tool uses this file to generate the client-side deployment descriptor <generated_name>
_Stub.xml
. "Creating a Client-Side Security Configuration File" provides instructions on how to create the client configuration file.
Generate the secure client code.
For the J2SE environment, generate stubs (client proxies) for a J2SE Web service client by running the WebServicesAssembler tool with the genProxy
command.
For information on assembling a J2EE client, see "Assembling a J2EE Client" in the Oracle Application Server Web Services Developer's Guide.
For example, the following command generates client proxies that can be used for a J2SE client. Note that the ddFileName
argument specifies the client configuration file.
Command line:
java -jar wsa.jar -genProxy -wsdl http://localhost:8888/webservice/webservice?WSDL -unwrapParameters false -output build/src/client -packageName oracle.demo.security.stubs -ddFileName clientConfig.xml
Ant task:
<oracle:genProxy wsdl="http://localhost:8888/webservice/webservice?WSDL" unwrapParameters="false" output="build/src/client" packageName="oracle.demo.security.stubs" ddFileName="clientConfig.xml" />
In this command and Ant task:
genProxy
—Creates a static proxy stub that can be used by a J2SE Web service client.
wsdl
—Specifies the absolute file path, relative file path, or URL to a WSDL document.
unwrapParameters
—This argument can be set only for document-literal operations and will be ignored for other message formats. When set to false
the generated service endpoint interface will be generated with wrappers around the input parameter and the return type.
output
—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created.
packageName
—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file.
ddFileName
—Specifies the oracle-webservices.xml
deployment descriptor that contains the settings you want to assign to the Web service.
See Also:
"Using WebServicesAssembler", in the Oracle Application Server Web Services Developer's Guide for more detailed information on these arguments.
At a minimum, specify the name of the WSDL, the name of the output directory and the name of the client configuration file. The WebServicesAssembler tool generates a <generated_name>
_Stub.xml
. A client application uses the stub to invoke operations on a remote service.
Compile and run the client.
The following steps provide a general outline of how to add a security configuration to a Web Service application that is being assembled bottom up. The WebServicesAssembler tool provides several specialized commands based on whether you are assembling the services from Java classes, EJBs, JMS destinations, or database resources. These commands are summarized in "Ant Tasks and WebServicesAssembler".
In the following example, a Web service is assembled from Java classes. To perform this assembly, the WebServicesAssembler tool provides the assemble
command. Only the steps that concern adding security are described in detail. If you need more information on an individual step, see "Assembling a Web Service with Java Classes" in the Oracle Application Server Web Services Developer's Guide.
Provide the compiled Java class that you want to expose as a Web service and its compiled interface.
Create the Web service security configuration file.
In this example, the file is called serverConfig.xml
. The WebServicesAssembler tool uses this file to generate security information into the oracle-webservices.xml
server-side deployment descriptor. "Creating a Server-Side Security Configuration File" provides instructions on how to create this file.
(Optional) Create a keystore.
If you are signing or encrypting data, or verifying signatures or decrypting data, you must have a keystore to store trusted certificates and public and private keys. See "Creating a Keystore" for more information on creating a Oracle Wallet or JKS keystore.
(Optional) Bundle the keystore.
If your server-side security configuration contains a <decrypt>
, <verify-signature>
, <verify-x509-token>
, or <verify-saml-token>
element in the inbound policy, or if it contains an <encrypt>
, <x509-token>
, <saml-token>
, or <signature>
element in the outbound policy, then you must either bundle a keystore with your application or specify a global-level keystore.
To bundle a keystore with your application, follow these steps:
Assemble the secure Web service.
Assemble the Web service by running the WebServicesAssembler tool with the appropriate *Assemble
command for the Web service you are creating. Note that the path to the serverConfig.xml
server configuration file is specified with the ddFileName
argument.
Note that this example assumes that the command is run on the UNIX operating system. Directory paths use the forward slash (/
) and the classpath argument uses a colon (:
) to separate individual classpath elements. If you are using the Windows operating system, use a back slash (\
) in directory paths and separate individual classpath elements with a semicolon (;
).
Command line:
java -jar wsa.jar -assemble -appName securehello -serviceName SecureHelloService -interfaceName oracle.demo.hello.HelloInterface -className oracle.demo.hello.HelloImpl -input ./build/classes/client -output build -ear dist/securehello.ear -uri SecureHelloService -ddFileName serverConfig.xml -classpath ./build/classes/client/ : $OC4J_HOME/jlib/jaxen.jar : $OC4J_HOME/jlib/osdt_wss.jar : $OC4J_HOME/jlib/osdt_cert.jar : $OC4J_HOME/jlib/osdt_xmlsec.jar : $OC4J_HOME/jlib/osdt_core.jar : $OC4J_HOME/jlib/osdt_saml.jar : $OC4J_HOME/jlib/oraclepki.jar : $OC4J_HOME/j2ee/home/jazn.jar : $OC4J_HOME/j2ee/home/jazncore.jar : $OC4J_HOME/j2ee/home/jaznplugin.jar
Ant task:
<oracle:assemble appName="securehello" serviceName'"SecureHelloService" input="./build/classes/client" output="build" ear="dist/securehello.ear" > <oracle:porttype interfaceName="oracle.demo.hello.HelloInterface" className="oracle.demo.hello.HelloImpl" <oracle:port uri="SecureHelloService" /> </oracle:porttype> <oracle:classpath> <pathelement location="build/classes/client/" /> <pathelement location="${OC4J_HOME}/jlib/jaxen.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_wss.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_cert.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_xmlsec.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_core.jar" /> <pathelement location="${OC4J_HOME}/jlib/osdt_saml.jar" /> <pathelement location="${OC4J_HOME}/jlib/oraclepki.jar" /> <pathelement location="${OC4J_HOME}/j2ee/home/jazn.jar" /> <pathelement location="${OC4J_HOME}/j2ee/home/jazncore.jar" /> <pathelement location="${OC4J_HOME}/j2ee/home/jaznplugin.jar" /> </oracle:classpath> </oracle:assemble>
In this command and Ant task:
assemble
—Generates a Web service from Java files bottom up. The command creates all of the files required to create a deployable archive.
appName
—Specifies the name of an application. Usually, this name is used as a base value for other arguments like context
and uri
.
serviceName
—Specifies the service name.
interfaceName
—Specifies the name of a Java class (including the package name) that contains the service endpoint interface (SEI).
className
—Specifies the name of the class (including the package name) that is the implementation class for the Web service.
input
—Specifies the directory or JAR containing the classes that should be copied to WEB-INF/classes
. This argument will be added to the classpath used by the WebServicesAssembler.
output
—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created.
ear
—Specifies the name and location of the generated EAR.
uri
—Specifies the URI to use for the Web service.
ddFileName
—Specifies the oracle-webservices.xml
deployment descriptor that contains the settings you want to assign to the Web service.
classpath
—Specifies the classpath that contains any user-created classes given to WebServicesAssembler. One reason to specify this argument is if you have already created some value type classes or exceptions and you do not want WebServicesAssembler to overwrite them.
See Also:
"Using WebServicesAssembler", in the Oracle Application Server Web Services Developer's Guide for more detailed information on these arguments.
The output of this command is an EAR file that contains the contents of a WAR file that can be deployed to an OC4J instance. The build
directory specified by the output
argument contains separate directories for the EAR file and the Java classes. The dist
directory contains the J2EE Web services-compliant application EAR file, securehello.ear
.
Note:
If you want to authenticate the user based on the username token, then a user entry must exist with the username and password sent by client. See "Configuring File Based Providers" in the Oracle Containers for J2EE Security Guide for information on adding user entries to the server.Deploy and bind the service.
You can deploy the service by using Application Server Control or by using admin_client.jar
on the command line. For more information on deployment, see Deploying an Application in the Application Server Control on-line help and the Oracle Containers for J2EE Deployment Guide.
Configure a security provider on the server-side to authenticate user data sent by the client.
See the Oracle Containers for J2EE Security Guide for more information on security provider configurations.
(Optional) Check that deployment succeeded. OracleAS Web Services provides a Web Service Home Page for each deployed Web service.
For more information on the Web Services Home Page, see "Testing Web Service Deployment" in the Oracle Application Server Web Services Developer's Guide.
Create a client security configuration.
Create a client configuration file that specifies the security that will be applied to your Web service client. In this example, the file is called clientConfig.xml
. The WebServicesAssembler tool uses this file to generate the client-side deployment descriptor <generated_name>
_Stub.xml
. "Creating a Client-Side Security Configuration File" provides instructions on how to create the client configuration file.
Assemble secure client code.
For the J2SE environment, generate stubs (client proxies) for a J2SE Web service client by running the WebServicesAssembler tool with the genProxy
command.
For information on assembling a J2EE client, see "Assembling a J2EE Client" in the Oracle Application Server Web Services Developer's Guide.
For example, the following command generates client proxies that can be used for a J2SE client. Note that the ddFileName
argument specifies the client configuration file.
Command line:
java -jar wsa.jar -genProxy -wsdl http://localhost:8888/webservice/webservice?WSDL -unwrapParameters false -output build/src/client -packageName oracle.demo.security.stubs -ddFileName clientConfig.xml
Ant task:
<oracle:genProxy wsdl="http://localhost:8888/webservice/webservice?WSDL" unwrapParameters="false" output="build/src/client" packageName="oracle.demo.security.stubs" ddFileName="clientConfig.xml" />
In this command and Ant task:
genProxy
—Creates a static proxy stub that can be used by a J2SE Web service client.
wsdl
—Specifies the absolute file path, relative file path, or URL to a WSDL document.
unwrapParameters
—This argument can be set only for document-literal operations and will be ignored for other message formats. When set to false
the generated service endpoint interface will be generated with wrappers around the input parameter and the return type.
output
—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created.
packageName
—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file.
ddFileName
—Specifies the oracle-webservices.xml
deployment descriptor that contains the settings you want to assign to the Web service.
See Also:
"Using WebServicesAssembler", in the Oracle Application Server Web Services Developer's Guide for more detailed information on these arguments.
At a minimum, specify the name of the WSDL, the name of the output directory, and the client configuration file. The WebServicesAssembler tool generates a <generated_name>
_Stub.xml
. A client application uses the stub to invoke operations on a remote service.
Compile and run the client.
This section describes how to create a server-side Web service security configuration file to verify a username token. In this example, the file is called serverConfig.xml
. The WebServicesAssembler tool appends the data found in this file into the oracle-webservices.xml
server-side deployment descriptor.
Note:
If you are using Oracle JDeveloper to secure your Web service, then the security configuration is automatically generated into theoracle-webservices.xml
file.The following general steps describe how to create the server-side Web service security configuration file.
Create a file using any text editor.
Example 4-1 provides a sample server-side configuration file named serverConfig.xml
.
Enter the XML elements to set the security configuration in the file.
The following sections provide sample server-side Web service security configurations for username token and for XML signature and encryption.
"Defining a Server-Side, Port Level Security Configuration for Username Token" provides a sample configuration file that enforces username token verification at the port-level.
"Defining a Server-Side, Operation-Level Security Configuration for Username Token" provides a sample configuration file that enforces username token verification at the operation-level.
"Defining a Server-Side, Port-Level Security Configuration to Verify XML Signature and Decryption" provides a sample configuration file that implements XML signature and XML encryption at the port level.
"Defining a Server-Side, Operation-Level Security Configuration for XML Signature and Decryption" provides a sample configuration file that implements XML signature and XML encryption at the operation level.
Save the file.
Example 4-1 illustrates a sample server-side Web services configuration file which enforces security on the port level. This means that the user name token will have to be verified before access is granted to any of the operations in the port. Note that line numbers have been added for reference purposes only. They should not appear in your file. "Security Elements for Inbound Messages" provides more information on the <verify-username-token>
element for inbound security.
Line 2: This line identifies the Web service to which security will be applied. The name
attribute value should match the service name in the WSDL.
Line 3: This line identifies the port name. It must match a valid port name in the WSDL.
Lines 4-10: In this example security is applied at port level. The <runtime enabled="security">
element indicates that at run time, Web services security will be enforced based on the policy defined in the <security>
element. Since security is configured at port level in this example, the same security will be applied to all operations exposed by this Web service.
Lines 6-8: These lines configure the inbound security for the incoming request. In this example, the <verify-username-token/>
element indicates that the Web service application is expecting a username token in the request header. You can also enforce the password type and whether a nonce is required. See "Security Elements for Inbound Messages" for more information on this element.
Lines 11-13: These lines define the operations that the Web service port exposes.
Example 4-1 Sample Server-Side Configuration File for Port-Level Username Token Verification
1. <oracle-webservices> 2. <webservice-description name="SecureService"> 3. <port-component name="SecureServiceSoap"> 4. <runtime enabled="security"> 5. <security> 6. <inbound> 7. <verify-username-token/> 8. </inbound> 9. </security> 10. </runtime> 11. <operations> 12. <operation name="getCatalog"/> 13. </operations> 14. </port-component> 15. </webservice-description> 16. </oracle-webservices>
Example 4-2 illustrates a sample server-side Web services configuration file which enforces security on the operation level. This means that the username token will have to be verified before access is granted to the specified operation. Note that line numbers have been added for reference purposes only. They should not appear in your file.
See Also:
See "Security Elements for Inbound Messages" for more information on the <verify-username-token>
element.
The following configuration is similar to Example 4-1 with one major difference:
Lines 6-14: The username verification is applied only for the getCatalog
operation.
Example 4-2 Sample Server-Side Configuration File for Operation Level Username Token Verification
1. <oracle-webservices> 2. <webservice-description name="SecureService"> 3. <port-component name="SecureServiceSoap"> 4. <runtime enabled="security"/> 5. <operations> 6. <operation name="getCatalog"> 7. <runtime> 8. <security> 9. <inbound> 10. <verify-username-token/> 11. </inbound> 12. </security> 13. </runtime> 14. </operation> 15. </operations> 16. </port-component> 17. </webservice-description> 18. </oracle-webservices>
Since the settings are made on the port level, verification must take place before access is granted to any of the operations in the port. See "Keystore Elements" and "Signature and Encryption Key Elements" for more information on configuring keystore, encryption and signature elements. Note that line numbers have been added for reference purposes only. They should not appear in your file.
Lines 4 -25: These lines set the keystore, keys, and inbound policy at the port level. Chapter 3, "Administering Web Services Security" provides more information on generating keystore and keys.
Lines 6-8: These lines set the key-store path
attribute to point to the keystore that is deployed with the application. The store-pass
attribute contains the keystore password. The signature-key alias
attribute is used to verify the trusted certificate. The encryption-key alias
attribute is used to decrypt the message. Note that signalias/encalias
must be in the testks.jks
file.
Lines 11-18: These lines specify the message integrity policy. The server expects the body and the timestamp to be signed. The signature must have a timestamp with the created value set to the creation time. The expiry
attribute specifies when the signature will expire (that is, the current time must be less than the value of the creation time plus the value of expiry
). The value of the clock-skew
attribute is used to adjust the system clocks, when the Web service client and the Web service are on different machines.
Lines 19-23: These lines specify the message confidentiality policy. The server expects the content of the message body to be encrypted.
Example 4-3 Sample Server-Side Configuration File with Keystore and Inbound Policy for Decryption and Signature Verification
1. <oracle-webservices> 2. <webservice-description name="SecureHelloService"> 3. <port-component name="SecureHelloPort"> 4. <runtime enabled="security"> 5. <security> 6. <key-store path="META-INF/testks.jks" store-pass="keystorepwd"/> 7. <signature-key alias="signalias" key-pass="signkeypwd"/> 8. <encryption-key alias="encalias" key-pass="enckeypwd"/> 9. </security> 10. <inbound> 11. <verify-signature> 12. <tbs-elements> 13. <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> 14. <tbs-element name-space="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" local-part="Timestamp"/> 15. </tbs-elements> 16. <verify-timestamp created="true" expiry="28800"/> 17. <property name="clock-skew" value="3000" /> 18. </verify-signature> 19. <decrypt> 20. <tbe-elements> 21. <tbe-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> 22. </tbe-elements> 23. </decrypt> 24. </inbound> 25. </runtime> 26. <operations> 27. <operation name="sayHello"> 28. </operation> 29. </operations> 30. </port-component> 31. </webservice-description> 32. </oracle-webservices>
Example 4-4 illustrates a sample server-side Web services configuration file where the global level keystore settings are used for signature verification and decryption. Note that line numbers have been added for reference purposes only. They should not appear in your file.
Lines 7-26: These lines indicate that security is enforced for the sayHello()
operation. The server expects to receive signed and encrypted messages.
Lines 10-17: These lines specify the message integrity policy. The server expects the message body and the timestamp to be signed. The signature must have a timestamp with the created value set to creation time. The expiry
attribute specifies when the timestamp will expire (that is, the current time must be less than the value of the creation time plus the value of expiry
). The clock-skew
attribute is used to adjust the system clocks, when the Web service client and the Web service are on different machines.
Lines 18 -22: These lines specify the message confidentiality policy. The server expects the content of the body to be encrypted.
Example 4-4 Sample Server-Side Configuration File with Operation-Level Decryption and Signature Verification
1. <oracle-webservices> 2. <webservice-description name="SecureHelloService"> 3. <port-component name="SecureHelloPort"> 4. <runtime enabled="security"> 5. <operations> 6. <operation name="sayHello"> 7. <runtime> 8. <security> 9. <inbound> 10. <verify-signature> 11. <tbs-elements> 12. <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> 13. <tbs-element name-space="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" local-part="Timestamp"/> 14. </tbs-elements> 15. <verify-timestamp created="true" expiry="28800"/> 16. <property name="clock-skew" value="3000" /> 17. </verify-signature> 18. <decrypt> 19. <tbe-elements> 20. <tbe-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> 21. </tbe-elements> 22. </decrypt> 23. </inbound> 24. </security> 25. </runtime> 26. </operation> 27. </operations> 28. </port-component> 29. </webservice-description> 30. </oracle-webservices>
This section describes how to create a client-side Web service security configuration file to generate a username token. In this example, the file is called clientConfig.xml
. The WebServicesAssembler tool appends the data found in this file into the <generated_name>
_Stub.xml
client-side deployment descriptor.
Note:
If you are using Oracle JDeveloper to secure your Web service, then the security configuration is automatically generated into the<generated_name>
_Stub.xml
file.The following general steps describe how to create the client-side Web service security configuration file.
Create a file using any text editor.
Example 4-5 provides a sample client-side configuration file named clientConfig.xml
.
Enter the XML elements to generate a username token security configuration in the file.
The following sections provide examples of client-side security configuration files for username token and for signature and encryption.
"Defining a Client-Side, Port Level Security Configuration for Username Token" provides a sample configuration file that allows a user name and password to be sent to access any operations exposed at the port level.
"Defining a Client-Side, Port-Level Security Configuration for XML Signature and Encryption" provides a sample configuration file that signs and encrypts the message body.
Save the file.
Example 4-5 illustrates a sample client-side Web services configuration file which enforces security on the port level. In this example, the client must send a user name and password to access any operations that the service exposes at the port level. Note that line numbers have been added for reference purposes only. They should not appear in your file.
See Also:
"Username Token Elements for Outbound Messages" provides more information on the <username-token>
element.
Lines 4-10: In this example, security is applied at port level. The <runtime enabled="security">
element indicates that at run time, the client will be secured based on the policy defined in the <security>
element. Since the security is configured at the port level, the same security will be applied to all operations of the Web service.
Lines 6-8: The <outbound>
clause is where you define the outbound message policy. The <username-token>
element indicates that a username token will be added to the security header with username SCOTT
and password TIGER
. You can also specify the password type as either PLAINTEXT
(default) or DIGEST
.
Example 4-5 Sample Client-Side Web Services Configuration File with Port-Level Username Token Security
1. <oracle-webservice-clients> 2. <webservice-client> 3. <port-info> 4. <runtime enabled="security"> 5. <security> 6. <outbound> 7. <username-token name="SCOTT " password="TIGER"/> 8. </outbound> 9. </security> 10. </runtime> 11. <operations> 12. <operation name="sayHello"/> 13. </operations> 14. </port-info> 15. </webservice-client> 16. </oracle-webservice-clients>
Example 4-6 illustrates a sample client-side Web services configuration file which enforces security on the port level. In this example, the configuration sets the security policy for the client side keystore, the key configuration policy, and the outbound message policy. Note that line numbers have been added for reference purposes only. They should not appear in your file.
Lines 4-24: These lines specify the security policy for the client side keystore, the key configuration policy, and the outbound message policy. You must generate the keystore and the signature and encryption keys. For more information on creating a keystore and adding keys, see "Using Keystores".
Lines 6-7: These lines specify the client side keystore path and signature key alias.
Lines 8-22: These lines specify the outbound message policy.
Lines 9-15: These lines specify the signature policy. In this example, these lines indicate that the body and timestamp must be signed.
Lines 16-21: Specify the encryption policy and the recipients key that will be used to encrypt the request.
Example 4-6 Sample Client-Side Web Services Configuration File with Port Level Signature and Encryption Security
1. <oracle-webservice-clients> 2. <webservice-client> 3. <port-info> 4. <runtime enabled="security"> 5. <security> 6. <key-store path="etc/testks.jks" store-pass="keystorepwd"/> 7. <signature-key alias="signalias" key-pass="signkeypwd"/> 8. <outbound> 9. <signature> 10. <tbs-elements> 11. <tbs-element name-space="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" local-part="Timestamp"/> 12. <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> 13. </tbs-elements> 14. <add-timestamp created="true" expiry="28800"/> 15. </signature> 16. <encrypt> 17. <tbe-elements> 18. <tbe-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> 19. </tbe-elements> 20. <recipient-key alias="encalias"/> 21. </encrypt> 22. </outbound> 23. </security> 24. </runtime> 25. <operations> 26. <operation name="sayHello"> 27. </operation> 28. </operations> 29. </port-info> 30. </port-component> 31. </webservice-description> 32. </oracle-webservices> 33. </webservice-client> 34. </oracle-webservice-clients>
The server requires username and password data to authenticate users trying to access the Web service secured with the username policy. To provide this data, you can enter information for each user in the instance level system-jazn-data.xml
file. You can find this file at OC4J_HOME
/j2ee/
<instance_name
>/config/system-jazn-data.xml
.
See Also:
For more information on the contents of the system-jazn-data.xml
file, see the Oracle Containers for J2EE Security Guide.
The Application Server Control console provides screens where you can create users and passwords and add them to the server.
See Also:
For more information, see the topic Managing Security Provider Roles and Users in the Application Server Control on-line help.
Table 4-1 lists the client JAR files required if you are assembling security into your Web service client.
See Also:
The "Web Service APIs and JARs" appendix in the Oracle Application Server Web Services Developer's Guide lists the other JARs that must appear on the classpath to compile a Web service client.
Table 4-1 Client JAR Files for Security
JAR Name and Path | Description |
---|---|
OC4J_HOME/jlib/jaxen.jar |
Contains the classes that define Jaxen—a Java XPath Engine capable of evaluating XPath expressions across multiple modes (such as dom4j, JDOM, and so on). |
OC4J_HOME/jlib/osdt_wss.jar |
Contains Oracle Security Developer's Toolkit Web services security (WS-Security) APIs. |
OC4J_HOME/jlib/osdt_cert.jar |
Contains the Oracle Security Developer's Toolkit cryptography APIs. |
OC4J_HOME/jlib/osdt_xmlsec.jar |
Contains Oracle Security Developer's Toolkit XML signing and encryption APIs. |
OC4J_HOME/jlib/osdt_core.jar |
Contains the Oracle Security Developer's Toolkit (OSDT) APIs |
OC4J_HOME/jlib/osdt_saml.jar |
Contains Oracle Security Developer's Toolkit Security Assertion Markup Language (SAML) APIs. |
OC4J_HOME/jlib/oraclepki.jar |
Contains the Oracle |
OC4J_HOME/j2ee/home/jazn.jar |
Contains the JAZN (Oracle JAAS provider) administration tool. |
OC4J_HOME/j2ee/home/jazncore.jar |
Contains the JAZN (Oracle JAAS provider) implementation. |
OC4J_HOME/j2ee/home/jaznplugin.jar |
Contains the JAZN (Oracle JAAS provider) custom plug-in module. |
You can secure a Web service on the transport level by using basic, digest, or client certification (client-cert) authentication. If your Web service was assembled from a version 2.1 or 3.0 EJB, you can secure it on the transport level by making additions to the oracle-webservices.xml
deployment descriptor. This section also provides information on how to write J2SE and J2EE clients to access Web services secured on the transport level.
With basic authentication, the user is prompted directly for a user name and password, without going through OracleAS Single Sign-On. A login module (such as RealmLoginModule
, for example) is used to generate a login dialog.
To specify basic authentication at the transport level, provide a value of BASIC
for the <auth-method>
subelement of <login-config>
in web.xml
. For example:
<web-app ...>
...
<login-config>
<auth-method>BASIC</auth-method>
...
<login-config>
...
</web-app>
See Also:
For more information on providing basic authentication, see the Oracle Containers for J2EE Security Guide.
With the digest authentication mechanism, the password that a client presents to authenticate itself is encrypted through the use of an MD5 digest. This is transmitted in the request message. From a user perspective, digest authentication behaves in the same way as basic authentication.
To specify digest authentication at the transport level, provide a value of DIGEST
for the <auth-method>
subelement of <login-config>
in web.xml
. For example:
<web-app ...>
...
<login-config>
<auth-method>DIGEST</auth-method>
...
<login-config>
...
</web-app>
See Also:
For more information on providing digest authentication see the Oracle Containers for J2EE Security Guide.
The client certification (client-cert) method authenticates the client through HTTPS. The user must possess a public key certificate.
To specify client-cert authentication at the transport level, provide a value of CLIENT-CERT
for the <auth-method>
subelement of <login-config>
in web.xml
. For example:
<web-app ...>
...
<login-config>
<auth-method>CLIENT-CERT</auth-method>
...
<login-config>
...
</web-app>
See Also:
For more information on providing client-cert authentication, see the Oracle Containers for J2EE Security Guide.
Version 2.1 and 3.0 Enterprise Java Beans (EJBs) can be exposed as Web services. You can define transport-level security constraints for Web services based on EJBs by configuring the <ejb-transport-security-constraint>
and <ejb-transport-login-config>
elements in the oracle-werbservices.xml
deployment descriptor.
The <ejb-transport-security-constraint>
element lets you specify whether the security constraints should apply to a SOAP port, a WSDL URL, or both. You can also specify a security role and a transport guarantee.
The <ejb-transport-login-config>
element lets you specify whether the EJB application uses basic authentication, digest authentication, or client certificate as its authentication mechanism.
The client of a secured EJB Web service can be configured to pass a username and password to the secured service in either of the following ways:
statically—enter configuration parameters into the proprietary deployment descriptors, such as orion-ejb-jar.xml
or orion-web.xml
file.
programmatically—"Accessing Web Services That Require a Username and Password" provides more information on writing a client that can access a secured Web service.
See Also:
For more information on how to use the elements described in this section, see the oracle-webservices-10_0.xsd
schema and "Packaging and Deploying Web Services" in the Oracle Application Server Web Services Developer's Guide.
Example 4-7 illustrates <ejb-transport-security-constraint>
and its subelements in the oracle-webservices.xml
deployment descriptor. This element associates transport-level security constraints for a version 2.1 or 3.0 EJB exposed as a Web service. The URL of the EJB exposed as a Web service is indicated by the <endpoint-address-uri>
element in the port component. The sub-elements <wsdl-url>
and <soap-port>
are identifiers that let you choose whether the security constraints will apply to a WSDL URL or to a SOAP port. If <wsdl-url>
and <soap-port>
are both present or both absent in the <ejb-transport-security-constraint>
element, then the security constraints will apply to both the WSDL and the SOAP port.
Example 4-7 <ejb-transport-security-constraint> Element in oracle-webservices.xml
... <port-component name="String"> <endpoint-address-uri>String</endpoint-address-uri> <ejb-transport-security-constraint> <wsdl-url/> <soap-port/> <role-name>Manager</role-name> <role-name>Administrator</role-name> <transport-guarantee>NONE</transport-guarantee> </ejb-transport-security-constraint> ... </port-component> ...
Example 4-8 illustrates <ejb-transport-login-config>
and its subelements in the oracle-webservices.xml
deployment descriptor. This element configures the transport-level authentication method (such as basic, digest, or client certificate) and the realm name that should be used for this EJB application. The URL of the EJB application exposed as a Web service is indicated by the <endpoint-address-uri>
element in the port component.
If a Web service is secured by either HTTP authentication or WS-Security username token authentication, then the client must provide a username and password in order to pass messages to it.
The following sections describe the properties and field values that a J2SE or J2EE client can use to access a Web service secured by HTTP authentication or WS-Security username token authentication. It also describes how to make these properties and values available to the client programatically or as part of a static configuration.
For HTTP authentication, the following properties can be used by the javax.xml.rpc.Stub
and javax.xml.rpc.Call
interfaces.
javax.xml.rpc.security.auth.username javax.xml.rpc.security.auth.password
For convenience, these interfaces also define constant field values for these properties.
javax.xml.rpc.Stub.USERNAME_PROPERTY javax.xml.rpc.Stub.PASSWORD_PROPERTY javax.xml.rpc.Call.USERNAME_PROPERTY javax.xml.rpc.Call.PASSWORD_PROPERTY
For WS-Security, a Web service client can pass a username and password by using stub field values. The following sections describe using these stub field values:
Stub.USERNAME_PROPERTY Stub.PASSWORD_PROPERTY
You can use Java properties (that is,javax.xml.rpc.Stub.USERNAME_PROPERTY
and PASSWORD_PROPERTY
, andjavax.xml.rpc.Call.USERNAME_PROPERTY
and PASSWORD_PROPERTY
) to pass username and password values programatically to the client.
Following are two examples, one for HTTP authentication and one for WS-Security username token authentication. The examples will pass the username and password to the client. The username and password are added to one of the generated Web service client files. The file is called <service>SoapHttp_Stub.java
. This technique can be used in a J2EE Web service client only.
In the following example for HTTP authentication, the generated file EchoSoapHttp_Stub.java
client file is accessing the Echo
Web service. This file is edited to add the username and password credentials. The javax.xml.rpc.security.auth.username
and password
properties are added with the _setProperty
method.
/* * public constructor */ public EchoSoapHttp_Stub(HandlerChain handlerChain) { super(handlerChain); _setProperty(ENDPOINT_ADDRESS_PROPERTY, "http://aaabbb.mycompany.com:8888/WebServicesDemos-Echo-context- root/echoSoapHttpPort"); // Added for HTTP authentication _setProperty("javax.xml.rpc.security.auth.username","helen"); _setProperty("javax.xml.rpc.security.auth.password","welcome"); setSoapVersion(SOAPVersion.SOAP_11); setServiceName( new QName("http://demo/","echo")); setPortName( new QName("http://demo/","echoSoapHttpPort")); setupConfig("echoclient/proxy/runtime/EchoSoapHttp_Stub.xml"); }
In the case of WS-Security username token, you must first generate support for the token into your client. When you assemble the client with the WebServicesAssembler genProxy
command, specify a client configuration file with the ddFileName
argument. The client configuration file is where you enable username token authentication. Example 4-9 illustrates a sample genProxy
command.
Example 4-9 Sample genProxy Command
<oracle:genProxy
wsdl="http://localhost:8888/webservice/webservice?WSDL"
unwrapParameters="false"
output="build/src/client"
packageName="MyService"
ddFileName="clientConfig.xml"
>
<classpath>
<pathelement path="${common.webservices.class.path}"/>
<pathelement location="${ORACLE_HOME}/webservices/lib/wsa.jar}"/>
</classpath>
</oracle:genProxy>
Example 4-10 illustrates the contents of a sample client configuration file that enables WS-Security username token. The file is based on the oracle-webservices-client-10_0.xsd
. Note the presence of the <username-token>
element in the <outbound>
section. You do not have to specify username
and password
attributes for the token as they will be supplied programatically.
Example 4-10 Sample Client Configuration File for WS-Security Username Token Authentication
<oracle-webservice-clients>
<webservice-client>
<port-info>
<runtime enabled="security">
<security>
<outbound>
<username-token name="" password-type="PLAINTEXT" add-nonce="true" add-created="false"/>
</outbound>
</security>
</runtime>
<operations>
<operation name="echoUser"/>
</operations>
</port-info>
</webservice-client>
</oracle-webservice-clients>
Example 4-11 illustrates a Java program that is calling the generated proxy client code. The username and password can be passed programatically using the properties Stub.USERNAME_PROPERTY
and Stub.PASSWORD_PROPERTY
.
Example 4-11 Providing a Username and Password Programatically
... Context ic = new InitialContext(); Service service = (Service) ic.lookup("java:comp/env/service/MyEchoServiceRef"); //Service.getPort(portQName,SEI class) EchoInterface echoPort = (EchoInterface) service.getPort(portQName,echo.EchoInterface.class); Stub port = (Stub) echoPort; port.setProperty(Stub.USERNAME_PROPERTY, "helen"); port.setProperty(Stub.PASSWORD_PROPERTY, "welcome"); ...
As an alternative to the properties, you can use the following methods provided in the generated proxy:
setUsername(String username) setPassword(String password)
To pass a static configuration, edit the appropriate orion-*.xml
file for your Web service. This technique can be used by either J2EE or J2SE Web service clients.
You can pass the username and password to access a Web service in a deployment descriptor. To do this, you must manually edit the <service-ref-mapping>
element in the orion-*.xml
file for your service.
If you are accessing the service endpoint with a static client proxy add, a <stub-property>
subelement to the <service-ref-mapping>
element. If you are dynamically invoking the service endpoint using Dynamic Invocation Interface (DII), add a <call-property>
element instead.
See Also:
For more information on the <call-property>
and <stub-property>
elements, see the Oracle Application Server Web Services Developer's Guide.
The following steps describe how to edit the <service-ref-mapping>
clause and the values you must provide for the <call-property>
and <stub-property>
elements.
Edit the <service-ref-mapping>
element of the appropriate orion-*.xml
deployment descriptor for your Web service.
If you are working with a client proxy, enter a <stub-property>
subelement for the username and password, or
If you are dynamically invoking the service endpoint, enter a <call-property>
subelement.
Specify the username property javax.xml.rpc.security.auth.username
and its value in the <name>
and <value>
subelements of the stub-
or call-property
element entered in Step 1.
Specify the username property javax.xml.rpc.security.auth.password
and its value in the <name>
and <value>
subelements of the stub-
or call-property
element entered in Step 1.
When you generate your Web service client, specify the orion-*.xml
deployment descriptor as input to the WebServicesAssembler genProxy
command.
Example 4-12 illustrates a sample <service-ref-mapping>
clause which uses <stub-property>
elements to specify a username and password to access the secured Web service. The javax.xml.rpc.security.auth.username
and password
properties and their values are added as child elements of <stub-property>
.
Example 4-12 Sample HTTP Authentication Configuration in an orion-*.xml File
... <service-ref-mapping name="service/MyEchoServiceRef"> ... <stub-property> <name>javax.xml.rpc.security.auth.password</name> <value>welcome</value> </stub-property> <stub-property> <name>javax.xml.rpc.security.auth.username</name> <value>helen</value> </stub-property> </service-ref-mapping > ...
In the case of WS-Security username token, you generate support for the token into the client. When you assemble the client with the WebServicesAssembler genProxy
command, specify a client configuration file with the ddFileName
argument. Example 4-13 illustrates a sample genProxy
command.
Example 4-13 Sample genProxy Command
<oracle:genProxy
wsdl="http://localhost:8888/webservice/webservice?WSDL"
unwrapParameters="false"
output="build/src/client"
packageName="MyService"
ddFileName="clientConfig.xml"
>
<classpath>
<pathelement path="${common.webservices.class.path}"/>
<pathelement location="${ORACLE_HOME}/webservices/lib/wsa.jar}"/>
</classpath>
</oracle:genProxy>
Example 4-14 illustrates a sample client configuration file that enables WS-Security username token authentication. The file is based on the oracle-webservices-clients.xsd
. Note the presence of the <username-token>
element in the <outbound>
section. In this case, specify username
and password
attributes for the token. The values of these attributes allows messages sent from the client to access the service.
Example 4-14 Sample Client Configuration File for WS-Security Username Token Authentication
<oracle-webservice-clients><webservice-client><port-info><runtime enabled="security"> <security> <outbound> <username-token name="" username="helen" password="welcome" password-type="PLAINTEXT" add-nonce="true" add-created="false"/> </outbound> </security> </runtime> <operations> <operation name="echoUser"/> </operations> </port-info> </webservice-client> </oracle-webservice-clients>
The Oracle Web Service Security implementation provides seamless integration for propagating the user's identity when a Web service invokes an EJB.
The Web service is authenticated by using message level security. Re-authentication is not required when accessing the EJB from the Web service. The same Web service user identity is propagated to the EJB. The EJB application can access the user identity by using standard EJB methods such as javax.ejb.EjbContext.getCallerPrincipal
.
Further access checks can be performed by using javax.ejb.EjbContext.isCallerInRole
.
Note:
The EJB application must be configured with J2EE security. Refer to "EJB Security Configuration" in the Oracle Containers for J2EE Security Guide for more information.The WebServicesAssembler tool assists in assembling OracleAS Web Services. It enables you to generate the artifacts required to develop and deploy Web services, regardless of whether you are creating the service top down (from a WSDL) or bottom up from Java classes, EJBs, JMS destinations, or database resources. The WebServicesAssembler tool can also be invoked to create Web service client objects based on a WSDL.
The WebServicesAssembler tool can be invoked either on the command line or by Ant tasks. The WebServicesAssembler tool gives you flexibility in how you assemble a Web service. You can break the assembly process into a number of steps that let you more closely control how the Web service is created.
The following list provides a summary of the tasks that you can perform with the WebServicesAssembler tool.
See Also:
The "Using WebServicesAssembler" chapter in the Oracle Application Server Web Services Developer's Guide provides detailed information on how to use WebServicesAssembler commands to perform each task.
Web service assembly—assemble Web services. These commands create all of the files necessary to create a deployable archive such as a WAR, an EAR, or an EJB JAR.
WSDL management—perform actions on a WSDL, such as generate a WSDL for bottom-up development, manage its contents and location, and determine whether it can be processed by WebServicesAssembler.
Java generation—generate code to create a Java interface from a WSDL, a proxy/stub, or JAX-RPC value type classes.
Deployment descriptor generation—generate deployment descriptors for EARs, WARs, or EJB JARs.
Information—return a short description of WebServicesAssembler commands and the version number of the tool.
On the server, you can obtain the name of an authorized user from the username (plaintext or digest), SAML, or X.509 security tokens. This information can be used for further validation checks before the user is allowed to access additional server resources. This section describes how you can obtain a user identity with the AccessControlContext
and ServiceLifeCycle
APIs.
Getting an Authenticated Subject with the AccessControlContext API
Getting an Authenticated Principal with the ServiceLifeCycle API
You can use methods from the java.security.AccessControlContext
, java.security.AccessController
, and javax.security.auth.Subject
classes to get the authenticated subject.
See Also:
For more information on the classes and methods described in this section, see the API for the java.security
and javax.security.auth
packages at the following Web site:
Note:
One of the purposes of getting the authenticated subject is to perform JAAS Provider authorization. "Performing JAAS Provider Authorization on a Web Service" provides a summary of how to perform this type of authorization on a Web service.The following general steps describe how to get the authenticated subject from an AccessController
object.
Create an AccessControlContext
object by calling the AccessController.getContext
method. The getContext
method takes a "snapshot" of the current calling context and returns it in an AccessControlContext
object.
Get the subject of the context by using the Subject.getSubject
method.
Example 4-15 illustrates using the AccessControlContext
, AccessController
, and Subject
APIs to get the name of an authorized user.
You can use the javax.xml.rpc.server.ServiceLifecycle
and ServletEndpointContext
interfaces to obtain user information from the SAML, username, or X.509 security tokens. For example, the ServletEndpointContext.getUserPrincipal
method returns the name of the authenticated user; the ServletEndpointContext.isUserInRole
method returns whether the user belongs to a specific role.
See Also:
For more information on the ServiceLifecycle
and ServletEndpointContext
interfaces, see the API for the javax.xml.rpc.server
package at the following Web site:
To obtain user information from the Web service, follow these general steps:
Implement the ServiceLifecycle
interface for the Web service.
In the implementation of the ServiceLifecycle.init
method, cast the context
parameter to ServletEndpointContext
.
Call methods, such as getUserPrincipal
and isUserInRole
, on the ServletEndpointContext
context
parameter to obtain user information.
Example 4-16 illustrates how to obtain the name of an authenticated user from a secure Web service. The SecureService
class in the example implements the ServiceLifecycle
interface. In the init
method implementation, the context
parameter is cast to the ServletEndpointContext
interface. The getUserPrincipal
method returns access to the authenticated user name, which is obtained by a call to getName
.
Example 4-16 Obtaining the Name of an Authenticated User with the ServiceLifeCycle API
package test; public class SecureService implements javax.xml.rpc.server.ServiceLifecycle { private javax.xml.rpc.server.ServletEndpointContext context; public void init(Object obj) throws javax.xml.rpc.ServiceException { context = (javax.xml.rpc.server.ServletEndpointContext)obj; } public String helloUser(String message) throws java.rmi.RemoteException { java.security.Principal principal = context.getUserPrincipal(); if(principal == null) { throw new RuntimeException("Principal not found"); } String userName = principal.getName(); return "Hi "+userName+"! "+message; } public void destroy() { context = null; } }
OracleAS Web Services includes OracleAS JAAS Provider, a highly scalable Java Authentication and Authorization Service (JAAS) provider. OracleAS Web Services can protect resources using JAAS authorization for enforcing fine-grained access control over protected resources.
The following general steps describe how to perform JAAS authorization on a Web service.
Get the authenticated subject from the security token.
See "Getting an Authenticated Subject with the AccessControlContext API" for more information on obtaining the authenticated subject.
Use the authenticated subject to issue JAAS authentication calls, such as checkPermission
.
See Also:
For more information on JAAS Provider authorization, see the Oracle Containers for J2EE Security Guide.
Oracle Security Developer Tools (OSDT) provide you with the cryptographic building blocks necessary for developing robust security applications ranging from basic tasks like secure messaging to more complex projects such as securely implementing a service-oriented architecture. The tools build upon the core foundations of cryptography, public key infrastructure, Web services security and federated identity management.
See Also:
You can find the Reference Guide and Javadocs for OSDT at the following Web site:
http://download-east.oracle.com/docs/cd/B14099_15/idmanage.htm
Chapter 5, "Secure Web Service Usage Scenarios", presents a number of use cases that describe the different ways in which you can integrate security into a Web service.