From af16564732031d94784408fd7577ed4813bb192f Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Mon, 14 Apr 2014 15:47:20 +0100 Subject: [PATCH] New --- doc/library-configuration.txt | 75 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 doc/library-configuration.txt diff --git a/doc/library-configuration.txt b/doc/library-configuration.txt new file mode 100644 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. + -- 1.7.10.4