5 MKWS accesses targets using the Pazpar2 metasearching engine, almost
6 always fronted by the Service Proxy to manage target selection. This
7 document assumes the SP is used, and so that a library of targets is
8 available, maintained using an instance of MKAdmin (often
9 http://mkc-admin.indexdata.com/console/)
12 1. Maintaining the library
13 --------------------------
18 2. Choosing targets from the library
19 ------------------------------------
21 MKWS applications can choose what subset of the library's targets to
22 use, by means of several alternative settings on individual widgets or
23 in the mkws_config structure:
25 * targets -- contains a Pazpar2 targets string, typically of the form
26 "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
29 At present, these IDs can take one of two forms, depending on the
30 configuration of the Service Proxy being used: they may be based on
31 ZURLs, so a typical value would be something like:
32 pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
33 Or they may be UDBs, so a typical value would be something like:
36 * targetfilter -- contains a CQL query which is used to find relevant
37 targets from the relvant library. For example,
42 * target -- contains a single UDB, that of the sole target to be
45 This is merely syntactic sugar for "targetfilter" with the query
49 3. Authenticating onto the library
50 ----------------------------------
52 Some MKWS applications will be content to use the default library with
53 its selection of targets. Most, though, will want to define their own
54 library providing a different range of available targets. An important
55 case is that of applications that authenticate onto subscription
56 resources by means of credentials stored in MKAdmin: precautions must
57 be taken so that such library accounts do not allow unauthorised
60 Setting up such a library is a two, three or four-stage process.
62 Stage A: create the library
64 Use MKAdmin to create the library:
65 - Make a new library on http://mkc-admin.indexdata.com/console/
66 - Select relevant targets
67 - Add authentication credentials to the targets as necessary
68 - Create an end-user account
69 - Depending on what authentication method it be used, set the
70 end-user account's username and password, or IP-address
71 range, or referring URL, or hostname.
73 Stage B: tell the application to use the library
75 In the HTML of the application, tell MKWS to authenticate on to the
76 Service Proxy. When IP-based, referer-based or hostname-based
77 authentication is used, this is very simple:
79 <script type="text/javascript">
80 var mkws_config = { service_proxy_auth:
81 "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login" };
84 And ensure that access to the MWKS application is from the correct
85 IP-range, referer or hostname.
87 Stage C (optional): embed credentials for access to the library
89 When credential-based authentication is in use (username and
90 password), it's necessary to pass these credentials into the Service
91 Proxy when establishing the session. This can most simply be done just
92 by setting the service_proxy_auth configuration item to a URL such as
93 http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH
95 Stage D (optional): conceal credentials from HTML source
97 Using a Service-Proxy authentication URL such as the one above reveals
98 the the credentials to public view -- to anyone who does View Source
99 on the MKWS application. This may be acceptable for some libraries,
100 but is intolerable for those which provide authenticated access to
101 subscription resources.
103 In these circumstances, a more elaborate approach is necessary. The
104 idea is to make a local URL that is used for authentication onto the
105 Service Proxy, hiding the credentials, and to use local mechanisms to
106 limit access to that local authentication URL. Here is one way to do
107 it when Apache2 is the application's web-server, which we will call
110 - Add a rewriting authentication alias to the configuration:
112 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
113 - Set thwe MKWS configuration item "service_proxy_auth" to:
114 http://example.com/spauth/
115 - Protect access to the local path http://example.com/spauth/
116 (e.g. using a .htaccess file).
118 Once such a library has been set up, and access to it established,
119 target selection within the set that it makes available can be done
120 using the mechanisms above.