Muse Proxy FAQ

The correct ways to use a proxy URL are listed below: 1) By source ID: http(s)://YOUR_PROXY_DOMAIN:PORT/APPLICATION_ID?groupID=PLACE_HERE_THE_GROUP_ID&action=source&sourceID=PLACE_HERE_THE_SOURCE_ID 2) By proxy prefix: http(s)://YOUR_PROXY_DOMAIN:PORT/APPLICATION_ID?qurl=PLACE_HERE_THE_ENCODED_URL_TO_PROXIFY or http(s)://YOUR_PROXY_DOMAIN:PORT/APPLICATION_ID?url=PLACE_HERE_THE_URL_TO_PROXIFY Using a followup rewritten URL which contain session information: ex: https://0d102vm5x-y-https-search-proquest-com.your_proxy_domain/databases is not recommended.

You can use the following format:

http(s)://YOUR_PROXY_DOMAIN:PORT/APPLICATION_ID?url=PLACE_HERE_THE_URL_TO_PROXIFY

or

http(s)://YOUR_PROXY_DOMAIN:PORT/APPLICATION_ID?qurl=PLACE_HERE_THE_ENCODED_URL_TO_PROXIFY

where replace YOUR_PROXY_DOMAIN with the actual fully qualified domain name (FQDN) of your Muse Proxy system, PORT with the value of the port on which Muse Proxy runs, and APPLICATION_ID with the correct Muse Proxy application ID.

Example:

https://proxy.yourdomain.org/MuseProxyFoundation?url=https://www.jstor.org/stable/i20716440

or

https://proxy.yourdomain.org/MuseProxyFoundation?qurl=https%3A%2F%2Fwww.jstor.org%2Fstable%2Fi20716440

Important observation:

In order for these proxified links to work, a proper configuration dealing with the rewriting of that domain must be in place in Muse Proxy. Otherwise, if such a configuration does not exist, you will get a message from Muse Proxy like below:

The url parameter provided cannot identify a source. Your organization may not have authentication for that remote target, or a source has not yet been configured to access that remote target.

If you experience this, then further address with the administrator of your Muse Proxy system the need for adding such a configuration (in Muse Proxy terminology it is called a Muse Proxy Source Profile).

The Navigation Sessions are used only by the ‘Navigation Manager’ Web Context (the Muse Navigation Manager component) to store useful data regarding a specific link navigation using a certain target site authentication context (cookies, referrer, next proxy access details, encoding etc.) through Muse Navigation Manager. This type of session is managed using an ID (named MuseSessionID) stored in the path of the Muse Navigation Manager rewritten links. This ID has associated a Navigation Session object at server side that stores the information needed to serve the requests for that Navigation Session (cookies, referrer, authorization, proxy, encoding, etc.).

A Navigation Session is generated by Muse Proxy in the following cases:
– when a user navigates on a ‘Type 1’ rewritten link there is generated automatically a redirect to a ‘Type 2’ rewritten link. The ‘Type 2’ rewritten link generated has associated a new Navigation Session;
– when a user logs into a Muse Proxy application and navigates on a Muse Proxy source link there is generated automatically a redirect to a ‘Type 2’ rewritten link. The ‘Type 2’ rewritten link generated has associated a new Navigation Session.

Many Navigation Sessions can be created for a single client, each corresponding to the authentication context of each rewritten target site. All the Navigation Session objects created for a Muse Proxy client are stored inside the Client Session object associated with that client. There is no limit set for the number of Navigation Sessions associated with each client.

The Client Sessions are used by the Muse Proxy Web Contexts which perform authentication in order to store the client authentication status to that Web Context, as well as other user metadata.

When a request comes to Muse Proxy (as a web server) without a Client Session cookie, a Client Session ID will be generated for it and sent back for storage in the browser in the form of a HTTP cookie. The name of the cookie is ‘MuseClientSessionID’. The Client Session cookie is returned to the Client only for the requests which require an authentication context. If a Client has performed only requests for free or public resources (e.g. static files: *.css, *.js, images etc), no Client Session cookie will be returned in the response.

Muse Proxy Authentication Token authenticates a rewritten request with an authentication token generated by Muse Proxy.

The authentication tokens are generated in the following cases:

A) when a rewritten link is generated using the ‘Utilities >> Rewrite URL’ section from the Muse Proxy Administrator Console and the ‘Muse Proxy Authentication Token’ option is selected. The authentication token generated is included as the ‘MuseProxyAuthenticationToken’ CGI GET parameter in the ‘Type 1’ rewritten link generated;

When ‘Type 1’ rewritten link request is performed, the value of the MuseProxyAuthenticationToken CGI parameter will be extracted and will be stored in the Navigation Session. If the Authentication Token is valid (it is not null or it is not expired) the request will be authenticated.
Otherwise, the entry associated with the user is searched in ${MUSE_HOME}/proxy/hosts.xml file. If the IP of the request is among the list of the ALLOW rules then the JAAS user group used for ‘Type 1’ rewritten links (by default ‘navigationManager’) is checked to match the GROUP entry associated with the user from ${MUSE_HOME}/proxy/hosts.xml file. If the group is matched then the authentication succeeds and the authentication process is finished;
If not, an authentication page will be returned to the client in order for him/her to enter the authentication details for UserName / Password authentication.

B) when a user logs in a Muse Proxy Application and clicks on a Muse Proxy Source link. The authentication token generated is included inside the Navigation Session associated with the ‘Type 2’ rewritten link generated;

