Authenticating Research Service Users

If you need to collect fees from the users of your research service, restrict access to the service or to server-based resources used by the service, or if you just want to track the use of your service more effectively, you can authenticate users of your service. This requires them to identify themselves when they query the service. You can use any of the authentication options available in Microsoft Internet Information Services (IIS) and the Microsoft .NET Framework (except ASP.NET Passport authentication).

Note  Note that applying IIS Directory Security has no effect on ASP.NET authentication. The two systems are independent and are applied in sequence. After selecting authentication options, you must authorize authenticated users (or the account used for anonymous access) to access any resources required by the research service, such as files or databases. ASP.NET impersonation (enabled in the web.config file) may facilitate certain authentication and authorization scenarios.

IIS provides the first level of authentication and supports four authentication methods, consisting of the default Anonymous (no authentication) option and three options that require users to identify themselves as Microsoft Windows user accounts: Basic, Digest, and Integrated Windows Authentication.

ASP.NET provides the second level of authentication, consisting of options selected through settings in the web.config file.

• Windows authentication (the default) receives the user identity recognized by IIS. ASP.NET Windows authentication, in conjunction with IIS Integrated Windows authentication, will often be the choice of research service providers within an enterprise where all users are members of the same domain or a group of trusted domains.
• Forms authentication requires the user to provide credentials and verifies those credentials against a source of the provider's choosing, such as a Microsoft SQL Server™ database. Forms authentication, in conjunction with IIS Anonymous authentication, will often be the choice of research service providers serving external users across the Internet.

Note  Currently, the Research task pane does not support ASP.NET Passport authentication.

When a user submits a query to a research service that requires authentication using ASP.NET Forms authentication, the provider should remember the user's original query on the server (in Session state, for example), then return a login form to the Research task pane, as in the following sample response packet fragment:

<ResponsePacket xmlns="urn:Microsoft.Search.Response">
    <Response domain="{5a1ff98f-2024-4c8e-ac9d-2d764c1f1379}">
        <Status>SUCCESS</Status> 
        <Range>
            <Results>
                <Form xmlns="urn:Microsoft.Search.Response.Form" 
                    revision="1">
                    <Edit id="UserID" width="20">
                        <Text>User Name:</Text> 
                    </Edit>
                    <Edit password="true" id="Passwd" width="20">
                        <Text>Password</Text> 
                    </Edit>
                    <Button id="SubmitButton" action="requery" 
                        submitUrl=
                            "https://www.service.com/search.asmx" >
                        <Text>Log On</Text> 
                    </Button>
                </Form>
...

After processing the user's login, the provider should return the results of the user's original query. As shown in the example, the submitUrl attribute can be used to submit the user's credentials to a URL that supports Secure Sockets Layer (SSL) encryption for additional security.

For more information about using forms in query responses, see Handling Queries.

Research service scenarios that involve the authentication of registered users may also involve fee-based services. The Research task pane uses a for-pay icon to identify content that requires payment.

Research service providers can use the forPay attribute with various elements in the Microsoft.Search.Response.Document and Microsoft.Search.Response.Content namespaces in a query response to display the for-pay icon automatically next to the text of a hyperlink. The following example uses the Hyperlink element from the Microsoft.Search.Response.Content namespace.

<Hyperlink url=”http://foo” forPay=”true”>
    <Text>Read this article now</Text>
</Hyperlink>

A typical scenario for the use of the forPay attribute and icon might consist of a NewQuery element that triggers a new query, resulting in a charge. The service provider may want to display the for-pay icon next to the hyperlink for submitting the new query as shown earlier. This SDK also includes the icon as a separate file (forPay.gif) to allow research service developers to display the icon in contexts where the forPay attribute is not available to display it automatically. Alternatively, the service provider can use another icon of its choosing.

For more information about the elements that support the forPay attribute, see Microsoft.Search.Response.Document Schema Documentation and Microsoft.Search.Response.Content Schema Documentation.