Applies To:Show Versions
- 16.0.0, 15.1.0, 15.0.0
Implementing Web Services Security
Overview: Implementing web services security
- Encrypt and decrypt parts of SOAP messages
- Digitally sign parts of SOAP messages
- Verify parts of SOAP messages using digital signatures
About client and server certificates
- 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
- 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.
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 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.
Writing XPath queries
- 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
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
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
- 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 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.