F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP Application Security Manager: Implementations
  3. Implementing Web Services Security
Manual Chapter : Implementing Web Services Security

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 17.1.2, 17.1.1, 17.1.0, 17.0.0
Manual 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:
    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, 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.
    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.
    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

It only makes sense to select learning and blocking settings for web services security errors if you previously created a security policy to protect a web application that uses XML formatting or employs web services. The security policy must have an XML profile (with web services security enabled) associated with it.
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 subviolations of the parent violation,
Web Services Security failure
.
  1. On the Main tab, click
    Security
    Application Security
    Policy Building
    Learning and Blocking Settings
    .
    The Learning and Blocking Settings screen opens.
  2. In the
    Current edited security policy
     list near the top of the screen, verify that the security policy shown 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 allow 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 on violations if the enforcement mode is set to
    Blocking
    .
  4. From the list, select
    Advanced
    .
  5. Expand the
    Content Profiles
     setting.
    The content profile violations and
    Web Services Security failure
     subviolations are displayed.
  6. Review the
    Web Services Security failure
     setting and adjust the
    Learn
    ,
    Alarm
    , and
    Block
     flags as required.
  7. For Web Services Security failure subviolations, enable or disable the web services subviolations, as required for your application.
    For an explanation of any individual subviolation, click it.
    The selected subviolations are the ones that will cause the
    Web Services Security failure
     violation to occur.
  8. Click
    Save
     to save your settings.
  9. 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. The system sends a blocking response page. If the XML profile associated with the policy is configured to use an XML blocking response page, it uses the XML response. Otherwise, it uses the default response page.
  • If a web services security violation occurs on an entity in staging, for example, a URL in staging associated with an XML profile, the violation (set to alarm or block) is not enforced.
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information