X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fmkws-manual.markdown;h=f05b06912d9c8027020d78e57af201a8581d8761;hb=ca89ae22902fc3f25119b59880e383d88ccaffab;hp=a315a22979efea4a1fbb910b09bea0923bf2b5ef;hpb=fda7da00419e8b5fdd051505c1073affa9690ae2;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index a315a22..f05b069 100644 --- a/doc/mkws-manual.markdown +++ b/doc/mkws-manual.markdown @@ -150,7 +150,8 @@ To see all of these working together, just put them all into the HTML
The full set of supported widgets is described in the -reference guide below. +reference guide +[below](#widgets). Widget team ----------- @@ -212,7 +213,7 @@ the English), initially sorts search results by title rather than relevance (though as always this can be changed in the UI) and makes the search box a bit wider than the default. -The full set of supported configuration items is described in the +The full set of supported configuration settings is described in the reference guide below. Per-widget configuration @@ -220,7 +221,7 @@ Per-widget configuration In addition to the global configuration provided by the `mkws_config` object, individual widgets' behaviour can be configured by providing -configuration items as attributed on their HTML elements. For example, +configuration settings as attributes on their HTML elements. For example, a `records` widget might be restricted to displaying no more than three records by setting the `numrecs` parameter as follows: @@ -237,11 +238,11 @@ attributes prefixed with `data-mkws-`, so: For first form is more convenient; the second is more correct. -Because some configuration items take structured values rather than +Because some configuration settings take structured values rather than simple strings, they cannot be directly provided by inline attributes. To allow for this, the special attribute `data-mkws-config`, if provided, is parsed as JSON and its key-value -pairs set as configuration items for the widget in question. For +pairs used as configuration settings for the widget in question. For example, the value of `lang_options` is an array of strings specifying which of the supported UI languages should be made available. The following invocation will limit this list to only English and Danish @@ -266,7 +267,7 @@ etc., customised layouts may wish to treat each of these components separately. In this case, `mkws-results` can be omitted, and the following lower-level widgets provided instead: -* `mkws-termlists` -- provides the facets +* `mkws-facets` -- provides the facets * `mkws-ranking` -- provides the options for how records are sorted and how many are included on each page of results. @@ -560,36 +561,42 @@ its own User Access record. 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 +by providing the `sp_auth_credentials` configuration setting as 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 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 +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. + +In these circumstances, a different approach is +necessary. Referer-based or IP-based authentication may be +appropriate. But if these are not possible, then a more elaborate +approach can be used to hide the credentials in a web-server +configuration that is not visible to users. + +The idea is to make a Service Proxy authentication URL local to the +customer, hiding the credentials in a rewrite rule in the local +web-server's configuration. 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: +yourname.com`: Step 1: add a rewriting authentication alias to the configuration: RewriteEngine on - RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P] + RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/\ + ?command=auth&action=check,login&username=U&password=PW [P] -Step 2: set the MKWS configuration item `service_proxy_auth` to -