Applies To:Show Versions
- 13.1.1, 13.1.0
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:
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:
Note: 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.
The Create New Certificate screen opens.
- For Name, type a name for the certificate.
- For Type, select Client or Server, as appropriate.
- 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.
- To store the certificate even if it is expired or untrusted, enable the Save Expired/Untrusted Certificate setting.
- Click Add.
- Click Add.
Enabling encryption, decryption, signing, and verification 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 the Web Services Security setting, select Enabled.
Click Web Services Security Configuration.
The XML Profile Properties screen displays Web Services Security Configuration options.
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.
For Client Certificates, select names from the
Available list and then move them into the
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, 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.
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.
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.
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.
Note: For the action to occur, you must also select Apply Action To Defined Elements.
- 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.
To limit how long a security header is valid:
- Enable the Add Timestamp setting.
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.
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.
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.
Tip: Be sure your clients support this type of encryption.
- 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.
- 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.
- Select the Apply Action To Defined Elements check 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:
- For Namespace Mappings, add the namespace mappings (prefix and URLs) the system uses for XPath queries:
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.
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.
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.
- If you are updating an existing profile, click Update. If you are creating a new profile, click Create.
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.
- 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.
|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.
|/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
On the Main tab, click
.The Learning and Blocking Settings screen opens.
- 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.
Adjust the Enforcement Mode setting if needed.
You can only configure the Block flag on violations if the enforcement mode is set to Blocking.
- 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.
- From the list, select Advanced.
Expand the Content Profiles setting.
The content profile violations and Web Services Security failure subviolations are displayed.
- Review the Web Services Security failure setting and adjust the Learn, Alarm, and Block flags as required.
For Web Services Security failure subviolations, enable or disable the web
services subviolations, as required for your application.
Tip: 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.
- Click Save to save your settings.
- To put the security policy changes into effect immediately, click Apply Policy.
- 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.