MicroStrategy ONE

Using an XQuery source to authenticate users for a MicroStrategy project

The authentication options described in Implementing security in an XQuery statement can be used directly in an XQuery report.

Additionally, by using database authentication, you can authenticate against an XQuery source when users log in to a project, and save any tokens returned by the authentication process. These tokens can then be used in XQuery reports for the duration of a given user's MicroStrategy session. This authentication technique has the added benefit of keeping your MicroStrategy project secure by authenticating upon login, while allowing the use of tokens to avoid the need to include authentication details in every XQuery report.

The steps below show you how to configure your environment to support authenticating all XQuery reports for a given project.

Prerequisites

An XQuery statement that returns various tokens from a web service, which can then be used in XQuery reports as authentication tokens, in place of authenticating with every request. A common scenario is to return two tokens, including a session URL (a URL for subsequent requests) and a session Token (which identifies the caller as an already authenticated user). You can return up to four distinct pieces of information from a web service.

To use an XQuery source to authenticate users for a MicroStrategy project

  1. In MicroStrategy Developer, log in to a project source, using a user account with administrative privileges.

  2. In the Folder List, expand the project source, expand Administration, expand Configuration Managers, and then select Database Instances.

  3. From the File menu, point to New, and then select Database Instance. The Database Instances Editor opens.

  4. On the General tab, in the Database instance name field, type a descriptive name for the database instance.

  5. From the Database connection type drop-down list, select XQuery.

  6. In the Database connection area, click New. The Database Connections dialog box opens.

  7. In the Database connection name field, type a descriptive name for the database connection.

  8. In the Default database login name area, click New. The Database Logins dialog box opens.

  9. In the Database login field, type a descriptive name for the database login.

  10. The login information that you provide depends on the web service that you plan to connect to:

    • If the web service that you plan to connect to requires a user name and password, you must type a valid user name and password in the Login ID and Password fields, respectively. For information on how you can include this security in your report so that you can access the web services data, see Implementing security in an XQuery statement.

    • If the web service that you plan to connect to does not require a user name and password, you can type any user name in the Login ID field, and leave the Password field blank.

  11. Click OK. You are returned to the Database Connections dialog box.

  12. In the Default database login name area, select the new database login that you created.

  13. On the Advanced tab, in the XQuery authentication parameters field, type the XQuery statement to return the required authentication credentials from the web service. A complete XQuery statement can be included in this field, but the return statement must have the following structure:

    <Table>
    <ColumnHeadersColumnHeader name="Token1" type="    Example1</Token1>
    <Token2>    Example2</Token2>
    <Token3>    Example3</Token3>
    <Token4>    Example4</Token4>
    </Row>
    }</Data>
    </Table>

    The syntax above returns four separate credentials, which can be supplied in the Example1, Example2, Example3, and Example4 locations respectively. If fewer than four credentials are required, you can delete the associated <ColumnHeader> tags and <TokenN> tags. For example, the following XQuery statement makes a call to a SOAP web service and returns a session ID and a URI to be used for subsequent connections to a web service:

    declare namespace mstr-soap = http://www.microstrategy.com/xquery/soap-functions;
    declare function mstr-soap:post($args) external;let $    ExampleURI'
    let $soap-version := element SOAPInfo {element SOAPVersion {'SOAP11'}, element SOAPAction{''}}let $    ExampleNamespace"> <username', $

  14. Once you have typed a valid XQuery statement, click OK. You are returned to the Database Instances Editor.

  15. In the Database connection area, select the new database connection that you created, and then click OK. The database instance is created.

  16. To make the database instance available for Freeform SQL reports, right-click a project and select Project Configuration. The Project Configuration Editor opens.

  17. Expand Database Instances, and select SQL Data Warehouses.

  18. From the list of available database instances, select the check box for the database instance that you created in the previous steps. If you are prompted to configure data mart optimization, click No.

  19. Within the Database Instances category, expand Authentication, and select Metadata.

  20. From the drop-down list, select the database instance you created earlier in this procedure.

  21. Click OK to save your changes and close the Project Configuration Editor.

  22. Since you must use database authentication, you must perform some additional configurations:

    • Modify the MicroStrategy user group Public/Guest so that it has the necessary privileges to view the projects that use database authentication.

    • Modify any required MicroStrategy user accounts to link them to the web service account. In the User Editor, in the Authentication: Metadata category, type the login ID in the Database Login field.

    • Create a new project source or modify an existing project source to use database authentication.

    • For additional details on supporting database authentication in MicroStrategy, see the System Administration Help.

  23. You must also ensure that each XQuery report references the tokens that store the authentication credentials. The tokens can be accessed by using system prompts in MicroStrategy XQuery reports. These system prompts are stored in the project folder Public Objects/Prompts/System prompts and are named Token 1, Token 2, Token 3, and Token 4. Each token corresponds to the respective column returned by the XQuery authentication parameters.

  24. Within an XQuery report, you can define variables in an XQuery statement to retrieve the authentication credentials stored in the tokens. For example, the sessionid and uri variables shown below retrieve the authentication credentials from the Token 1 and Token 2 system prompts.

    To insert a prompt in an XQuery statement, within the Freeform SQL Editor, from the Edit menu, select Insert Prompt. You can then select the relevant Token prompt from the list of system prompts. You must include these tokens in any XQuery report that requires this authentication to connect to a web service.

This completes the steps to configure authentication for all XQuery reports for a given project. For additional details on how to create XQuery reports to return data from a web service, see Creating a report to analyze web service data.