Add text of new section on maintaining libraries.

[mkws-moved-to-github.git] / doc / library-configuration.txt

diff --git a/doc/library-configuration.txt b/doc/library-configuration.txt
index 18c0cd4..040bf73 100644 (file)
--- a/doc/library-configuration.txt
+++ b/doc/library-configuration.txt
@@ -2,46 +2,58 @@ 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. Changing the library
------------------------
+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.
+
+
+1. 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 "MKC 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. Note that IT IS THEN CRUICIAL 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.
+
+
+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
 
 Some MKWS applications will be content to use the default library with
 its selection of targets. Most, though, will want to define their own

@@ -51,40 +63,54 @@ resources by means of credentials stored in MKAdmin: precautions must
 be taken so that such library accounts do not allow unauthorised
 access.
 
 be taken so that such library accounts do not allow unauthorised
 access.
 

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

 
 

-Stage A (on MKAdmin)
+Stage A: create the library

 
 

-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
        - 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

-       - Set its username and password
+       - 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 (on the application's web-server):
+Stage B: tell the application to use the library

 
 

-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 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
-which is usually done with JavaScript like:
+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:
 
        <script type="text/javascript">
          var mkws_config = { service_proxy_auth:

-         "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH" };
+         "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login" };

         </script>
 
         </script>
 

-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, which we will call
+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:
 example.com:
 
        - Add a rewriting authentication alias to the configuration:

@@ -92,9 +118,42 @@ example.com:
                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/
                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 http://example.com/spauth/ (e.g. using a .htaccess file).
+       - 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.
 
 
 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.
 

+
+3. 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
+
+