| My Support

Applies To:

Show Versions Show Versions
Manual Chapter: Implementing Web Services Security
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Implementing Web Services Security

Overview: Implementing web services security

Web services security adds another level of protection to XML-based web applications by embedding security-related data within SOAP messages. For web services that Application Security Manager™ protects, you can use web services security to do the following:

  • Encrypt and decrypt parts of SOAP messages
  • Digitally sign parts of SOAP messages
  • Verify parts of SOAP messages using digital signatures

If you want to use features such as encryption, you can add web services security to an existing security policy that has an associated XML profile. You can enforce web services security only for URLs.

Task Summary

About client and server certificates

Client and server certificates are XML digital signatures that ensure the integrity of the message data, and can authenticate the identity of the document signer. By importing client and server certificates, the system can perform encryption and decryption of SOAP messages.

The system uses client and server certificates differently:

Server Certificates
Decrypt SOAP messages from a web client to a web service, or sign SOAP messages from a web service back to a web client.
Client Certificates
Encrypt SOAP messages from a web service to a web client, or verify SOAP messages from a web client to a web service.

Adding client and server certificates

To use web services security for encryption, decryption, and digital signature signing and verification, you must upload client and server certificates onto the Application Security Manager™. The system uses these certificates to process Web Services Security markup in SOAP messages within requests and responses to and from web services.

You must import both client and server certificates to perform encryption and decryption on the Application Security Manager.

  1. On the Main tab, click Security > Options > Application Security > Advanced Configuration > Certificates Pool .
    The Certificates Pool screen opens.
  2. Add one server certificate, and a client certificate for each client that you want to access the XML application. For each certificate you want to add, perform these steps:
    Note: The server and client certificates must be PEM files in x509v3 format. Also, the server certificate should contain the server’s private key.
    1. Click Add.
      The Create New Certificate screen opens.
    2. For Name, type a name for the certificate
    3. For Type, select Client or Server, as appropriate.
    4. For the .PEM File setting, either select Upload File from the list, then browse to and upload a certificate, or select Paste text to paste a copy of the certificate in the field.
    5. To store the certificate even if it is expired or untrusted, enable the Save Expired/Untrusted Certificate setting
    6. Click Add.
    The system adds the certificate to the certificates pool.
You have added client or server certificates to the system’s database. You can configure a security policy to use these certificates in an associated XML profile. The certificates in the pool can be used for any web applications.

Enabling encryption, decryption, signing, and verification of SOAP messages

Before you can complete this task, you first must have created a security policy using the option Create a policy for XML and web services manually, created and associated an XML profile with the policy, and uploaded security certificates onto the system.
You can use the web services security features of Application Security Manager™ to off load encryption and decryption of SOAP messages from the application server. Web services security can also handle verification of digital signatures and digital signing of SOAP messages.
  1. On the Main tab, click Security > Application Security > Content Profiles > XML Profiles .
    The XML Profiles screen opens.
  2. Click the name of the XML profile for which you want to configure web services security, or create a new profile.
    The XML Profile Properties screen opens.
  3. For the Web Services Security setting, select Enabled.
  4. Click Web Services Security Configuration.
    The XML Profile Properties screen displays Web Services Security Configuration options.
  5. For Server Certificate, select one server certificate from the list, or click Create to add a new certificate to the configuration.
    A Request area appears after you specify the certificate.
    The system uses the server certificate to decrypt SOAP messages from a web client to a web service, or sign SOAP messages from a web service back to a web client.
  6. For Client Certificates, select names from the Available list and then move them into the Members list.
    The system uses the client certificates to encrypt SOAP messages from a web service to a web client, or to verify SOAP messages from a web client to a web service.
  7. In the Request area, for Action, select the action you want the system to perform in SOAP message requests.
    • Select Verify and Decrypt to decrypt and verify digitally signed SOAP messages. F5 recommends that you use this value.
    • Select Decrypt to decode encrypted SOAP messages.
    • Select Verify to validate digitally signed SOAP messages. This option is available only if you imported client certificates, but no server certificate.
  8. For Role/Actor, select a role to determine which security headers you want the system to process in SOAP message requests.
    Role Description
    Do not check role/actor Process all security headers regardless of the role. This is the default setting.
    Custom role/actor Process security headers that contain the role you type in the adjacent box.
    next Process security headers that contain the role next or http://www.w3.org/2003/05/soap-envelope/role/next.
    none Process security headers that contain the role none or http://www.w3.org/2003/05/soap-envelope/role/none.
    ultimateReceiver Process security headers that contain the role ultimateReceiver or http://www.w3.org/2003/05 /soap-envelope/role/ultimateReceiver.
  9. Select the Enforce And Verify Defined Elements check box to confirm that elements defined in the Namespaces and Elements area of the screen and contained in the request are signed and verified.
    This setting also enforces the options SOAP Body in Request Must Be Signed and Verified and Enforce Timestamp In Request.
  10. In the Response area, for Action, select the action you want the system to perform on the elements defined in the Namespaces and Elements area of the screen for SOAP message responses.
    • Select Encrypt to encrypt the elements.
    • Select Sign to digitally sign the elements.
    • Select Sign, Then Encrypt to first digitally sign and then encrypt the elements. F5 recommends that you use this value.
    • Select Encrypt, Then Sign to first encrypt, then digitally sign the elements.
    Note: For the action to occur, you must also select Apply Action To Defined Elements.
  11. To limit how long a security header is valid:
    1. Enable the Add Timestamp setting.
    2. Type the length of time (in seconds) the timestamp should be valid. The default is 300 seconds.
      If you want the timestamp to be valid for an unlimited amount of time, enter 0. The maximum value is 134217728 seconds.
  12. For Role/Actor, select a role to insert into the security header of SOAP messages.
    Role Description
    Do not assign role/actor If the document contains a security header without a role, the system inserts the cryptographic information into the security header. This is the default setting.
    Assign custom role/actor If the document contains a security header with a custom role, the system inserts the cryptographic information into the existing security header. In the field, type the custom role/actor attribute.
    next If the document contains a security header with the next role, the system inserts the cryptographic information into that security header.
    none If the document contains a security header with the none role, the system inserts the cryptographic information into that security header.
    ultimateReceiver If the document contains a security header with the ultimateReceiver role, the system inserts the cryptographic information into that security header.
  13. If the response action includes signing, for Signature Algorithm, select the type of signature algorithm used to sign parts of SOAP messages in responses that match the response elements that you configure in the Namespaces and Elements area of the screen.
    • Select RSA-SHA-1 (the default value) to use the RSA public cryptosystem for encryption and authentication.
    • Select HMAC-SHA-1 to use secret-key hashing.
    Tip: Be sure your clients support this type of encryption.
  14. If the response action includes encryption, for Encryption Algorithm and Key Transport Algorithm, select the types of encryption to use for the elements and keys.
  15. Select the Apply Action To Defined Elements check box to perform the action you selected.
  16. In the Namespaces and Elements area of the Web Services Security Configuration, configure these settings to specify how to process the XML document:
    1. For Namespace Mappings, add the namespace mappings (prefix and URLs) the system uses for XPath queries:
    2. Select the SOAP Body In Request Must Be Signed And Verified check box to verify that requests contain a SOAP body that is digitally signed and verified.
      If not, the system issues a Verification Error violation.
    3. Select the Enforce Timestamp In Request check box to verify that the SOAP request contains a valid timestamp.
      If the request has no timestamp, the Missing Timestamp violation occurs. If the timestamp is expired, the system issues the Expired Timestamp violation.
  17. Specify which parts of the XML document you want the system to process:
    • If you want the response action to apply to the whole SOAP message (/soapenv:Envelope/soapenv:Body), select the Apply Action to Entire Response Body Value check box.
    • To specify which parts of requests and responses you want the system to process, use the Elements setting to add XPath expressions to define the parts of the SOAP message to encrypt.
  18. If you are updating an existing profile, click Update. If you are creating a new profile, click Create.