When ‘Type 1’ rewritten link request is performed, the Authentication Token value will be extracted directly from the Navigation Session.
For example, when an user navigates on a source link from a Muse Proxy Application, a Navigation Session will be created dynamically in Muse Proxy. In that Navigation Session there is stored an authentication token to be used for the authentication. Next it is returned to the Client a redirect to a ‘Type 2’ rewritten URL which contains the id of the newly created Navigation Session as value for the MuseSessionID parameter from the path part of the URL. When the Client performs a request to this URL the MuseProxyApplicationSources filter extracts all the needed data from the Navigation Session and prepares the request to be handled by Muse Navigation Manager. The request is next authenticated using the authentication token mechanism and after the Muse Navigation Manager filters are applied the response is returned to the user.

C) when a request to 'http://${PROXY_HOST}:${PROXY_PORT}/ProxyInformation' is performed and only if the ‘com.edulib.muse.proxy.filter.MuseProxyAuthenticationToken’ filter is enabled. The value of the authentication token generated is included in the response of the 'http://${PROXY_HOST}:${PROXY_PORT}/ProxyInformation' request in the ‘AUTHENTICATION_TOKEN’ field.

The lifetime of an authentication token depends the value specified in the Authentication Token configuration file, which has the following full path: ${MUSE_HOME}/proxy/webcontexts/NavigationManager/profiles/filters/MuseProxyAuthenticationToken.xml. The Authentication Token configuration file contains only the authentication token timeout value. This value is present in the "AUTHENTICATION_TOKEN_TIMEOUT" field and it represents the timeout value, in milliseconds, after which an authentication token will be dumped.

The overall steps would be:
1) Create the new application as copy of the MuseProxyFoundation template, the ID of the new application to be MuseProxyFoundationHMAC for example.
2) Edit the file

$MUSE_HOME\proxy\webcontexts\Applications\MuseProxyFoundationHMAC\

profiles\AuthenticationGroups.xml

and do the following:
– Locate the

/ICE-CONFIG/AUTHENTICATION_GROUPS/AUTHENTICATION_GROUP/AUTHENTICATIONS

node and remove its content, thus obtaining an empty node:
<AUTHENTICATIONS>
</AUTHENTICATIONS>

– Edit the value of the node

/ICE-CONFIG/AUTHENTICATION_GROUPS/AUTHENTICATION_GROUP/NAME
to be:
HMAC Authentication

– Add the following sequence under the node

/ICE-CONFIG/AUTHENTICATION_GROUPS/AUTHENTICATION_GROUP/AUTHENTICATIONS

<AUTHENTICATION>
<IDENTIFIER>9</IDENTIFIER>
<LEVEL>requisite</LEVEL>
<CLASS>com.edulib.muse.proxy.authentication.modules.ProxyLoginModuleHMAC
</CLASS>
<HANDLER>
<CLASS>com.edulib.muse.proxy.authentication.modules
.ProxyLoginModuleHMACDataHandlerXml</CLASS>
<PARAMETERS>
<CONFIGURATION_FILE>${WEB_CONTEXT_HOME}/profiles/login
/ProxyLoginModuleHMAC.xml</CONFIGURATION_FILE>
</PARAMETERS>
</HANDLER>
</AUTHENTICATION>

(make sure that after pasting the content the XML file is still valid)

3) Refresh the applications properties via the Muse Proxy Administrator Console -> Advanced left menu section -> Operations item -> Refresh Applications button.
Now the HMAC is set with HMAC authentication.

4) Establish and configure the parameters for the HMAC authentication. For this edit the file:
$MUSE_HOME\proxy\webcontexts\Applications\MuseProxyFoundationHMAC
\profiles\login\ProxyLoginModuleHMAC.xml
and make changes according to your requirements. E.g. you may want to change the secret value (default is quiet) and the parameters that you want to hash as part of the signature. By default only the userName (Application ID) and timestamp are used, however you can add the userAgent and/or referer and/or userAddress to be hashed.

We assume for the examples purposes that all defaults remain (e.g. the quiet secret and userName.timestamp as message to sign with HmacSHA1).

Assuming that you want to proxify an URL (ex. http://www.amazon.com/) for the MuseProxyFoundationHMAC Muse Proxy application, the generated HMAC URL will look like:

http://MUSE_PROXY_HOST:PORT/MuseProxyFoundationHMAC?userName=MuseProxyFoundationHMAC
&ts=1469524141&sig=ee5a160dbd37c4867e34e6147a3421d2289bec14
&qurl=http%3A%2F%2Fwww.amazon.com%2F

where MUSE_PROXY_HOST:PORT are the Muse Proxy server details.

Note that by default the validity of this URL is 30 seconds.

For more detailed information on enabling and configuring HMAC authentication refer to the Muse Proxy Advanced Configuration.pdf manual, 6.4.5.8 ProxyLoginModuleHMAC chapter.

5) Create your server side implementation that will generate dynamically the HMAC link(s).

Notes:

1) The generated HMAC URL will work only for 30 seconds (configurable in the value of the TS_EXPIRY field in
$MUSE_HOME\proxy\webcontexts\Applications\MuseProxyFoundationHMAC
\profiles\login\ProxyLoginModuleHMAC.xml)
2) The server generating the HMAC links and the Muse Proxy server must be time synchronized. This is a must, otherwise if the 2 machines are not synchronized with regard to the time, the HMAC links will not work due to the validity value of the signature.
3) If you create proxified links, the destination URL (e.g the value of the qurl parameter) must be URL encoded.

The instructions and code provided below are based on the following assumptions:
– MuseProxyFoundationHMAC is the Muse Proxy application configured with HMAC authentication;
– quiet is the value of the secret;
– userName and timestamp are the signature parameters;
– SHA256 is the algorithm;
– the separator between the signature parameters is . .

