-MKWS Target Selection
-=====================
+% MKWS Target Selection
+% Mike Taylor
MKWS accesses targets using the Pazpar2 metasearching engine. Although
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,
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
+<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
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
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 <http://mkx-admin.indexdata.com/console/>
* Enter the adminstrative username/password
* Go to the User Access tab
* Create an end-user account
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
+<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.
+"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,
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
<script type="text/javascript">
var mkws_config = { service_proxy_auth:
"//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" };
- </script>
+ </script>
-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
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
+ <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:
+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:
+
+ <div class="mkwsRecords" targetfilter='categories=news'/>
+
+- - -
+Copyright 2014 IndexData ApS. <http://indexdata.com>
projects / mkws-moved-to-github.git / blobdiff