New

diff --git a/doc/library-configuration.txt b/doc/library-configuration.txt
new file mode 100644 (file)
index 0000000..7abcfc0
--- /dev/null
+++ b/doc/library-configuration.txt
@@ -0,0 +1,75 @@
+MKWS Target Selection
+=====================
+
+
+1. Selecting targets within the library
+---------------------------------------
+
+MKWS applications can choose what subset of the available 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 are based on ZURLs, so a typical
+  value would be something like:
+       pz:id~josiah.brown.edu:210/innopac|connect.indexdata.com:9000/mit_opencourseware'
+
+* targetfilter -- contains a CQL query which is used to find relevant
+  targets from the relvant library. For example,
+       udb==Google_Images
+
+* target -- contains a single UDB, that of the sole target to be
+  used. For example
+       Google_Images
+
+
+2. Changing the library
+-----------------------
+
+Some MKWS applications will want to define their own library providing
+a different range of available targets. This is particularly important
+in the case of applications that authenticate onto subscription
+resources by means of credentials stored in MKAdmin, in that such
+library accounts need to prohibit unauthorised access.
+
+Setting up such a library is a two-stage process.
+
+Stage A (on MKAdmin)
+
+Create the library:
+       - Make a new library on http://mkc-admin.indexdata.com/console/
+       - Select relevant targets
+       - Add authentication credentials as necessary
+       - Create an end-user account
+       - Set its username and password
+
+Stage B (on the application's web-server):
+
+Authentication onto the library can be achieved by a single HTTP GET
+to the relevant Service Proxy, passing in the credentials and thereby
+initiating an HTTP session. This can most simply be done just by
+setting service_proxy_auth to a URL such as
+       http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=MIKE&password=SWORDFISH
+
+However, doing so 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. For such
+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:
+
+       - Add a rewriting authentication alias to the configuration:
+               RewriteEngine on
+               RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=U&password=PW [P]
+       - Extend the MKWS configuration to set service_proxy_auth:
+               http://application.com/spauth/
+       - Protect access to /apauth/ (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.
+