X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fmkws-manual.markdown;h=61b5c96c1778cdc637e6ddf5de18658058e966bb;hb=a091348aabc6efb4e000682a20c67e0042c1bd13;hp=2d9fe959b5abc4f8f01380a2c31a089b5820fd80;hpb=5940e38aaaf2fc274915ccafdac94243255127fd;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 2d9fe95..61b5c96 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -431,17 +431,29 @@ The relevant properties (`popup_width`, etc.) are documented
in the reference section.
-Authentication and target configuration
----------------------------------------
+MKWS target selection
+=====================
-MKWS configures itself to use an account on a service hosted by
-`sp-mkws.indexdata.com`. By default, it sends no authentication
-credentials, allowing the appropriate account to be selected on the
-basis of referring URL or IP address.
+Introduction
+------------
+
+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.
+
+By default MKWS configures itself to use an account on a service
+hosted by `sp-mkws.indexdata.com`. By default, it sends no
+authentication credentials, allowing the appropriate account to be
+selected on the basis of referring URL or IP address.
If no account has been set up to recognise the referring URL of the
application or the IP address of the client, then a default "MKWS
-demo" account is used. This account (which can also be explicitly
+Demo" account is used. This account (which can also be explicitly
chosen by using the username `mkws`, password `mkws`) provides access
to about a dozen free data sources.
@@ -449,23 +461,7 @@ In order to search in a customised set of targets, including
subscription resources, it's necessary to create an account with
Index Data's hosted Service Proxy, and protect that account with
authentication tokens (to prevent unauthorised use of subscription
-resources). For information on how to do this, see the next section.
-
-
-MKWS target selection
-=====================
-
-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.
-
+resources).
Maintaining the library
-----------------------
@@ -481,18 +477,17 @@ Libraries are maintained using MKAdmin (MasterKey
Admin). Specifically, those used by MKWS are generally maintained on
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
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.
+customer-specific modifications to the target profiles --
+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
+credentials that the Service Proxy will use on their behalf when
accessing subscription resources -- username/password pairs or proxies
to use for IP-based authentication. Note that **it is then crucial to
secure the library from use by unauthorised clients**, otherwise the
@@ -529,19 +524,14 @@ Log in to MKAdmin to add a User Access account for your library:
* Create an end-user account
* Depending on what authentication method it be used, set the
User Access account's username and password, or referring URL, or
- Service Proxy hostname, or IP-address range.
+ IP-address range.
If your MWKS application runs at a well-known, permanent address --
, 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.**
+the "Referring URL" field. Then the application will always use that
+library that this User Access record is associated with (unless it
+sends a username/password pair to override this default).
Or if your application's users are coming from a well-known range of
IP-address space, you can enter the range in the "IP Ranges"
@@ -555,15 +545,15 @@ Alternatively, your application can authenticate by username and
password credentials. This is a useful approach in several situations,
including when you need to specify the use of a different library from
usual one. To arrange for this, set the username and password as a
-single string separated by a slash -- e.g. "mike/swordfish" -- into
+single string separated by a slash -- e.g. `mike/swordfish` -- into
the User Access record's Authentication field.
You can set multiple fields into a single User Access record; or
create multiple User Access records. For example, a single User Access
-record can specify both a Referring URL a username/password pair that
-can be used when running an application from a different URL. But if
-multiple Referring URLs are needed, then each must be specified in its
-own User Access record.
+record can specify both a Referring URL and a username/password pair
+that can be used when running an application from a different URL. But
+if multiple Referring URLs are needed, then each must be specified in
+its own User Access record.
### Tell the application to use the library
@@ -581,21 +571,6 @@ this is very simple:
And ensure that access to the MWKS application is from the correct
Referrer URL or IP-range.
-### (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
-URL containing that hostname, such as
-`//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): see
-> **MKWS-252**.
-
-> TODO When changing the SP authentication URL, the Pazpar2 URL should
-> in general change along with it: see **MKWS-253**.
-
### (Optional): embed credentials for access to the library
When credential-based authentication is in use (username and