X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;f=doc%2Flibrary-configuration.txt;h=040bf738cef46788b904f438ffbdbf10ff63954c;hb=851a7c7eb7aebfb6d0b2d756b4377d8e325efd3f;hp=7abcfc0e082d0821dd658eff3f487409097ab626;hpb=af16564732031d94784408fd7577ed4813bb192f;p=mkws-moved-to-github.git diff --git a/doc/library-configuration.txt b/doc/library-configuration.txt index 7abcfc0..040bf73 100644 --- a/doc/library-configuration.txt +++ b/doc/library-configuration.txt @@ -2,74 +2,158 @@ 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: +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 +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. -* 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' +Stage B: tell the application to use the library -* targetfilter -- contains a CQL query which is used to find relevant - targets from the relvant library. For example, - udb==Google_Images +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: -* target -- contains a single UDB, that of the sole target to be - used. For example - Google_Images + +And ensure that access to the MWKS application is from the correct +IP-range, referer or hostname. -2. Changing the library ------------------------ +Stage C (optional): embed credentials for access to 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. +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 -Setting up such a library is a two-stage process. +Stage D (optional): conceal credentials from HTML source -Stage A (on MKAdmin) +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. -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: +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=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). + 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. + +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 + +