X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Flibrary-configuration.markdown;h=e692a72a361e54ccd5e510166eaf295cfa75b5ec;hb=4f6d99fb3a1d8efa942a89b93e3acfa922df5e07;hp=cb2db48253aa37fa0b7a106a5cbfd135cbb44566;hpb=3ddd0c7cb7c41465ccd3b4ec2eb9c079aa67a4eb;p=mkws-moved-to-github.git diff --git a/doc/library-configuration.markdown b/doc/library-configuration.markdown index cb2db48..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 @@ -41,8 +41,8 @@ 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 CRUICIAL TO -SECURE THE LIBRARY FROM USE BY UNAUTHORISED CLIENTS, otherwise the +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" @@ -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,32 +66,33 @@ 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/ - - 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. + +* Go to +* 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 +, 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.** -### 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, @@ -104,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 @@ -113,39 +114,39 @@ authentication is used, this is very simple: + -### 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 + -### 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) -### 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 + -### 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 @@ -161,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] +- Set the MKWS configuration item `service_proxy_auth` to + +- Protect access to the local path + (e.g. using a .htaccess file). -3. Choosing targets from the library ------------------------------------- + +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.