FAQ

Most Popular

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).
Categories: Muse Proxy, Usage

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.

Categories: Muse Proxy, Usage

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.

Categories: Muse Proxy, Usage

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).

Categories: Muse Proxy, Usage

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’.

Categories: General, Muse Proxy

Load More

Latest

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.

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.

Categories: Muse Proxy, Usage

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).

Categories: Muse Proxy, Usage

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.

Categories: Muse Proxy, Usage

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.

Categories: Muse Proxy, Usage

Load More