Add the following code into your PHP page:

<?php
require_once './MuseProxyHMAC.php';
$museProxyURL = "http://MUSE_PROXY_HOST:PORT";
$applicationID = "MuseProxyFoundationHMAC";
$secret = "quiet";
$algorithm = "sha256";
$separator = ".";
// $timestamp is the current unix timestamp
$timestamp = time();
// $userAgent represent the userAgent from the request
//$userAgent = filter_input(INPUT_SERVER, "HTTP_USER_AGENT");
// $referer represent the referer from the request
//$referer = filter_input(INPUT_SERVER, "REQUEST_SCHEME") . "://" . filter_input(INPUT_SERVER, "HTTP_HOST") . filter_input(INPUT_SERVER, "REQUEST_URI");
// $userAddress represents the remote adress
//$userAddress = gethostbyname(gethostbyaddr(filter_input(INPUT_SERVER, "REMOTE_ADDR")));
//The order from this array must be the same with order and parameters name from the hmac configuration file ${APPLICATION_HOME}/profiles/login/ProxyLoginModuleHMAC.xml.
//$used_params = array("userName" => "MuseProxyFoundation", "ts" => $timestamp, "userAgent" => $userAgent, "referer" => $referer, "userAddress" => $userAddress);
$used_params = array("userName" => $applicationID, "ts" => $timestamp);

$museProxy = new MuseProxyHMAC($museProxyURL, $applicationID, $secret, $algorithm, $separator, $used_params);
echo $museProxy->generatedHmacDigest . "<br/>";
echo "<a href='" . $museProxy->generatedURL . "' target='_blank'>TEST</a>";
?>



where replace MUSE_PROXY_HOST:PORT with your actual Muse Proxy host and port.

The aditional MuseProxyHMAC.php file can be downloaded from here.

The code will generate the HMAC link on the TEST label.

The commented lines are for the cases when you want to use in the signature the userAgent/referer/userAddress values.
Note that they must be specified in the Muse Proxy as well (in the $MUSE_HOME\proxy\webcontexts\Applications\MuseProxyFoundationHMAC
\profiles\login\ProxyLoginModuleHMAC.xml file).

The instructions and code provided below are based on the following assumptions:
– MuseProxyFoundationHMAC is the Muse Proxy application configured with HMAC authentication;
– quiet is the value of the secret;
– userName and timestamp are the signature parameters;
– SHA256 is the algorithm;
– the separator between the signature parameters is . .

Integrate the following code into your Java project:

package com.edulib.muse.proxy.samples;

import java.io.IOException;
import java.io.PrintWriter;
import java.util.LinkedHashMap;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
@WebServlet("/index")
public class Index extends HttpServlet {
private static final long serialVersionUID = 1L;
/**
* Default constructor.
*/
public Index() {
// TODO Auto-generated constructor stub
}
/**
* @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse response)
*/
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
response.setContentType("text/html");
String algorithm = "HmacSHA256";
String secret = "quiet";
String proxyURL = "http://MUSE_PROXY_HOST:PORT";
String applicationID = "MuseProxyFoundationHMAC";
String separator = ".";
// timestamp represent the current UNIX timestamp
String timestamp = "" + System.currentTimeMillis() / 1000L;
// referer is the referer from request
String referer = request.getRequestURL().toString();
// userAddres is IP adress for user from request
String userAddress = request.getRemoteAddr();
// userAgent is userAgent from request header
String userAgent = request.getHeader("user-agent");
LinkedHashMap parameters = new LinkedHashMap();
parameters.put("userName", "test");
parameters.put("ts", timestamp);
parameters.put("referer", referer);
parameters.put("userAddress", userAddress);
parameters.put("userAgent", userAgent);

MuseProxyHMAC museProxyHMAC = new MuseProxyHMAC(proxyURL, applicationID, secret, algorithm, separator, parameters);

PrintWriter out = response.getWriter();
out.print(""<a href=\"" + museProxyHMAC.generatedURL + "\" target=\"_blank\">" + museProxyHMAC.generatedURL + "</a>"");
}
}


where replace MUSE_PROXY_HOST:PORT with your actual Muse Proxy host and port.
The aditional file MuseProxyHMAC.java that needs to be integrated into your Java project can be downloaded from here.

The instructions and code provided below are based on the following assumptions:

• MuseProxyFoundationHMAC is the Muse Proxy application configured with HMAC authentication;
• quiet is the value of the secret;
• userName and timestamp are the signature parameters;
• SHA256 is the algorithm;
• the separator between the signature parameters is . .

Integrate the following code into your ASPX page:

<%@ Page Language="C#" %>
<%@ Import Namespace="System" %>
<%@ Import Namespace="System.Linq" %>
<%@ Import Namespace="System.Security.Cryptography" %>
<%@ Import Namespace="System.Text" %>
<%@ Import Namespace="System.IO" %>
<%@ Import Namespace="System.Collections.Generic" %>

