+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).
+
+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 "MKX 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 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 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
+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.
+
+
+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
+library providing a different range of available targets. An important
+case is that of applications that authenticate onto subscription
+resources by means of back-end site 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 process of several stages.
+
+### Create the User Access account
+
+Log in to MKAdmin to add a User Access account for your library:
+
+* Go to <http://mkx-admin.indexdata.com/console/>
+* Enter the adminstrative username/password
+* Go to the User Access tab
+* 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
+ IP-address range.
+
+If your MWKS application runs at a well-known, permanent address --
+<http://yourname.com/app.html>, say -- you can set the User Access
+record so that this originating URL is recognised by setting it into
+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"
+field. The format of this field is as follows: it can contain any
+number of ranges, separated by commas; each range is either a single
+IP address or two addresses separated by a hyphen; each IP address is
+four small integers separated by periods. For example,
+`80.229.143.255-80.229.143.255, 5.57.0.0-5.57.255.255, 127.0.0.1`.
+
+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
+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 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.
+
+### (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 is done
+by setting the `sp_auth_credentials` configuration item to a string
+containing the username and password separated by a slash:
+
+ mkws_config = { sp_auth_credentials: "mike/swordfish" };
+
+### (Optional): conceal credentials from HTML source
+
+Using credential-based authentication settings such as those 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.