Implementing security in an XQuery statement

Web services can have various security requirements to access the data that the web service provides. MicroStrategy's support of data retrieval from web services using XQuery statements supports most of the web services security mechanisms available. A web service can have the following security requirements:

HTTP authentication provides authentication using one of several authentication modes. MicroStrategy supports the use of basic and digest HTTP authentication for REST functions, and only basic HTTP authentication for SOAP functions. The user name and password that you provide as part of a database login is automatically used by MicroStrategy to complete any HTTP authentication required by the web service. Creating a database login is part of the steps required to create a database instance to access a web service, which is described in Allowing connections to web services in a project. A default database login is associated with the web service that you are connecting to. You can also use connection mapping to determine the database login used for each MicroStrategy user. For information on configuring connection mappings, see the System Administration Help. If the web service uses HTTP authentication, you cannot use Web Services Security authentication, as described below.

The example provided in Using XQuery to retrieve data from a web service is an example of using REST functions with the parameters URI. In this example, the parameter URI provides the URL to access the web service as well as define the data to return. This supports both basic and digest HTTP authentication.

An additional example of using REST functions that can support both basic and digest HTTP authentication is shown below.

This type of REST function requires the following parameters:
URI is the Internet address required to access the web service.
Content-Type is the Internet media type to use for the web form accessed by the request for data.
Payload is the request for data from the web service. For the example above, this requests data on the state of Virginia.
Web Services Security (WS-Security) provides web services authentication, as defined in the WS-Security standard. MicroStrategy utilizes the mstr-soap:post() external function to make SOAP web services calls. This function uses Axis2/C to invoke web services and uses Rampart/C to support WS-Security authentication. Using these XML-based assertions, you can enforce authentication and ensure the confidentiality and integrity of the message. If the web service uses WS-Security authentication, HTTP authentication must be defined as anonymous for the web service.

With WS-Security you can support security features such as:
Authentication with Username tokens.
Authentication with X.509 certificates.
Inclusion of Timestamp tokens.
SOAP message encryption.
SOAP message signature.
Message replay detection.
- The MicroStrategy function required to utilize WS-Security has the following syntax and requirements:
  
  mstr-soap:
URI is the Internet address required to access the web service.
SoapInfo is the version and action information of the SOAP request required to access the web service. For example, the following is a definition of SoapInfo for a web service SOAP request:

let $soap-version := element SOAPInfo { element SOAPVersion{ 'SOAP11' }, element SOAPAction{ ' ' } }

The SoapInfo element shown above is defined as two elements:
SOAPVersion, which specifies the SOAP Version of the request. The two possible values for this element are 'SOAP11' or 'SOAP12'.
SOAPAction, which specifies the required action for the web service.
WSSPolicy is the location of the web service's security policy file, which conforms to the WS-Security and WS-Security policy assertion language along with Rampart/C extensions.

A policy file can be extracted from the Web Services Description Language (WSDL) supplied by a SOAP file. Most web services provide a way to view the WSDL in a web browser. The policy file can also be created based on the security requirements of a SOAP web service. Regardless of how you create the policy file, the file may require manual changes to fully configure the required Rampart/C behavior. This MicroStrategy documentation assumes you have a working knowledge of WS-Security, Axis2/C, and Rampart/C technologies. While a comprehensive explanation of these technologies is not provided, the following links are provided for further details and background information on these subjects:
The specification for WS-Security can be found at http://docs.oasis-open.org/.
The specification for WS-Security policy language can be found at http://specs.xmlsoap.org/
Information on how Rampart/C can be configured using WS-Security policy language can be found at http://ws.apache.org/rampart/c/docs/
SoapCustomHeader is the SOAP header required to process the information from the web service.
SoapPayload is the statement that determines what information is retrieved from the web service.
A web service can require additional authentication requirements to access the data. If a web service requires additional authentication through the use of a user name and password, you can provide a valid user name and password in one of the following ways:
Include the user name and password directly in the XQuery statement. While this provides access to the web service, providing a password directly into an XQuery statement can cause a security risk. Additionally, the same security would be used regardless of the user running the report.
Use a MicroStrategy database login to provide the user name and password. Creating a database login is part of the steps required to create a database instance to access a web service, which is described in Allowing connections to web services in a project. The benefits of this approach include:
Placeholders are used to supply the database login user name and password, which keeps the user name and password information secure. The required syntax to use the user name and password from a database login in an XQuery statement is #?DBLOGIN_UID?# for the user name and #?DBLOGIN_PWD?# for the password.
You can use different database logins for each MicroStrategy user. This allows the security access to reflect the permissions of the user running the report. A default database login is associated with the web service that you are connecting to. You can also use connection mapping to determine the database login used for each MicroStrategy user. For information on configuring connection mapping, see the System Administration Help.