<script runat=server>
public String getHmacURL(String museProxyURL, String applicationID, String generatedHmacDigest, String parametersToSend) {
return museProxyURL + "/" + applicationID + "?sig=" + generatedHmacDigest + parametersToSend;
}
public String getParametersToCreateURL(Dictionary usedParameters){
String parametersToSend = "";
foreach( KeyValuePair param in usedParameters )
{
String key = param.Key;
if (!key.Equals ("userAddress") && !key.Equals ("userAgent") && !key.Equals ("referer")) {
parametersToSend += "&" + key + "=" + param.Value;
}
}
return parametersToSend;
}
public String getValueForGenerateDigest(Dictionary usedParameters, String separator){
String value = "";
int length = usedParameters.Count;
for (int i = 0; i < length; i++) { if (i < length - 1) { value += usedParameters.Values.ElementAt(i) + separator; } else { value += usedParameters.Values.ElementAt(i); } } return value; } public String generateHmacDigest(String algorithm, String secret, String value){ byte[] key = System.Text.ASCIIEncoding.Default.GetBytes(secret); byte[] byteArray = Encoding.ASCII.GetBytes(value); MemoryStream stream = new MemoryStream(byteArray); String digest = null; if (algorithm.Equals ("sha1")) { HMACSHA1 hmacSHA1 = new HMACSHA1 (key); digest = hmacSHA1.ComputeHash (stream).Aggregate ("", (s, e) => s + String.Format ("{0:x2}", e), s => s);
} else if (algorithm.Equals ("md5")) {
HMACMD5 hmacMD5 = new HMACMD5 (key);
digest = hmacMD5.ComputeHash (stream).Aggregate ("", (s, e) => s + String.Format ("{0:x2}", e), s => s);
} else if (algorithm.Equals ("sha256")) {
HMACSHA256 hmacSHA256 = new HMACSHA256 (key);
digest = hmacSHA256.ComputeHash (stream).Aggregate ("", (s, e) => s + String.Format ("{0:x2}", e), s => s);
} else if (algorithm.Equals ("sha384")) {
HMACSHA384 hmacSHA384 = new HMACSHA384 (key);
digest = hmacSHA384.ComputeHash (stream).Aggregate ("", (s, e) => s + String.Format ("{0:x2}", e), s => s);
} else if(algorithm.Equals ("sha512")){
HMACSHA512 hmacSHA512 = new HMACSHA512 (key);
digest = hmacSHA512.ComputeHash (stream).Aggregate ("", (s, e) => s + String.Format ("{0:x2}", e), s => s);
}
return digest;
}
public Dictionary initUsedParameters(){
// timestamp represent the current UNIX timestamp
long ticks = DateTime.UtcNow.Ticks - DateTime.Parse("01/01/1970 00:00:00").Ticks;
ticks /= 10000000; //Convert windows ticks to seconds
String timestamp = ticks.ToString();
// referer is the referer from request
String referer = Request.Url.GetLeftPart(UriPartial.Authority);
// userAddres is IP adress for user from request
String userAddress = GetIP();
// userAgent is userAgent from request header
String userAgent = HttpContext.Current.Request.UserAgent;

Dictionary parameters = new Dictionary();
parameters.Add ("userName", "username");
parameters.Add ("ts", timestamp);
//parameters.Add("referer", referer);
//parameters.Add("userAddress", userAddress);
//parameters.Add("userAgent", userAgent);
return parameters;
}


String algorithm = "sha256";
String secret = "quiet";
String proxyURL = "http://MUSE_PROXY_HOST:PORT";
String applicationID = "MuseProxyFoundationHMAC";
String separator = ".";

public String getDigest(){
String value = getValueForGenerateDigest(initUsedParameters(), separator);
return generateHmacDigest(algorithm,secret,value);
}

public String getURL(){
return getHmacURL(proxyURL, applicationID, getDigest(), getParametersToCreateURL(initUsedParameters()));
}


public static String GetIP()
{
String ip = HttpContext.Current.Request.ServerVariables["HTTP_X_FORWARDED_FOR"];

if (string.IsNullOrEmpty(ip))
{
ip = HttpContext.Current.Request.ServerVariables["REMOTE_ADDR"];
}
return ip;
}





<%=getURL()%>




where replace MUSE_PROXY_HOST:PORT with your actual Muse Proxy host and port.

The aditional file MuseProxyHMAC.cs that needs to be integrated into your project can be dowloaded from here.
The commented lines are for the cases when you want to use in the signature the userAgent/referer/userAddress values.
Note that they must be specified in the Muse Proxy as well (in the $MUSE_HOME\proxy\webcontexts\Applications\MuseProxyFoundationHMAC
\profiles\login\ProxyLoginModuleHMAC.xml file).

There are several methods for adding new resources into the Muse Proxy Application for handling the rewriting of vendor platforms, the recommended method is by using the Muse Proxy Administrator Console. The rewriting definitions for a vendor platform are stored in XML files, which we call Muse Proxy Sources.
Mainly the steps for adding a new Muse Proxy Source are:

1. Identify the source profile in the existing repository from the EduLib website by accessing this link:
   https://www.edulib.com/products/muse-proxy/support/muse-proxy-sources-profiles/
   Make use of the search functionality to narrow the results. Any term entered in the search box is searched in the source’s identifier and in the following field values from the source profile: NAME and DESCRIPTION.
   Once identified, click on the name link and a popup window will open with the details of the source’s profile. Click the Download Profile link to download the XML file.
2. Access your Muse Proxy Administrator Console, the URL should be of the form:
   https://proxy.domain.com/admin
   Login with the administrator user and the password that you configured during the setup.
3. Navigate to the left menu Aplications item, Manage Applications link. Locate the Muse Proxy Application in use and click on the Sources button to access the list of installed sources.
4. In the Sources page, click on the Create source from an existing profile icon, next to the Quick Filter search box.
5. In the new page, upload the XML file downloaded at step #1. Upon succesfull upload, you are requested to specify the Source Identifier value, place here the file name without the .xml extension. Also you can change the default name and description values for the source. When done, click the Create button.
6. The next step is to add the new source profile into a sources group. For doing this, in the Sources page click the Edit Sources Groups icon, next to the Quick Filter search box. In the new page click on the Sources icon from the Actions column, corresponding to the group in which to add the new source. By default only one group exists.
7. In the new Sources Groups page, click on the plus (+) icon found next to the new source in the List of available sources column.
8. Test by accessing a proxified link for the newly added resource. E.g. https://proxy.domain.com/applicationID?url=vendor_URL, where replace the hostname, applicationID and vendor_URL with the appropriate values.

