X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;f=doc%2Flibrary-configuration.markdown;h=e692a72a361e54ccd5e510166eaf295cfa75b5ec;hb=e621c06f4648c400be9236f6a436de2f126773ef;hp=8975275df839f3dc9a7deb66adba39b23fe1db45;hpb=b86a5a12355fa00a5c98380370b0007eb9c410aa;p=mkws-moved-to-github.git
diff --git a/doc/library-configuration.markdown b/doc/library-configuration.markdown
index 8975275..e692a72 100644
--- a/doc/library-configuration.markdown
+++ b/doc/library-configuration.markdown
@@ -1,5 +1,5 @@
-MKWS Target Selection
-=====================
+% MKWS Target Selection
+% Mike Taylor
MKWS accesses targets using the Pazpar2 metasearching engine. Although
@@ -14,8 +14,8 @@ MKWS application to that library, and how to choose which of the
available targets to use.
-1. Maintaining the library
---------------------------
+Maintaining the library
+-----------------------
The service proxy accesses sets of targets that are known as
"libraries". In general, each customer will have their own library,
@@ -26,8 +26,8 @@ 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/
+the "MKX Admin" installation at
+
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
@@ -53,8 +53,8 @@ the library. The authentication process, described below, works by
searching for a matching User Access record.
-2. Authenticating your MWKS application onto the library
---------------------------------------------------------
+Authenticating your MWKS application 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
@@ -66,11 +66,11 @@ unauthorised access.
Setting up such a library is a process of several stages.
-### Stage A: create the User Access account
+### Create the User Access account
Log in to MKAdmin administrate your library:
-* Go to http://mkc-admin.indexdata.com/console/
+* Go to
* Enter the adminstrative username/password
* Go to the User Access tab
* Create an end-user account
@@ -79,20 +79,20 @@ Log in to MKAdmin administrate your library:
referring URL, or hostname.
If your MWKS application runs at a well-known, permanent address --
-http://yourname.com/app.html, say -- you can set the User Access
+, say -- you can set the User Access
record so that this originating URL is recognised by setting it into
the "Referring URL" field.
If your application accesses the Service Proxy by a unique virtual
hostname -- yourname.sp-mkws.indexdata.com, say -- you can tie the use
of this hostname to your library by setting the User Access record's
-"Host Name" field to name of the host where the SP is accessed. NOTE
-THAT THIS IS NOT SECURE, AS OTHER APPLICATIONS CAN USE THIS VIRTUAL
-HOSTNAME TO GAIN ACCESS TO YOUR LIBRARY.
+"Host Name" field to name of the host where the SP is accessed. **Note
+that this is not secure, as other applications can use this virtual
+hostname to gain access to your library.**
-TODO Authentication by IP address does not yet work correctly -- see
-bug MKWS-234 ("Improve SP configuration/proxying for better
-authentication").
+> TODO Authentication by IP address does not yet work correctly -- see
+> bug MKWS-234 ("Improve SP configuration/proxying for better
+> authentication").
Alternatively, your application can authenticate by username and
password credentials. This is a useful approach in several situations,
@@ -105,7 +105,7 @@ You can create multiple User Access records: for example, one that
uses Referring URL, and another that uses a username/password pair to
be used when running an application from a different URL.
-### Stage B: tell the application to use the library
+### Tell the application to use the library
In the HTML of the application, tell MKWS to authenticate on to the
Service Proxy. When IP-based, referer-based or hostname-based
@@ -114,39 +114,39 @@ authentication is used, this is very simple:
+
-TODO This should be the default setting
+> TODO This should be the default setting
And ensure that access to the MWKS application is from the correct
Referrer URL or IP-range.
-### Stage C1 (optional): access by a different virtual hostname
+### (Optional): access by a different virtual hostname
When hostname-based authentication is in use, it's necessary to access
the Service Proxy as the correctly named virtual host. This can be
-done by setting the service_proxy_auth configuration item to a
+done by setting the `service_proxy_auth` configuration item to a
URL containing that hostname, such as
- //yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig
+/yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig>
-TODO It should be possible to change just the hostname without needing
-to repeat the rest of the URL (protocol, path, query)
+> TODO It should be possible to change just the hostname without
+> needing to repeat the rest of the URL (protocol, path, query)
-TODO When changing the SP authentication URL, the Pazpar2 URL should in
-general change along with it.
+> TODO When changing the SP authentication URL, the Pazpar2 URL should
+> in general change along with it.
-### Stage C2 (optional): embed credentials for access to the library
+### (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
- //sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish
+by setting the `service_proxy_auth` configuration item to a URL such as
+/sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish>
-TODO It should be possible to add the username and password to the
-configuration without needing to repeat the rest of the URL.
+> TODO It should be possible to add the username and password to the
+> configuration without needing to repeat the rest of the URL.
-### Stage D (optional): conceal credentials from HTML source
+### (Optional): conceal credentials from HTML source
Using a credential-based Service-Proxy authentication URL such as the
one above reveals the the credentials to public view -- to anyone who
@@ -162,43 +162,53 @@ to that local authentication URL. Here is one way to do it when
Apache2 is the application's web-server, which we will call
yourname.com:
- - Add a rewriting authentication alias to the configuration:
- RewriteEngine on
- 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://yourname.com/spauth/
- - Protect access to the local path http://yourname.com/spauth/
- (e.g. using a .htaccess file).
+- Add a rewriting authentication alias to the configuration:
+ RewriteEngine on
+ RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
-3. Choosing targets from the library
-------------------------------------
+- Set the MKWS configuration item `service_proxy_auth` to
+
+- Protect access to the local path
+ (e.g. using a .htaccess file).
+
+
+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:
+in the `mkws_config` structure:
-* targets -- contains a Pazpar2 targets string, typically of the form
+* `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
+ 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
+* `targetfilter` -- contains a CQL query which is used to find relevant
targets from the relvant library. For example,
- udb==Google_Images
- Or
- categories=news
+ `udb==Google_Images`
+ or
+ `categories=news`
-* target -- contains a single UDB, that of the sole target to be
- used. For example
- Google_Images
+* `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
+ `udb==NAME`
+
+For example, a `Records` widget can be limited to searching only in
+targets that have been categorised as news sources by providing an
+attribute as follows:
+
+
+
+- - -
+Copyright 2014 IndexData ApS.