Manual Chapter : Implementing Web Services Security
Applies To:Show Versions
- 16.0.1, 16.0.0, 15.1.0, 15.0.1, 15.0.0
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.
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.
- On the Main tab, click.The Certificates Pool screen opens.
- 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.
The system adds the certificate to the certificates pool.
- ClickAdd.The Create New Certificate screen opens.
- ForName, type a name for the certificate.
- ForType, selectClientorServer, as appropriate.
- For the.PEM Filesetting, either selectUpload Filefrom the list, then browse to and upload a certificate, or selectPaste textto paste a copy of the certificate in the field.
- To store the certificate even if it is expired or untrusted, enable theSave Expired/Untrusted Certificatesetting.
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.
- On the Main tab, click.The XML Profiles screen opens.
- 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.
- For theWeb Services Securitysetting, selectEnabled.
- ClickWeb Services Security Configuration.The XML Profile Properties screen displays Web Services Security Configuration options.
- ForServer Certificate, select one server certificate from the list, or clickCreateto 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.
- ForClient Certificates, select names from theAvailablelist and then move them into theMemberslist.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.
- In the Request area, forAction, select the action you want the system to perform in SOAP message requests.
- SelectVerify and Decryptto decrypt and verify digitally signed SOAP messages. F5 recommends that you use this value.
- SelectDecryptto decode encrypted SOAP messages.
- SelectVerifyto validate digitally signed SOAP messages. This option is available only if you imported client certificates, but no server certificate.
- ForRole/Actor, select a role to determine which security headers you want the system to process in SOAP message requests.RoleDescriptionDo not check role/actorProcess all security headers regardless of the role. This is the default setting.Custom role/actorProcess security headers that contain the role you type in the adjacent box.nextProcess security headers that contain the rolenextorhttp://www.w3.org/2003/05/soap-envelope/role/next.noneProcess security headers that contain the rolenoneorhttp://www.w3.org/2003/05/soap-envelope/role/none.ultimateReceiverProcess security headers that contain the roleultimateReceiverorhttp://www.w3.org/2003/05 /soap-envelope/role/ultimateReceiver.
- Select theEnforce And Verify Defined Elementscheck 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 optionsSOAP Body in Request Must Be Signed and VerifiedandEnforce Timestamp In Request.
- In the Response area, forAction, 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.
For the action to occur, you must also selectApply Action To Defined Elements.
- SelectEncryptto encrypt the elements.
- SelectSignto digitally sign the elements.
- SelectSign, Then Encryptto first digitally sign and then encrypt the elements. F5 recommends that you use this value.
- SelectEncrypt, Then Signto first encrypt, then digitally sign the elements.
- To limit how long a security header is valid:
- Enable theAdd Timestampsetting.
- Type the length of time (in seconds) the timestamp should be valid. The default is300seconds.If you want the timestamp to be valid for an unlimited amount of time, enter0. The maximum value is134217728seconds.
- ForRole/Actor, select a role to insert into the security header of SOAP messages.RoleDescriptionDo not assign role/actorIf 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/actorIf 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.nextIf the document contains a security header with thenextrole, the system inserts the cryptographic information into that security header.noneIf the document contains a security header with thenonerole, the system inserts the cryptographic information into that security header.ultimateReceiverIf the document contains a security header with theultimateReceiverrole, the system inserts the cryptographic information into that security header.
- If the response action includes signing, forSignature 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.
Be sure your clients support this type of encryption.
- SelectRSA-SHA-1(the default value) to use the RSA public cryptosystem for encryption and authentication.
- SelectHMAC-SHA-1to use secret-key hashing.
- If the response action includes encryption, forEncryption AlgorithmandKey Transport Algorithm, select the types of encryption to use for the elements and keys.
- Select theApply Action To Defined Elementscheck box to perform the action you selected.
- In the Namespaces and Elements area of the Web Services Security Configuration, configure these settings to specify how to process the XML document:
- ForNamespace Mappings, add the namespace mappings (prefix and URLs) the system uses for XPath queries:
- Select theSOAP Body In Request Must Be Signed And Verifiedcheck box to verify that requests contain a SOAP body that is digitally signed and verified.If not, the system issues aVerification Errorviolation.
- Select theEnforce Timestamp In Requestcheck box to verify that the SOAP request contains a valid timestamp.If the request has no timestamp, theMissing Timestampviolation occurs. If the timestamp is expired, the system issues theExpired Timestampviolation.
- 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 theApply Action to Entire Response Body Valuecheck box.
- To specify which parts of requests and responses you want the system to process, use theElementssetting to add XPath expressions to define the parts of the SOAP message to encrypt.
- If you are updating an existing profile, clickUpdate. If you are creating a new profile, clickCreate.
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
These are the rules for writing XPath queries for XML content-based routing.
- Express the queries in abbreviated form.
- Map all prefixes to namespaces.
- Use only ASCII characters in queries.
- Write queries to match elements and attributes.
- Use wildcards as needed for elements and namespaces; for example,//emp:employee/*.
- Do not use predicates in queries.
Syntax for XPath expressions
This table shows the syntax to use for XPath expressions.
Selects all child nodes of the named node.
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.
Selects the root element
belements wherever they appear in the document.
Selects any element in a namespace bound to prefix
b, which is a child of the root element
Selects elements in the namespace of element
c, which is bound to prefix
b, and is a child of element
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.
- On the Main tab, click.The Learning and Blocking Settings screen opens.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- Adjust theEnforcement Modesetting if needed.
You can only configure the Block flag on violations if the enforcement mode is set toBlocking.
- To block traffic that causes violations, selectBlocking.
- To allow traffic even if it causes violations (allowing you to make sure that legitimate traffic would not be blocked), selectTransparent.
- From the list, selectAdvanced.
- Expand theContent Profilessetting.The content profile violations andWeb Services Security failuresubviolations are displayed.
- Review theWeb Services Security failuresetting and adjust theLearn,Alarm, andBlockflags as required.
- 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 theWeb Services Security failureviolation to occur.
- ClickSaveto save your settings.
- To put the security policy changes into effect immediately, clickApply 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 failureviolation:
- 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.