The short answer is Yes, Muse Proxy support TLS 1.2.

Muse Proxy runs on Java, hence it uses the Java Virtual Machine security settings, it does not rely on anything from the Operating System in this regard. Also it is not compiled with any specific SSL libraries versions like other software is.

Starting with Java 6 update 115, TLS 1.2 is available, and in Java 7 and 8 it is enabled by default.

Hence Muse Proxy supports TLS 1.2, and to be more precise, TLS 1.2 is supported since 2014 when we added support in the Muse Proxy configuration file to specify the SSL protocols that can be used both on the server end and on the client end (requests
against the sources).

A complete set of manuals on Muse Proxy is available in your installation in the following path - $MUSE_HOME/proxy/doc, where $MUSE_HOME is the location on disk where you installed it:

– Muse Proxy Install.pdf. This is the installation manual.
– Muse Proxy.pdf. This is a manual with general information on Muse Proxy, describing its features.
– Muse Proxy Advanced Configuration.pdf. Manual with technical information on advanced configuration of Muse Proxy.
– Muse Proxy Sources Profiling.pdf. This document describes how to profile a Muse Proxy Source.
– Muse Proxy Administrator Console.pdf. Manual describing the Muse Proxy Administrator Console features.
– Muse Proxy Monitoring and Management using JMX.pdf. Advanced monitoring tools and techniques for monitoring Muse Proxy.
– Muse Proxy Release Notes.pdf. Release notes of Muse Proxy.

Also some general information is further below.

Muse Proxy has a multi-tenant architecture, capable of hosting in the same installation multiple client implementations, each having their own set of resources available and authentication methods.

In Muse Proxy terminology we have Muse Proxy Applications, which are a logical and physical bundle of all items specific for a customer implementation:

– the end user interface (HTML/JS/CSS files). The end-user interface can be easily customized as they are implemented with the Apache FreeMarker templating engine. An end-user interface for a Muse Proxy Application is optional. Each Muse Proxy installation comes by default with two Muse Proxy Applications Templates which you can use as base for creating your customers’ Muse Proxy Applications.
– the resources available;
– the authentication method(s).

By default Muse Proxy comes with 2 template applications, both containing a list of sources configured for demo purposes only.
– Muse Proxy Foundation.
http://Muse_Proxy_Hostname:Port/MuseProxyFoundation

where replace Muse_Proxy_Hostname with the fully qualified domain name of your Muse Proxy installation and Port with the value of the port on which you installed Muse Proxy (default 9797).

– Anonymous
http://Muse_Proxy_Hostname:Port/Anonymous

We do not recommend using the template applications in production as they will be overwritten by future Muse Proxy upgrades. New Muse Proxy applications must be created for production by copying an existing template.

You can use MuseProxyFoundation for tests in which you can add new Muse Proxy Sources from the EduLib repository :
https://www.edulib.com/products/muse-proxy/support/muse-proxy-sources/
or you can create new sources profiles by following the profiling rules from the “Muse Proxy Sources Profiling.pdf” manual.
The Muse Proxy Sources are XML files which store all necessary information about a resource, from the URL to access, to rewriting rules for rewriting its content and administrative information such as name, description, etc.
For ProQuest we already have about 80 source profiles for the various databases.

There are several ways of connecting to Muse Proxy:
1) Via the Muse Proxy Application interface. The Muse Proxy Application is a web application which presents to the end-user the collection of subscribed resources under a nice interface with several features like:
– Alphabetical View;
– Grouped view by Subject and/or Type;
– The possibility to have a description for each resource;
– The possibility to have a logo for each resource;
– Pagination options;
– Sorting options.

2) Via “proxified” URLs placed in your website, or constructed dynamically by your discovery/federated search implementation, URLs of the form:

http://Muse_Proxy_Hostname:Port/ApplicationID?url=Publisher_URL

where Muse_Proxy_Hostname is the hostname of your Muse Proxy instance; Port is the port on which it runs (default 9797); ApplicationID is the ID of the Muse Proxy Application; Publisher_URL is the URL to the publisher platform.

For example:

http://proxy.domain.com/myApplication?url=http://search.proquest.com/

When accessing such URL, if not already authenticated, Muse Proxy will authenticate the end-user through the configured authentication method, and upon authentication will present the end-user the publisher website in a rewritten form.

The Muse Proxy Application UI is based on skins.
If you want to customize the look and feel for a Muse Proxy Application we recommend the following approach:
– copy the existing skin with a different name. The skins folder is located on disk in the following location:

%MUSE_HOME%\proxy\webcontexts\Applications\
APPLICATION_ID\www\static\skins

where replace the APPLICATION_ID with the actual ID of the Muse Proxy Application.
– make the desired changes in the new skin;
– configure the Muse Proxy Application to use the new skin. This is done by editing the file:

%MUSE_HOME%\proxy\webcontexts\Applications\
APPLICATION_ID\www\application.inc

and changing the value of the variable applicationSkinId with the name of the new skin;

In the Muse Proxy.pdf manual, chapter Customize Muse Proxy Application Interface you can find information for how to customize the Muse Proxy Application UI.

The version of muse proxy can be found via putting in the following URL in an address bar on a browser such as FireFox or Internet Explorer:

