17.5.2.SOAP Server WS-Security Endpoint

The WS-Security processing is performed by filtering incoming and outgoing messages of the Virtuoso SOAP server. These filters are activated when a special SOAP option is set on the current virtual directory that is the SOAP endpoint. The WS-Security filters are invoked on input to verify / decrypt the message. Upon success the message will be processed by the SOAP server, otherwise a SOAP:Fault will be returned to the SOAP requester. On outgoing messages, depending of SOAP options, messages produced by the SOAP server can be encoded and signed as well. The administrator configures the WS Security subsystem at the access point level. Different security schemes involving encryption and/or signature can be selected.

The keys and certificates need to be defined in order to get a working secure service. The key/certificate(s) for the SOAP endpoint that is WS-Security enabled are referenced in a special PL hook and/or signature template. If none of these (signature or key instance hook) are defined the response will not be encrypted or signed.

Here are the steps involved in processing a message to a secure end point.

  1. SOAP server receives a message on a secure endpoint

  2. The message is determined to be for this endpoint, otherwise will be sent to the next SOAP router if routing is enabled.

  3. The message (as is) is passed to the decoding routine. At this point keys that are referenced in SOAP message need to be in the user space of the SQL account on whose behalf SOAP accessible procedures of this end point run. If any key does not exist in the user space, the requested processing will fail.

    [Note] Note:

    Signatures can be verified in the following manners:

    never try signatures
    expect signatures, explicit
    try signature if exists

    This behavior depends on the "WSS-Validate-Signature" option set for the virtual directory.

  4. If step 3 completes without problem, security related headers are stripped from the decoded message.

  5. The result of point 4 is passed to the usual SOAP server for processing.

  6. Once a response is generated by the SOAP method (i.e. corresponding PL procedure, exposed as SOAP method) the result will be encoded and/or signed. This is the last step before the result is sent back to the requestor client. At this point the server behavior is controlled by a few options defined in the virtual directory. See below: "WSS-KEY", "WSS-Template", and "WSS-Type" options.