whitepaper.html
whitepaper.odt
whitepaper.pdf
+library-configuration.html
+library-configuration.odt
+library-configuration.pdf
# Copyright (c) 2013-2014 IndexData ApS. http://indexdata.com
DOCS = README.html README.odt README.pdf \
- whitepaper.html whitepaper.odt whitepaper.pdf
+ whitepaper.html whitepaper.odt whitepaper.pdf \
+ library-configuration.html library-configuration.odt library-configuration.pdf
-INSTALLABLE = README.html whitepaper.html mkws-doc.css
+INSTALLABLE = README.html whitepaper.html library-configuration.html mkws-doc.css
INSTALLED = $(INSTALLABLE:%=../tools/htdocs/%)
install: $(INSTALLED)
+++ /dev/null
-Set "Referring URL" to URL of the MKWS application, e.g.
-http://x.example.indexdata.com/mike.html
-
-Set "Host Name" to name of the host where the SP is accessed. e.g.
-sp-mkws.indexdata.com
-
-Set User Name and Password to values specified in auth URL.
-
-IP Address doesn't seem to work. Search is:
-http://mkc-admin.indexdata.com/torus2/identity.USERS/records/
- query=ipRanges encloses/net.ipAddress "127.0.0.1"
-And that always gets hit by one of the many records with ipRanges set
-to 0.0.0.0-255.255.255.255.
% The MasterKey Widget Set
% Mike Taylor; Wolfram Schneider
-% 23 July 2014
+% 28 July 2014
Introduction
------------
-This is the MasterKey Widget Set. It provides searching and other
-information-related functionality which can be inserted into existing
+This is the MasterKey Widget Set. It provides a way to insert
+searching and other information-related functionality into existing
web pages as small snippets of HTML.
As much of the searching functionality as possible is hosted on
<http://mkws.indexdata.com/>
-so that very simple websites such as
- <http://example.indexdata.com/>
+so that very simple applications such as
+ <http://example.indexdata.com/simple.html>
can have MasterKey searching with minimal effort.
The following files are hosted on `mkws.indexdata.com`:
</script>
~~~
-For much more detail, see
-[the MKWS whitepaper](whitepaper.html).
+For much more detail, see:
+
+* [Embedded metasearching with the MasterKey Widget Set](whitepaper.html)
+* [MKWS Target Selection](library-configuration.html)
- - -
--- /dev/null
+% MKWS Target Selection
+% Mike Taylor
+
+
+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.
+
+
+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 -- 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 -- 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 backe-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 administrate 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 IP-address range, or
+ 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
+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.**
+
+> 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,
+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 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.
+
+### 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
+authentication is used, this is very simple:
+
+ <script type="text/javascript">
+ var mkws_config = { service_proxy_auth:
+ "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" };
+ </script>
+
+> TODO This should be the default setting
+
+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)
+
+> TODO When changing the SP authentication URL, the Pazpar2 URL should
+> in general change along with it.
+
+### (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>
+
+> TODO It should be possible to add the username and password to the
+> configuration without needing to repeat the rest of the URL.
+
+### (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
+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.
+
+In these circumstances, a more elaborate approach is necessary. The
+idea is to make a URL local to the customer that is used for
+authentication onto the Service Proxy, hiding the credentials in a
+local rewrite rule. Then local mechanisms can be used 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
+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 the 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).
+
+
+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`
+
+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:
+
+ <div class="mkwsRecords" targetfilter='categories=news'/>
+
+
+- - -
+
+Copyright 2014 IndexData ApS. <http://indexdata.com>
+++ /dev/null
-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.
-
-
-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.
-
-Stage B: 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
-authentication is used, this is very simple:
-
- <script type="text/javascript">
- var mkws_config = { service_proxy_auth:
- "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login" };
- </script>
-
-And ensure that access to the MWKS application is from the correct
-IP-range, referer or hostname.
-
-Stage C (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
- http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH
-
-Stage D (optional): conceal credentials from HTML source
-
-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.
-
-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=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
-
-
color: black
}
-body > p, ul, ol, pre, table, h4 {
+body > p, ul, ol, pre, table, h4, blockquote {
margin-left: 10%;
}
+blockquote {
+ padding-left: 4em;
+ padding-right: 4em;
+}
+
p, ul {
max-width: 40em;
}
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). But in order to gain access to those resources, the
-authentication tokens have to be available to the widgets in some way,
-and simple embedding them in the JavaScript configuration is not
-acceptable because they are easy to read from there.
-
-The solution to this problem is in three steps.
-
-<b>First</b>
-the application's web-server creates a rewriting rule that takes an
-innocuous URL like
-http://example.indexdata.com/service-proxy-auth/
-and rewrites it as an access to Index Data's authentication service
-with authentication credentials embedded. This can be done using
-Apache2 directives such as
-
- RewriteEngine on
- RewriteRule /service-proxy-auth/
- http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=U&password=PW [P]
-
-Because the credentials appear only in the application's web-server
-configuration, they are not visible to malicious users.
-
-<b>Second</b>, the broader application that includes MKWS widgets must
-protect access to the authentication URL on its own web-server. This
-can be done using IP authentication, a local username/password scheme,
-Kerberos or any other means.
-
-<b>Third</b>, the MKWS application must be configured to use the
-application-hosted authentication URL instead of the default one. This
-is done by means of the `service_proxy_auth` configuration element,
-which should be set to the authentication URL.
-
-Once these three steps are taken, the MKWS application will
-authenticate by means of a special URL on the application's web
-server, which the application prevents unauthorised access to, and the
-underlying credentials are hidden.
+resources). For information on how to do this, see
+[MKWS Target Selection](library-configuration.html)
Reference Guide
-Development
-===========================================
-
-please run first in this directory:
-$ make jasmine-links
-
-
-jasmine.html - jasmine test with standard HTML page.
-
-jasmine-popup.html - jasmine test with MKWS popup. No HTML, only JavaScript.
- Returns better readable test results as jasmine.html,
- but it is less flexible.
-
-
Public demo pages
-----------------
auto.html
Jasmine test pages
------------------
-jasmine-popup.html - jasmine test with jquery popup, best for JS/HTML testing
jasmine-local-popup.html jasmine test with local SP and jquery popup, best for development
jasmine-pp2.html - running with local pazpar2 instead SP
-jasmine.html - standard jasmine test
-
+jasmine.html - jasmine test with standard HTML page.
+jasmine-popup.html - jasmine test with MKWS popup. No HTML, only JavaScript.
+ Returns better readable test results as jasmine.html,
+ but it is less flexible.
-<html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>MKWS demo client</title>
- <link rel="stylesheet" type="text/css" href="//mkws.indexdata.com/mkws.css" />
- <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
- </head>
- <body>
- <div class="mkwsSwitch"></div>
- <div class="mkwsLang"></div>
- <div class="mkwsProgress"></div>
- <div class="mkwsSearch"></div>
- <div class="mkwsResults"></div>
- <div class="mkwsTargets"></div>
- <div class="mkwsStat"></div>
- <div class="mkwsBuilder"></div>
- </body>
-</html>
+<h1>MKWS examples</h1>
+<p>
+ List to follow ...
+</p>
+<p>
+ In the mean time see the links from
+ <a href="http://mkws.indexdata.com/"
+ >mkws.indexdata.com</a>
+</p>
--- /dev/null
+<html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>MKWS demo client</title>
+ <link rel="stylesheet" type="text/css" href="//mkws.indexdata.com/mkws.css" />
+ <script type="text/javascript" src="//mkws.indexdata.com/mkws-complete.js"></script>
+ </head>
+ <body>
+ <div class="mkwsSwitch"></div>
+ <div class="mkwsLang"></div>
+ <div class="mkwsProgress"></div>
+ <div class="mkwsSearch"></div>
+ <div class="mkwsResults"></div>
+ <div class="mkwsTargets"></div>
+ <div class="mkwsStat"></div>
+ <div class="mkwsBuilder"></div>
+ </body>
+</html>
mkws.min.js
pz2.js
whitepaper.html
+library-configuration.html
<ul>
<li>
A very simple application at
- <a href="//example.indexdata.com/"
- >//example.indexdata.com/</a>.
+ <a href="//example.indexdata.com/simple.html"
+ >//example.indexdata.com/simple.html</a>.
</li>
<li>
<a href="//example.indexdata.com/minimal.html"
projects / mkws-moved-to-github.git / commitdiff