MKWS Target Selection
=====================


MKWS accesses targets using the Pazpar2 metasearching engine, almost
always fronted by the Service Proxy to manage target selection. This
document assumes the SP is used, and so that a library of targets is
available, maintained using an instance of MKAdmin (often
http://mkc-admin.indexdata.com/console/)


1. Selecting targets within the library
---------------------------------------

MKWS applications can choose what subset of the library's targets to
use, by means of several alternative settings on individual widgets or
in the mkws_config structure:

* targets -- contains a Pazpar2 targets string, typically of the form
  "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
  target IDs.

  At present, these IDs can take one of two forms, depending on the
  configuration of the Service Proxy being used: they may be based on
  ZURLs, so a typical value would be something like:
	pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
  Or they may be UDBs, so a typical value would be something like:
	pz:id=brown|artstor

* targetfilter -- contains a CQL query which is used to find relevant
  targets from the relvant library. For example,
	udb==Google_Images
  Or
	categories=news

* target -- contains a single UDB, that of the sole target to be
  used. For example
	Google_Images
  This is merely syntactic sugar for "targetfilter" with the query
	udb==NAME


2. Authenticating onto the library
----------------------------------

Some MKWS applications will be content to use the default library with
its selection of targets. Most, though, will want to define their own
library providing a different range of available targets. An important
case is that of applications that authenticate onto subscription
resources by means of credentials stored in MKAdmin: precautions must
be taken so that such library accounts do not allow unauthorised
access.

Setting up such a library is a two, three or four-stage process.

Stage A: create the library

Use MKAdmin to create the library:
	- Make a new library on http://mkc-admin.indexdata.com/console/
	- Select relevant targets
	- Add authentication credentials to the targets as necessary
	- Create an end-user account
	- Depending on what authentication method it be used, set the
	  end-user account's username and password, or IP-address
	  range, or referring URL, or hostname.

Stage B: tell the application to use the library

In the HTML of the application, tell MKWS to authenticate on to the
Service Proxy. When IP-based, referer-based or hostname-based
authentication is used, this is very simple:

	<script type="text/javascript">
	  var mkws_config = { service_proxy_auth:
	  "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login" };
        </script>

And ensure that access to the MWKS application is from the correct
IP-range, referer or hostname.

Stage C (optional): embed credentials for access to the library

When credential-based authentication is in use (username and
password), it's necessary to pass these credentials into the Service
Proxy when establishing the session. This can most simply be done just
by setting the service_proxy_auth configuration item to a URL such as
	http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH

Stage D (optional): conceal credentials from HTML source

Using a Service-Proxy authentication URL such as the one above reveals
the the credentials to public view -- to anyone who does View Source
on the MKWS application. This may be acceptable for some libraries,
but is intolerable for those which provide authenticated access to
subscription resources.

In these circumstances, a more elaborate approach is necessary. The
idea is to make a local URL that is used for authentication onto the
Service Proxy, hiding the credentials, and to use local mechanisms to
limit access to that local authentication URL. Here is one way to do
it when Apache2 is the application's web-server, which we will call
example.com:

	- Add a rewriting authentication alias to the configuration:
		RewriteEngine on
		RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
	- Set thwe MKWS configuration item "service_proxy_auth" to:
		http://example.com/spauth/
	- Protect access to the local path http://example.com/spauth/
		(e.g. using a .htaccess file).

Once such a library has been set up, and access to it established,
target selection within the set that it makes available can be done
using the mechanisms above.