http://PROXY_HOST:PROXY_PORT/ProxyInformation

In the above URL, PROXY_HOST is the server that is hosting Muse Proxy. PROXY PORT is the port that is running proxy. The default port for Muse Proxy is 9797.

The response is a XML message which is rendered raw by the browser. To correctly see the proxy version, view the source of the page (this is done differently in each browser) and search for the value of the field.

Please note that a dialog box may pop-up for entering UN/PW unless the IP where the request is coming from is allowed under the default section of the hosts.xml file under $MUSE_HOME/proxy/hosts.xml .

The Flash and Java Applets resources are binary files which cannot be processed by any re-writing proxy, including Muse Proxy.

Flash and Java Applets may load in pages re-written by Muse Proxy as long as there are no absolute pathnames in URLs inside them or if there is an object parameter of the Flash or Java Applet, accepting its base URL. However, if the Flash or Java Applet contains links inside them, they will not be re-written.

In other words the Flash and Java Applets may display correctly in Muse Proxy re-written pages, but when an end-user clicks a link hidden inside the Flash or Java Applets it is possible it will go straight to the provider and may appear unauthorized.

In Muse, there are 2 types of proxy chaining:

a) “ProxyChaining” happens when the MNM chains with the proxy used for source authentication. In a Muse application where we have configured a MNM_HOST to re-write the record links and a PROXY_HOST to use for authentication we have the following scenarios:

1) If the MNM and PROXY fields have different values then at runtime when the end user navigates on a rewritten link the following happens:
– enduser makes HTTP request to MNM_HOST
– the MNM_HOST makes the HTTP request to PROXY_HOST, thus chaining.
– the PROXY_HOST makes the HTTP request to the native data source.

This scenario is described in the Muse Advanced Configuration.pdf document, chapter “Data Services IP Authentication” and applies in all ASP Muse environments where IP authentications are used. For example, this type of proxy chaining is used in all our hosted Muse instances.

2) If the MNM is the same as the PROXY_HOST then the proxy chaining does not occur anymore.

Note that the proxy chaining feature works only if the com.edulib.muse.proxy.filter.ProxyChain filter is enabled in the $MUSE_HOME/proxy/MuseProxy.xml configuration file.
Also note that the proxy chaining feature works with other proxies than Muse Proxy used for source authentication, e,g, when PROXY_HOST is other proxy than Muse Proxy .

b) Another type of proxy chaining is when the Muse Proxy is configured to use another proxy, meaning that it will forward all HTTP requests to the configured proxy. This happens when the following fields from the "$MUSE_HOME/proxy/MuseProxy.xml" file are configured:

</PROXY_PORT>



Type a) of proxy chaining is the most encountered in the Muse installations.

They are types of rewritten links handled by the ‘Navigation Manager’ web context.

A) Example of ‘Type 1’ rewritten URL:
http://navigationManagerHost:navigationManagerPort/com/site/?MuseProtocol=ProtocolValue&MuseHost=some.site.com
&targetSiteParameter1=targetSiteParameterValue1
...
&targetSiteParameterN=targetSiteParameterValueN
&MuseCookie=CookieValue&MuseReferer=RefererValue
&MuseAuthorization=AuthorizationValue
&MuseAuthorizationScheme=AuthorizationSchemeValue
&MuseProxyHost=ProxyHostValue&MuseProxyPort=ProxyPortValue
&MuseProxyPac=ProxyPacValue
&MuseProxyAuthorization=ProxyAuthorizationValue
&MuseProxyAuthorizationScheme=ProxyAuthorizationSchemeValue
&MuseCharset=CharsetValue&MuseUID=UIDValue
&MuseProxyAuthenticationToken=ProxyAuthenticationTokenValue
&MuseNavigationManagerMode=NavigationManagerModeValue&MusePath=PathValue


A rewritten link is of ‘Type 1’ format if it contains the Muse Navigation Manager authentication markers (MuseCookie, MuseReferer, MuseProxyHost etc. as CGI parameters) and if it does not contain the MuseSessionID marker in the path part of the URL.

The ‘Type 1’ URL can be manually created, automatically generated from a different application or can be generated using the “Utilities >> Rewrite URL” section from the Muse Proxy Administrator console. The latter is available only if the “Enable Type 1 Links” option is enabled in the Muse Proxy License Key File.

B) The ‘Type 2’ rewritten URLs are dynamical URLs associated with a navigation session managed by Muse Proxy. The ‘Type 2’ rewritten URLs are valid only for small periods of time (by default 30 minutes after they are last accessed), while the navigation session associated with them is still valid.

Example of ‘Type 2’ rewritten URL:
http://navigationManagerHost:navigationManagerPort/MuseSessionID=SessionIDValue
/MuseProtocol=ProtocolValue/MuseHost=some.site.com/MusePath
/targetSitePathPart1/.../targetSitePathPartN/?
&targetSiteParameter1=targetSiteParameterValue1
...
&targetSiteParameterN=targetSiteParameterValueN

A rewritten link is of ‘Type 2’ format if it contains the MuseSessionID marker in the path part of the URL.

The ‘Type 2’ rewritten links cannot be manually generated. They are generated by Muse Proxy in the following cases:
– when a user navigates on a ‘Type 1’ rewritten link there is generated automatically a redirect to a ‘Type 2’ rewritten link;
– when a user logs into a Muse Proxy application and navigates on a Muse Proxy source link there is generated automatically a redirect to a ‘Type 2’ rewritten link;
– all the rewritten links inside a rewritten page are rewritten links of ‘Type 2’.

