Oracle® Application Server Web Services Security Guide 10g (10.1.3.5.0) Part Number E13983-01 |
|
|
View PDF |
This chapter describes the client- and server-side configurations for Web services security. These security configurations are stored in XML files. On the server, this configuration is stored in the oracle-webservices.xml
deployment descriptor file. On a client, it is stored in the <
generated_name
>_Stub.xml
deployment descriptor file.
You can create these files and configure the security elements in any of the following ways:
Oracle JDeveloper IDE—Use the Oracle JDeveloper IDE to create and configure Web service and client security. This tool provides wizards that help you create a security configuration. It stores the results in an oracle-webservices.xml
deployment descriptor for the server and a <
generated_name
>_Stub.xml
deployment descriptor for the client.
Application Server Control—Use Application Server Control to configure security for all of the operations in a particular Web services port, or configure specific security settings for individual operations in the port. The content of the oracle-webservices.xml
and <
generated_name
>_Stub.xml
files are not changed. The changes are made to the wsmgmt.xml
file which contains the Web service security and management policies currently in force. Application Server Control can change the configuration only for Web services, not for their clients.
For more information, see the topic Configuring Security for a Web Service in the Application Server Control on-line help.
WebServicesAssembler—Use this command line tool to configure and assemble the security elements in the Web service and client.
Manual configuration—To manually configure security, enter values for the security elements directly in the server and client deployment descriptor files.
The Web services security configuration for the client and server is based on inbound and outbound policies. These policies are defined in "Security Policies".
Figure 2-1 illustrates the deployment descriptors that are generated when you configure Web service security and how information is passed to the client and service. The following steps correspond to the numbers in the figure.
The security configuration for a Web service client. Configuring security for a client will generate the <
generated_name
>_Stub.xml
deployment descriptor with a security configuration. The client interceptor uses the <
generated_name
>_Stub.xml
deployment descriptor at runtime to generate the security header (if an <outbound>
element is configured) and enforce the security policy (if an <inbound>
element is configured).
The security configuration for a Web service (server side). Configuring security for the Web service application will generate an oracle-webservices.xml
deployment descriptor with the security configuration.
When you deploy the Web service, the wsmgmt.xml
file will be updated with the Web service security configured in the oracle-webservices.xml
deployment descriptor as described in Step 2. The wsmgmt.xml
file is an instance-level configuration file, which holds the entire security configuration for the Web services deployed in an OC4J instance. The server interceptor uses the wsmgmt.xml
file at runtime to enforce the security policy (if an inbound element is configured) or generate the security header (if an outbound element is configured).
In the diagram, the dashed boxes indicate that for a given <outbound>
element in the Web service client configuration, there is a corresponding <inbound>
element in the Web service configuration. Similarly, for a given <outbound>
element in the Web service, there is a corresponding <inbound>
element in the client configuration file.
For example, a <username-token>
subelement in the client <outbound>
element indicates that the client will be sending a username token. In the Web service <inbound>
element there is corresponding <verify-username-token>
element which indicates that the Web service must verify the username token.
Figure 2-1 How Policies Work Together for Client- and Server-side Web Services
This section provides definitions of the security configuration elements. The same set of security configuration elements can appear at the global, port, and operation level. The values for security configuration elements set at the operation level override settings made at the port and global levels. Port-level settings override global-level settings.
In general, OracleAS Web Services Security elements appear in the header or body of SOAP messages. The client uses the same set of security configuration elements as the server. Example 2-1 illustrates the security configuration elements as they are used in the server-side oracle-webservices.xml
deployment descriptor.
Example 2-1 Security Configuration Elements in the Server-Side Configuration File
<oracle-webservices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/oracle-webservices-10_0.xsd"> <webservice-description name="XYZService "> <port-component name="XYZPort"> <runtime enabled="security"> <security> <key-store store-pass="abc" path="./mykeystore.jks"/> <signature-key alias="signkey" key-pass="signkeypass"/> <encryption-key alias="enckey" key-pass="enckeypass"/> </security> </runtime> <operations> <operation name="sayHello" input="{http://tempuri.org/}/sayHello"> <runtime> <security> <inbound> <verify-username-token /> <verify-x509-token /> <verify-saml-token/> <verify-signature> <signature-methods> <signature-method> RSA-SHA1 </signature-method> </signature-methods> <tbs-elements> <element name-space="http://schemas.xmlsoap.org/soap/envelope" local-part="Body"/> </tbs-elements> <verify-timestamp expiry="28800" created="true"/> </verify-signature> <decrypt> <encryption-methods> <encryption-method> 3DES </encryption-method> </encryption-methods> <keytransport-methods> <keytransport-method> RSA-1_5 </keytransport-method> </keytransport-methods> <tbe-elements> <element name-space="http://schemas.xmlsoap.org/soap/envelope" local-part="Body" mode="CONTENT"/> </tbe-elements> </decrypt> </inbound> <outbound> <signature> <tbs-elements> <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> </tbs-elements> </signature> <encrypt> <recipient-key alias="enckey"/> <tbe-elements> <tbe-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body" /> </tbe-elements> </encrypt> </outbound> </security> </runtime> </operation> </operations> </port-component> </webservice-description> </oracle-webservices>
Example 2-2 illustrates the security configuration elements as they are used in the client-side <
generated_name
>_Stub.xml
deployment descriptor.
Example 2-2 Security Configuration Elements in the Client-Side Configuration File
<oracle-webservice-clients> <webservice-client> <port-info> <runtime enabled="security"> <key-store path="mykeystore.jks" store-pass="password"/> <signature-key alias="signkey" key-pass="signkeypass"/> <security> <outbound> <username-token name="SCOTT" password="TIGER"/> <signature> <tbs-elements> <tbs-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> </tbs-elements> <add-timestamp created="true" expiry="28800"/> </signature> <encrypt> <recipient-key alias="reckey"/> <tbe-elements> <tbe-element name-space="http://schemas.xmlsoap.org/soap/envelope/" local-part="Body"/> </tbe-elements> </encrypt> </outbound> </security> </runtime> <operations> <operation name="sayHello"/> </operations> </port-info> </webservice-client> </oracle-webservice-clients>
The <key-store>
element is required and can occur at both global and port levels on the server, and at port level on the client. A global keystore setting applies to all applications deployed within the instance; it can be overridden by a specific port-level keystore. If you make any changes to the value of the <key-store>
element, then you must restart the application to enable the new values.
Table 2-1 Keystore Settings
The <signature-key>
and <encryption-key>
are required at port level if a port level keystore is specified or when selecting keys from a global keystore. If these keys are not configured at the port level, then the global-level values are used.
If you make any changes to the values of the <signature-key>
or <encryption-key>
elements, then you must restart the application to enable the new values.
Table 2-2 General Security Settings
Element Name | Description |
---|---|
<signature-key> |
Points to the key required by |
<encryption-key> |
Points to the key required for decrypting the message. This element has these attributes: The |
A nonce is a random value that can be included in the username token to prevent replay attacks. The nonce is cached by the server. OracleAS Web Services Security lets you configure a nonce value that can be inserted into the username token. For more information on configuring the nonce, see "Configure the Nonce Cache with a Digest Password".
Table 2-3 Nonce Configuration Settings
The following sections describe the security elements that can be set for inbound messages.
The inbound message section in the oracle-webservices.xml
and <
generated_name
>_Stub.xml
deployment descriptors are delimited with <inbound>
elements. The <inbound>
element encapsulates the security configuration policy with respect to incoming messages. The <inbound>
element can occur as a subelement of <security>
at the global, port, and operation level.
Inbound security defines the context-specific security policy for incoming messages. In the case of a client, it corresponds to the security policy associated with receiving a response. In the case of a service, it corresponds to the security policy associated with receiving a request.
The <verify-username-token>
, <verify-x509-token>
, and <verify-saml-token>
elements are the authentication elements for inbound messages. Authentication elements are optional and can be configured for the server side. The Web service application can choose to allow a username token, an X.509 token, and a SAML token, in any combination.
A Web service client is not required to send an authentication token. If an authentication token is required, only one can be sent. The user will be authenticated based on the token(s) sent in the SOAP request.
Table 2-4 summarizes the security tokens that can be inserted into an inbound message configuration.
Table 2-4 Authentication Elements for Inbound Messages
Element Name | Description |
---|---|
Specifies the security policy for username tokens. See "Username Token Elements for Inbound Messages" for more information on this security token. |
|
Specifies the authentication policy with respect to X.509 tokens. See "X.509 Token Elements for Inbound Messages" for more information on this security token. |
|
Specifies whether the incoming SOAP message carrying a SAML assertion should be verified. See "SAML Token Elements for Inbound Messages" for more information on this security token. |
The <verify-username-token>
element specifies the security policy for username tokens. This is an optional subelement of the <inbound>
element and can occur only once within the element. This subelement has these attributes:
password-type
—Type of password authentication: plaintext
or digest
. Default is plaintext
.
require-nonce
—Specifies whether a nonce must be included in the username token. This attribute is required for digest authentication. Default is false
.
require-created
—Specifies whether the creation time must be included in the username token. This attribute can be used with either plain text or digest password authentication. However, it must be set to true
for digest authentication. Default is false
.
The <verify-username-token>
element can also have an optional <property>
subelement. Table 2-5 describes the property element and its value.
Table 2-5 Subelements of the <verify-username-token> Element
Element Name | Description |
---|---|
<property> |
Properties that can be set on the
OracleAS Web Services Security defines the following property on
See "Configure the Service to Not Require a Password" for examples of how to use this property. |
The <verify-x509-token>
element specifies the authentication policy with respect to X.509 tokens. It is an optional subelement of the <inbound>
element.
The <verify-saml-token>
element is an optional subelement of the <inbound>
element. It specifies whether the incoming SOAP message carrying a SAML assertion should be verified.
Table 2-6 lists the subelements of the <verify-saml-token>
element. All of the subelements are optional.
Table 2-6 Subelements of the <verify saml-token> Element
The <verify-signature>
element is an optional subelement of the <inbound>
element. It specifies the integrity or signature requirements of the receiver. These requirements include the name of the signature verification algorithm and the message parts to be verified. The <verify-signature>
element occurs only once within the <inbound>
element. Table 2-7 describes the subelements of the <verify-signature>
element. All of the subelements are optional.
Table 2-7 Subelements of the <verify-signature> Element
Element Name | Description |
---|---|
Collection of |
|
List of elements that are expected to be signed in the incoming request. This element has these attributes: |
|
Verifies the timestamp in the incoming SOAP message. (This timestamp is configured with the |
|
<property> |
Properties that can be set on the
OracleAS Web Services Security defines the following property on
|
The <decrypt>
element is an optional subelement of the <inbound>
element. It specifies the confidentiality requirements of the receiver. The <decrypt>
element occurs only once within an <inbound>
element.
Table 2-8 describes the elements that are available to set decryption details for inbound messages. All of the subelements are optional.
Table 2-8 Subelements of the <decrypt> Element
Element Name | Description |
---|---|
Collection of
Table 2-9 lists the encryption algorithm URIs and corresponding short names recognized by Web services security. Table 2-19 provides more information on the |
|
Collection of
Table 2-10 lists the algorithm URIs and corresponding short names recognized by Web services security. |
|
Collection of
|
|
<property> |
Properties that can be set on the
OracleAS Web Services Security defines the following property on
|
Table 2-9 lists the URIs of the encryption algorithms recognized by Web service security and their short names.
Table 2-9 URIs and Short Names for Encryption Algorithms
URI of the Algorithm | Short Name |
---|---|
http://www.w3.org/2001/04/xmlenc#3des-cbc |
3DES |
http://www.w3.org/2001/04/xmlenc#aes128-cbc |
AES-128 (default) |
http://www.w3.org/2001/04/xmlenc#aes256-cbc |
AES-256 |
Table 2-10 lists the URIs of the key transport algorithms recognized by Web service security and their short names.
The following sections describe the security elements that can be set for outbound messages.
The outbound message section in the oracle-webservices.xml
and <
generated_name
>_Stub.xml
deployment descriptors are delimited with <outbound>
elements. Outbound security defines the context-specific security policy for the outgoing messages. In the case of a client, it corresponds to the security policy associated with sending a request. In the case of a service, it corresponds to the security policy associated with sending a response.
Example 2-2 summarizes the security tokens that can be inserted into an outbound message configuration.
Table 2-11 Outbound Security Tokens
Element Name | Description |
---|---|
Specifies a username token that must be inserted into the security header block. See "Username Token Elements for Outbound Messages" for more information on this security token. |
|
If this element is present, an X.509 certificate is inserted into the security header block. See "X.509 Token Elements for Outbound Messages". |
|
The client interceptor uses the contents of this element to create the SAML assertion for the user identity. See "SAML Token Elements for Outbound Messages" for more information on this security token. |
|
Specifies the algorithm for signing outgoing messages or individual message elements. See "Signature Elements for Outbound Messages" for more information on this security token. |
|
Specifies the encryption algorithm, key transport algorithm, and recipient key for encrypting outgoing messages or message elements. See "Encryption Elements for Outbound Messages" for more information on this security token. |
The <username-token>
element is an optional element of the outbound policy. This element specifies the username token that must be inserted into the security header block. Only one instance of the element is permitted.
A client can pass a username and password by using a callback handler. The callback handler is a user-defined class that handles javax.security.auth.Namecallback
and Passwordcallback
. The name of the class can be specified in the <username-token>
element's cbhandler-name
attribute.
If this element is not present, the client runtime can build the username token using the Stub.USERNAME_PROPERTY
and Stub.PASSWORD_PROPERTY
supported by JAX-RPC. The Web service client can either use the Stub
properties or use a static configuration by specifying the user name and password in a deployment descriptor. For more information on using the Stub
properties, see "Pass the User Name and Password with Stub Properties".
Table 2-12 describes the <username-token>
attributes. All of the attributes are optional.
Table 2-12 Attributes of the <username-token> Element
Attribute Name | Description |
---|---|
The username to be inserted into the token. |
|
The actual password of the user. |
|
Type of password: |
|
The name of the callback handler that inserts the username token into the SOAP message. The callback handler is a user-defined callback handler class that handles |
|
Specifies whether a nonce should be added to the request. For digest authentication, this attribute is required and must be set to |
|
Specifies whether a creation time should be added to the request. For digest password authentication, this attribute is required and must be set to |
The <x509-token>
element is an optional element of the <outbound>
configuration. This element indicates that an X.509 signing certificate will be inserted into the request. A direct reference to the X.509 certificate (signer's certificate) is added. You must have the signature key configured for this configuration to work.
Instead of passing a certificate (using direct reference), you could also pass the subject key identifier of the certificate. "Using the Subject Key Identifier for Signing" provides more information on how to pass the subject key identifier.
Table 2-13 describes the subelement of the <x509-token>
element.
Table 2-13 Subelement of the <x509-token> Element
Element Name | Description |
---|---|
<property> |
Properties that can be set on the
OracleAS Web Services Security defines the following property on
|
The <saml-token>
element is an optional element of the <outbound>
policy. The client interceptor refers to the <saml-token>
element in the outbound policy for creating the actual SAML assertion for the user identity. "How to Configure a SAML Token for the Client-Side" provides information on how to provide dynamic and static configuration of SAML tokens. Table 2-14 describes the attributes of the <saml-token>
element. All of the attributes are optional.
Table 2-14 Attributes of the <saml-token> Element
Attribute | Description |
---|---|
(required) You can choose a name for the assertion subject by providing a value for the [realm-name The name represents the name of the assertion. The assertion name can be prefixed with the assertion's realm-name. If the realm name is already present, then it is set as the name qualifier. The |
|
Specifies the format of the assertion subject name. This element can have any of the following values:
|
|
Identifies the name of the user-defined class that will handle the The callback handler must be able to handle SAML token callback. "Writing a SAML Token Callback Handler" provides more information on how to write this handler. |
|
Used to get the SAML assertion issuer name. The default value is |
Table 2-15 describes the subelements of the <saml-token>
element. All of the subelements are optional.
Table 2-15 Subelements of the <saml-token> Element
Element Name | Description |
---|---|
The supported confirmation methods are "Configuring Confirmation Methods" provides more information on confirmation methods and on how to configure this element. |
|
The This properties file contains one or more attribute name/value pairs for asserting a user's identity. The attribute name can be prefixed with an optional namespace. For example: [attribute-name-space The following is an example of a value that can appear in an
For more information on using the |
|
Enables you to retrieve a SAML token from an external SAML authority. For more information, see "Elements for Retrieving SAML Tokens from an External SAML Authority". |
The <saml-authority>
element is an optional subelement of <saml-token>
. A configuration of the <saml-authority>
element and its attributes allow you to retrieve a SAML token from an external SAML authority by issuing a SAMLP request. "Retrieving a SAML Token from an External SAML Authority" provides more information on configuring this element. Table 2-16 describes the attributes of <saml-authority>
.
Table 2-16 Attributes of the <saml-authority> Element
Name | Description |
---|---|
(Required) Specifies the SAML Responder URL. |
|
Specifies the username that is used to provide authentication to the SAML authority. This attribute is required for the |
|
(Optional) Specifies the password that is used to provide authentication to the SAML authority. The |
|
(Optional) If this boolean attribute is See "Keystore Elements" and "Signature and Encryption Key Elements" for more information on configuring the keystore and the signature key. |
Table 2-17 describes the subelements of the <signature>
element. The subelements describe the options that are available for signing outbound messages.
Table 2-17 Subelements of the <signature> Element
Element Name | Description |
---|---|
Collection of Table 2-18, "Signature Algorithms and Short Names" lists the algorithm URIs and corresponding short names that are recognized by OracleAS Web Services Security. |
|
Collection of |
|
Adds a timestamp to the outbound SOAP message. (This timestamp is verified by setting the |
Table 2-18 lists the signature algorithms recognized by Web service security and their associated short names.
The <encrypt>
element is an optional subelement of the <outbound>
element. It specifies confidentiality requirements of the sender. The <encrypt>
element can occur only once within an <outbound>
element.
Table 2-19 describes the encryption elements that are available for outbound messages.
Table 2-19 Subelements of the <encrypt> Element
Element Name | Description |
---|---|
Specifies the encryption method to be used for encrypting the elements of the outbound SOAP message. Only one encryption method can be listed under the
Table 2-9 lists the URIs and corresponding short names for the encryption algorithms recognized by Web services security. |
|
A
Table 2-10 lists the URIs and corresponding short names of the algorithms recognized by Web services security. |
|
Collection of
|
|
The key alias of the recipient, which is used to encrypt the data encryption key. The data encryption key is the generated symmetric key that is used to encrypt the actual data. The data encryption key itself is also encrypted using the recipient's public key. The recipient key may or may not have a key usage extension. If the recipient key does have a key usage extension, then it must be of the type This element has these attributes: |
|
The Web service client has sent a signed SOAP message and the Web service application has successfully verified the signature. When the Web service application sends a response back to the same client, it can choose to encrypt the response with the signature certificate that the client sent in the first message exchange. The |