MKWS Target Selection
---------------------

MKWS accesses targets using the Pazpar2 metasearching engine. Although
Pazpar2 can be used directly, using a statically configured set of
targets, this usage is unusual. More often, Pazpar2 is fronted by the
Service Proxy (SP), which manages authentication, sessions, target
selection, etc.

This document assumes the SP is used, and explains how to go about
making a set of targets (a "library") available, how to connect your
MKWS application to that library, and how to choose which of the
available targets to use.


### Maintaining the library

The service proxy accesses sets of targets that are known as
"libraries". In general, each customer will have their own library,
though some standard libraries may be shared between many customers --
for example, a library containing all open-access academic journals.
A library can also contain other configuration information, including
the set of categories by which targets are classified for the library.

Libraries are maintained using MKAdmin (MasterKey
Admin). Specifically, those used by MKWS are generally maintained on
the "MKX Admin" installation at
<http://mkx-admin.indexdata.com/console/>

In general, Index Data will create a library for each customer, then
give the customer a username/password pair that they can use to enter
MKAdmin and administrate that library.

Once logged in, customers can select which targets to include (from
the list of several thousand that MKAdmin knows about), and make
customer-specific modifications -- e.g. overriding the titles of the
targets.

Most importantly, customers' administrators can add authentication
credentials that the Service Proxy will used on their behalf when
accessing subscription resources -- username/password pairs or proxies
to use for IP-based authentication. Note that **it is then crucial to
secure the library from use by unauthorised clients**, otherwise the
customer's paid subscriptions will be exploited.

Access to libraries is managed by creating one or more "User Access"
records in MKAdmin, under the tab of that name. Each of these records
provides a combination of credentials and other data that allow an
incoming MKWS client to be identified as having legitimate access to
the library. The authentication process, described below, works by
searching for a matching User Access record.


### Authenticating your MWKS application 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 backe-end site 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 process of several stages.

#### Create the User Access account

Log in to MKAdmin administrate your library:

* Go to <http://mkx-admin.indexdata.com/console/>
* Enter the adminstrative username/password
* Go to the User Access tab
* Create an end-user account
* Depending on what authentication method it be used, set the
  User Access account's username and password, or IP-address range, or
  referring URL, or hostname.

If your MWKS application runs at a well-known, permanent address --
<http://yourname.com/app.html>, say -- you can set the User Access
record so that this originating URL is recognised by setting it into
the "Referring URL" field.

If your application accesses the Service Proxy by a unique virtual
hostname -- yourname.sp-mkws.indexdata.com, say -- you can tie the use
of this hostname to your library by setting the User Access record's
"Host Name" field to name of the host where the SP is accessed. **Note
that this is not secure, as other applications can use this virtual
hostname to gain access to your library.**

> TODO Authentication by IP address does not yet work correctly -- see
> bug MKWS-234 ("Improve SP configuration/proxying for better
> authentication").

Alternatively, your application can authenticate by username and
password credentials. This is a useful approach in several situations,
including when you need to specify the use of a different library from
usual one. To arrange for this, set the username and password as a
single string separated by a slash -- e.g. "mike/swordfish" -- into
the User Access record's Authentication field.

You can create multiple User Access records: for example, one that
uses Referring URL, and another that uses a username/password pair to
be used when running an application from a different URL.

#### 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:
	  "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" };
	</script>

> TODO This should be the default setting

And ensure that access to the MWKS application is from the correct
Referrer URL or IP-range.

#### (Optional): access by a different virtual hostname

When hostname-based authentication is in use, it's necessary to access
the Service Proxy as the correctly named virtual host. This can be
done by setting the `service_proxy_auth` configuration item to a
URL containing that hostname, such as
<//yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig>

> TODO It should be possible to change just the hostname without
> needing to repeat the rest of the URL (protocol, path, query)

> TODO When changing the SP authentication URL, the Pazpar2 URL should
> in general change along with it.

#### (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
<//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish>

> TODO It should be possible to add the username and password to the
> configuration without needing to repeat the rest of the URL.

#### (Optional): conceal credentials from HTML source

Using a credential-based 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 URL local to the customer that is used for
authentication onto the Service Proxy, hiding the credentials in a
local rewrite rule. Then local mechanisms can be used 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
yourname.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 the MKWS configuration item `service_proxy_auth` to
  <http://yourname.com/spauth/>
- Protect access to the local path <http://yourname.com/spauth/>
  (e.g. using a .htaccess file).


### Choosing targets from 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`

For example, a `Records` widget can be limited to searching only in
targets that have been categorised as news sources by providing an
attribute as follows:

	<div class="mkwsRecords" targetfilter='categories=news'/>


- - -

Copyright 2014 IndexData ApS. <http://indexdata.com>