For authenticating the end-users into a Muse Proxy Application the following authentication modules are available:
–ProxyLoginModuleUserPassword. Performs User Name/Password authentication.
–ProxyLoginModuleIP. Performs IP authentication based on client machine IP.
–ProxyLoginModuleLDAP. Performs authentication against a LDAP Server.
–ProxyLoginModuleFTP. Performs authentication against a FTP Server. The FTP authentication module supports NONE, SSL or TLS connection encryptions.
– ProxyLoginModuleIMAP. Performs authentication against a IMAP Server. The IMAP authentication module supports NONE, SSL or TLS connection encryptions.
–ProxyLoginModuleSQL. Performs authentication against an SQL Server through Java Database Connectivity (JDBC). The SQL authentication module supports NONE, SSL or TLS connection encryptions.
–ProxyLoginModuleReferer.Performs authentication against the client’s referer URL.

You can read more about the authentication in a Muse Proxy Application in the “Muse Proxy.pdf” manual, chapter “Authentication of a Muse Proxy Application”.

This may be due to the default Windows limitations for network connections, more exactly the max limit set on simultaneous network connections. Receiving the TCP/IP has reached the security limit imposed on the number of concurrent TCP connect attempts error in Windows Event Viewer for Event ID 4226 is a clear sign of reaching the limit set on simultaneous network connections.
To disable the TCP connections limit follow the steps:
1) Click Start, type regedit in the Start Search box, and then click regedit.exe in the Programs list. If you are prompted for an administrator password or for confirmation, type your password, or click Continue.
2) Locate and then double-click the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\EnableConnectionRateLimiting
3) In the Value data box, type 0, and then click OK.
4) Exit Registry Editor.
5) Restart the computer.

If the EnableConnectionRateLimiting registry entry does not exist it must be added.

The Microsoft Knowledge Base article KB969710 confirms that the half-open TCP connections limit is disabled in Windows Server 2008 with Service Pack 2 (SP2) and in Windows Vista with Service Pack 2 (SP2).

The PERSISTENT-URL (sometimes also called durable URLs or durable links) is a url to a detailed native record and it is specifically not rewritten by Muse Navigation Manager. The PERSISTENT-URL link was created as an URL for which the users will use their own authentication to access the native data. The PERSISTENT-URL was specifically designed to not be tied to a search session and to provide a persistent link outside of Muse applications. They are not intended to take the place of a normal URL link in Muse records.

It is normal to be prompted to enter access details after following the PERSISTENT-URL to get to the record page. If the end-user is IP-authenticated to an account containing the required database, then the record page will appear without entering additional credentials.

In conclusion:
– use the regular DATA/URL to access the native data directly without having to enter user/password details
– use the DATA/PERSISTENT-URL when you want to provide your users an URL for which they should use their individual access details and only after that they will be able to go to that native record.

This FAQ has been created for partners to check the Muse Proxy configuration ($MUSE_HOME/proxy/hosts.xml file) to make sure they are not open proxies, and therefore prone to illegal usage.

RULES TO MODIFY:
1.) In the hosts.xml under the default user, there should be no * rule:


default
*

The default user allows the ICE Servers to access Muse Proxy. If the * rule is entered, the wildcard character, or *, will allow any IP to access the proxy via the default user. This could cause abuse of the proxy from remote IPs.  It is recommended that the IPs, or IP ranges, that will access the proxy via ICE are put in.

2.) In the hosts.xml under the administrator user, there should be no * rule:


administrator
*

Like the default user above, if the * statement is put in under this , it could potentially allow remote users to abuse muse proxy via the administrator user. It is recommended to only allow the IP (or IP ranges)  of computers that you expect to use to administrate the proxy.

RULES TO KEEP IN PLACE:
1.) For Muse Proxies above the 2.2.2.0 version, there is the following rule for the default.mnm user:

default.mnm
*

This must be kept in place, so that end users will able to navigate to links rewritten via Muse Navigation Manager.

2.)Under the section for every user, there is a * rule:


20
21
22
23
25
*


This must be kept in place. The REMOTE_PORTS section specifies the outgoing access port rules of the Muse proxy, i.e. to what remote ports the Muse Proxy is allowed to connect to. By default, we block access to the following remote ports:
20,21: File Transfer Protocol (FTP)
22: Secure Shell (SSH)
23: Telnet
25: Simple Mail Transfer Protocol (SMTP)
and allow access to the rest of the ports. Meaning that the Muse Proxy can connect to data services on any other ports except the ones listed above.

The *  was set to cover all possible ports used by service providers such as 80, 8080, 443, 210,etc.

3.) It is also recommended that if an rule is entered for Muse Global support (secure.museglobal.com or secure.museglobal.ro) that these are not taken out. These are in so that Muse support can properly troubleshoot the proxy.?

We strongly recommend to access the Muse Proxy service securely over HTTPS. This is required because almost all content vendor platforms accessed through Muse Proxy rewriting are using the secure protocol, and the same level of security must be matched by Muse Proxy as well. Furthermore, the rewriting of some platforms may not work without https:// access.

For this purpose, a wildcard SSL certificate from a trusted Certificate Authority must be configured in Muse Proxy. By default Muse Proxy comes with a self-signed certificate, the default port for https:// access is 9443. For production systems we recommend using the standard port 443.

Because Muse Proxy is a Java application, the SSL related items, Private key and Certificate must be stored in a Java standard KeyStore file type. In the Java KeyStore format the Certificate and Private Key are grouped in a single Key Pair with a password, and the KeyStore itself is also having a password. For simplicity reasons there should be a single Key Pair in the KeyStore and the Key Pair must have the same password as the KeyStore.

