12.7. Securing Operations and Messages
This section explains how to specify security mechanisms at the operation level and at the message level.
You can specify security mechanisms at the following levels:
At times, you may need to configure different operations with different supporting tokens. You may wish to configure security at the operation level, for example, in the situation where only one operation requires a UsernameToken to be passed and the rest of the operations do not require this, or in the situation where only one operation needs to be endorsed by a special token and the others do not.
Input Message and Output Message
Security mechanisms at this level are used to specify what is being protected and the level of protection required.
In this section, you can specify parts of a message that require integrity protection (digital signature) and/or confidentiality (encryption). When you do this, the specified part of the message, outside of security headers, requires signature and/or encryption. For example, a message producer might submit an order that contains an orderID header. The producer signs and/or encrypts the orderID header (the SOAP message header) and the body of the request (the SOAP message body). Parts that can be signed and/or encrypted include the body, the header, the local name of the SOAP header, and the namespace of the SOAP header.
You can also specify arbitrary elements in the message that require integrity protection and/or confidentiality. Because of the mutability of some SOAP headers, a message producer may decide not to sign and/or encrypt the SOAP message header or body as a whole, but instead sign and/or encrypt elements within the header and body. Elements that can be signed and/or encrypted include an XPath expression or a URI which indicates the version of XPath to use.
This section covers the following topics:
To Specify Security at the Operation, Input Message, or Output Message Level
To specify security mechanisms at the level of the operation, input message, or output message, perform the following steps.
Right-click the web service and select Web Service Attributes.
The Web Service Attributes editor is displayed.
- Select Secure Service.
Select a security mechanism.
The following mechanisms do not support Input message level protection:
- Expand the operation Operation node (for example, the add Operation node.) It should look like Web Service Attributes Editor Page: Operation Level.
Expand the operation section.
The section will be grayed out if Secure Service is not selected.
Select an option from the Transactions list to specify
a level at which transactions will be secured.
For this release, transactions will only use SSL for security. Transactions are discussed in Using Atomic Transactions.
Expand the Input Message section.
This section will be grayed out if Secure Service is not selected.
Specify the following options, as appropriate:
Authentication Token : Specifies which supporting token will be used to sign and/or encrypt the specified message parts. Options include Username, X509, SAML, Issued, or None. For further description of these options, read Supporting Token Options.
Signed : Specifies that the authentication token must be a signed, supporting token. A signed, supporting token is signed by the primary signature token and is part of primary signature.
Endorsing : Specifies that the authentication token must be endorsed. With an endorsing supporting token, the key represented by the token is used to endorse/sign the primary message signature.
Encrypted: Specifies that the authentication token must be an encrypted supporting token.
One can select any (or none) combination of the three options above. If both Signed and Endorsing are selected, the authentication token must be a signed, endorsing, supporting token. In this situation, the token is signed by the primary signature. The key represented by the token is used to endorse/sign the primary message signature. If Encrypted is selected as well, the supporting token is also encrypted in the request message.
For the Input Message and/or Output Message, click the
Message Parts button to specify which parts of the message need to
be encrypted, signed, and/or required.
See the following section for more information on the options in the Message Parts dialog.
The Message Parts dialog appears. It should look like Web Service Attributes Editor Page: Message Parts.
Click in a checkbox to the right of the message part or
element that you would like to sign, encrypt or require.
Select Sign to specify the parts or elements of a message that require integrity protection (digital signature).
Select Encrypt to specify the parts or elements of a message that require confidentiality (encryption).
Select Require to specify the set of parts and/or elements that a message must contain.
Click Add Body to add a row for the message body.
This will only be necessary if the row has been removed.
Click Add Header to add a row for either a specific SOAP
header part or for all SOAP header parts.
This will only be necessary if the SOAP header row in question has been deleted. The header parts that are available to sign and/or encrypt before clicking the Add Header button include To (Addressing), From (Addressing), FaultTo (Addressing), ReplyTo (Addressing), MessageID (Addressing), RelatesTo (Addressing), and Action (Addressing). After clicking Add Header, and then clicking All Headers, you may also specify AckRequested (RM), SequenceAcknowledgement (RM), and Sequence (RM).
Click Add Attachments to add a row the SOAP attachments.
This is useful if the web service has MIME attachments which should be protected. All the attachments in the message are secured on selecting this option. This option is only available for the specification version of Security Policy, supported in Netbeans IDE from 6.5 version.
Attachments Protection is not supported in .NET 3.0 and 3.5. So it is best to avoid this feature for interop with .NET.
There are no XPath elements displayed by default. Click
Add XPath to add rows that enable you to specify signature and/or
encryption for an XPath expression or a URI which indicates the version
of XPath to use.
By default, the Required field is selected. This is an editable field. Double-click the XPath row to specify the XPath expression or URI. Only one XPath element is allowed.
There is a limitation when specifying XPath elements. To use XPath elements, switch off Optimize Security manually by adding the disableStreamingSecurity policy assertion. For information on how to do this, refer to http://blogs.sun.com/venu/ for more information on disableStreamingSecurity.
- To remove an element, select it in the Message Part section, and then click Remove to remove it from message security.
- Click OK to save these settings.
12.7.1. Supporting Token Options
You can use one of the following options for supporting tokens:
Username Token: A username token is used to identify the requestor by their username, and optionally using a password (or shared secret, or password equivalent) to authenticate that identity. When using a username token, the user must be configured on GlassFish. For information on configuring users on GlassFish, read Adding Users to GlassFish.
X.509 Certificate: An X.509 certificate specifies a binding between a public key and a set of attributes that includes (at least) a subject name, issuer name, serial number, and validity interval. An X.509 certificate may be used to validate a public key that may be used to authenticate a SOAP message or to identify the public key with a SOAP message that has been encrypted. When this option is selected, you must specify a truststore. For information on specifying a truststore, read To Configure the Truststore on a Service Manually.
Issued Token : An issued token is a token issued by a trusted Secure Token Service (STS). The service does not trust the client directly, but instead trusts tokens issued by a designated STS. In other words, the STS is taking on the role of a second service with which the client has to securely authenticate. The issued tokens contain a key, which is encrypted for the server and which is used for deriving new keys for signing and encrypting.
SAML Token : A SAML Token uses Security Assertion Markup Language (SAML) assertions as security tokens.