The security policy that is associated with the XML profile now includes web services security for the XML application.

Writing XPath queries

You can write up to three XPath queries to define the content that you are looking for in XML documents. When writing XPath queries, you use a subset of the XPath syntax described in the XML Path Language (XPath) standard at http://www.w3.org/TR/xpath.

These are the rules for writing XPath queries for XML content-based routing.

  1. Express the queries in abbreviated form.
  2. Map all prefixes to namespaces.
  3. Use only ASCII characters in queries.
  4. Write queries to match elements and attributes.
  5. Use wildcards as needed for elements and namespaces; for example, //emp:employee/*.
  6. Do not use predicates in queries.

Syntax for XPath expressions

This table shows the syntax to use for XPath expressions.

Expression Description
Nodename Selects all child nodes of the named node.
@Attname Selects all attribute nodes of the named node.
/ Indicates XPath step.
// Selects nodes that match the selection no matter where they are in the document.

XPath query examples

This table shows examples of XPath queries.

Query Description
/a Selects the root element a.
//b Selects all b elements wherever they appear in the document.
/a/b:* Selects any element in a namespace bound to prefix b, which is a child of the root element a.
//a/b:c Selects elements in the namespace of element c, which is bound to prefix b, and is a child of element a.

Configuring blocking actions for web services security

You can select which web services security errors must occur for the system to learn, log, or block requests that trigger the errors. These errors are sub-violations of the parent violation, Web Services Security failure.
  1. On the Main tab, click Security > Application Security > Blocking .
    The Settings screen opens.
  2. In the Current edited policy list near the top of the screen, verify that the edited security policy is the one you want to work on.
  3. Adjust the Enforcement Mode setting if needed.
    • To block traffic that causes violations, select Blocking.
    • To not block traffic even if it causes violations (allowing you to make sure that legitimate traffic would not be blocked), select Transparent.
    You can only configure the Block flag if the enforcement mode is set to Blocking.
  4. Review the Web Services Security failure violation and adjust the Learn, Alarm, and Block flags as required.
  5. Click the Web Services Security failure violation link.
    The web services subviolations are displayed.
  6. Enable or disable the web services subviolations, as required.
  7. Click Save to save your settings.
  8. To put the security policy changes into effect immediately, click Apply Policy.
If a request causes one of the enabled errors to occur, web services security stops parsing the document. How the system reacts depends on how you configured the blocking settings for the Web Services Security failure violation:
  • If configured to Learn or Alarm when the violation occurs, the system does not encrypt or decrypt the SOAP message, and sends the original document to the web service.
  • If configured to Block when the violation occurs, the system blocks the traffic and prevents the document from reaching its intended destination.
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.

Additional Comments (optional)

About F5

Education

F5 Sites

Support Tasks

Connect with us

© Copyright 2018 by F5 Networks, Inc. | Policies | Privacy | Trademarks