Starting with Muse Proxy version 5.1 Build 02, it is possible to manage the keystores from the Muse Proxy Administrator Console, thus operations like certificate renewal or configuring the certificate for the first time can be done from the console.

In all cases, either it is a renewal or a first time configuration, the steps are mainly the same:

1. Create a new keystore;
2. Assign the newly created keystore;
3. Restart the Muse Proxy service.

Important: Both the certificate as obtained from the CA and private key must be in DER or PEM formats. The private key must be unencrypted.
The steps are detailed below.

1) Create a new keystore

• Access the Muse proxy Administrator Console at URL:
  https://{MuseProxyHost}:{MuseProxySSLPort}/admin/
  where {MuseProxyHost} is the proxy Host Name and {MuseProxySSLPort} is the value of the SSL_PORT field from ${MUSE_HOME}/proxy/MuseProxy.xml configuration file (default is 9443). If the value of {MuseProxySSLPort} is 443 (default value for HTTPS connections) then this can be omitted from the URL. If it is the first CA signed SSL certificate assignment, you will get a browser security warning about the selfsigned certificate like “Your connection isn’t private”, access the “Continue” link.
• Select from the left menu “Server KeyStores” option to expand, then “Available KeyStores“. Click on “Create” button;
• In the new page are available 3 methods for creating a new keystore, the first one is for creating with a selfsigned certificate, this method must be used only for test purposes, not in production. The other two methods are further described, use only one of them , which suits you best.
  • KeyStore by Key Pair Import. In the “KeyStore details” section provide the filename with which the keystore will be saved on disk and the password to be set for the keystore.
    In the “Certificate” section the certificate and unencrypted private key must be provided, either by pasting their content, PEM format, or by uploading them as files in PEM or DER formats. A sample picture is provided below.
    
    Click the “Import” button when all inputs are filled in with the proper content. Upon success you should get a notification popup like below:
    
  • KeyStore by Upload. This assumes the keystore file is already available, created externally by using the JDK command line tool – keytool or through a dedicated certificates handling software like CERTivity® KeyStores Manager.
    More details on how to generate the keystore file externally can be found in the Muse Proxy Advanced Configuration.pdf manual, chapter 2.3 SSL KeyStore File.
    When uploading it, the keystore password is requested, and the name with which to be saved on disk, if different.
    

2) Assign the newly created keystore

• Select from the left menu “Server KeyStores” option to expand, then “Assigned KeyStores“;
• In the assigned keystores page, the current keystore in use is displayed:
  
• Click the “Edit” icon from the “Action” row and in the editing dialog, select the new keystore from the “Available KeyStores” dropdown.
  
• Click the “Save” button.

3) Restart the Muse Proxy service from the server’s console, e.g. on a Windows based server from the Services Management Console, on a Linux server by issuing a stop command (/etc/init.d/museproxy stop) and a minute late the start command (/etc/init.d/museproxy start).

 

When done, you can verify the new certificate by accessing in a browser the Muse Proxy service on https://. The browser will issue warnings if the SSL connection is not secure. To view the certificate details, locate and click the padlock next to the URL, the next steps depend on the browser as they are different depending on the browser. You can refer here to an online article for the exact steps to view the SSL certificate details in every well known browser.

We encountered cases on some Windows distributions when the Muse Proxy Windows Service fails to start, usually an error like below can be found in the Windows Event Viewer:

“The LoadLibrary function failed for the following reason: The specified module could not be found.”

The fix consists in adding into the Path system environment variable the path to the Java bin folder. For example, if your Java installation folder is

C:\Program Files\Java\jdk1.8.0_73

then add the following string to the beginning of the value for the Path environment variable:

C:\Program Files\Java\jdk1.8.0_73\bin;

Note that the separator between the entries from the Path variable is the semicolon (;) .
Details for how to update the Path variable for some Windows distributions can be found here:

http://www.java.com/en/download/help/path.xml

After doing this, start the Muse Proxy Service from the Windows Services management console
or by typing in a command prompt window the following command:

net start “Muse Proxy Server”

Certain kinds of Antivirus software automatically change the extension when downloading a file with exe extension via HTTP (eg. muse-win32.exe is renamed to muse-win32.1.2D0D17.efw). You should just rename the file to muse-win32.exe and run the executable.

More details about the .efw extension are available here: http://www.fileinfo.net/extension/efw

One can specify an IP address for Muse Proxy to listen on for connections. By default, Muse Proxy listens on all IP addresses, on all interfaces.

This setting can be changed in the ${MUSE_HOME}/proxy/MuseProxy.xml file by specifying an IP address in the "" field.

For Muse Proxy service to correctly work on Windows 64-bit systems you must install Muse Proxy either using the muse-proxy-setup.jar file or the executable file (muse-proxy-win32.exe). In the latter case you must set JAVA_HOME environment variable to the location of the 64-bit Java.

If no JAVA_HOME is defined and there are both 32-bit JAVA and 64-bit JAVA when installing Muse Proxy using muse-proxy-win32.exe file, then 32-bit JAVA will be used and Muse Proxy Service will not work correctly.

If JAVA_HOME is set to the location of the 64-bit JAVA and there are both 32-bit JAVA and 64-bit JAVA, then the JAVA used will be 64-bit JAVA, thus the services will work correctly.

Follow these steps to install the new Muse Proxy version:
– stop the Muse Proxy
– delete the content of the ${MUSE_HOME}/proxy/cache directory. IMPORTANT: Do not delete the directory itself, only its content.
– copy and dearchive the attached file “proxy.zip” in ${MUSE_HOME} directory
– start the Muse Proxy