Most Popular

The .cpb file describes the search capabilities of a source. The .pmf is the pre-mapping file that allows administrators to map search/index attributes that apply before the Muse ISR stylesheet is used to format the search for the source (thus “Pre”-mapping). The .cpb file lists all the search indexes and Boolean operators which are supported by the Source (whatever the actual, native syntax of the attribute). It is also a place where other source capabilities could be added later for easy import into the Muse InfoBase. The search limiter sets are one example. The .pmf file provides a mapping from one attribute in ISR to one attribute in translator. The .pmf mapping is TO an attribute which is handled into the ISR translator. All of the attributes handled (supported) in the ISR translator have been automatically extracted and recorded into the appropriate section in .cpb file. By default, the PMF files map unsupported attributes to keyword.

MuseGlobal provides three methods for search and retrieval of EBSCOhost content.

  • Z39.50
  • HTTP
  • EBSCO Integration Toolkit (EIT)

Where applicable, the preferred method of access is via EIT. This is a SOAP-based Web Service approach which provides the optimal combination of performance and completeness. You can find the EIT Source Packages by searching in your Muse Console’s “Add Sources” section in the “IDs Containing” field for the term EIT. EIT SPs have Source IDs which start with the string EBSCOEIT.


The HTTP Source Packages for EBSCO search on the URL
http://search.ebscohost.com/. The EIT Source Packages use
http://eit.ebscohost.com/Services/SearchService.asmx as the Home URL and Search URL.

Authentication for the EBSCOEIT Source Packages is two-fold.

1) Authentication for search and retrieval can done by user/pw (with the USER_NAME and USER_PASSWORD fields of the profile) or IP (with the CUSTOM_PARAMETERS field of the profile).

For search/retrieval authentication by IP, a value must be placed in the CUSTOM_PARAMETERS tag from the EBSCOEIT* source profile. Again, this is used to connect to and search a certain database. Using this IP authentication, you may be authenticated to a number of databases.

Example :

where : IP_ADDRESS=your IP which authenticates to EIT.

Please note that your EBSCO account must be specifically enabled in order to use of EIT. The user/pw used for connecting to http://search.ebscohost.com/ will not work for EIT. Also note that the IP_PROFILE will be either eitor eitws; — this string matches the 3rd section of your 3-part EIT authentication string (ex. s123456.main.eit or s123456.main.eitws). Please check with EBSCO if you are not sure which it is.

2) The aforementioned authentication by IP or user/pw gives us access to the EBSCOEIT API, but it does not provide successful link navigation on the record links obtained.

For this, the PROXY_HOST and PROXY_PORT in the profile must be configured. IMPORTANT: authentication to EBSCO for link navigation is only done by IP.

Example :

So, in conclusion, 2 IP authentication settings are needed: one (user/pw or IP) for accessing and searching the EBSCOEIT database desired and the other one (proxy IP) to successfully navigate on the record links obtained.

Questions about your EIT account status should be referred to Gregory Julien [GregoryJulien@ebscohost.com].

Categories: Muse Search, Sources

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;


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;

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 {

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



and do the following:
– Locate the


node and remove its content, thus obtaining an empty node:

– Edit the value of the node

to be:
HMAC Authentication

– Add the following sequence under the node



(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:
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:


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, ProxyLoginModuleHMAC chapter.

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


1) The generated HMAC URL will work only for 30 seconds (configurable in the value of the TS_EXPIRY field in

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

Load More


In production we recommend to use Azure Active Directory with SAML (ADFS). Theoretically there are no special requirements for integration with Azure Active Directory SAML , however this is a multi-step configuration which involves a lot of communication between the Muse Proxy technical team and the customer’s technical team.

The customer must create a new SSO application inside the MS Azure portal for Muse Proxy and provide the metadata URL, which looks like the one below:

where {tennantID} and {appid} are particular to the customer.

In more detailed steps:

– In the Azure Portal select the Azure Active Directory > Enterprise Application > All applications > New application. Add the custom application by accessing Create your own application link and add the name of the application (e.g. Muse Proxy), making sure the option Integrate any other application you don’t find in the gallery (Non-gallery) is selected. Then chose the application created and select Single sign-on from the Manage menu, and then click the “SAML” button to access the configuration guide.
– In the configuration pages, add at Identifier(Entity ID):
where proxy.yourdomain.com is the Muse Proxy domains and MPAppID is the Muse Proxy Application ID for which SSO is being configured.
At the Reply URL (the ACS from metadata) add:
It is not mandatory to add Sign on URL or Relay State. If Sign on URL is requested, that can be the URL for accessing the MP application:
Click the Save button to save the configuration.
– Then, in the SAML Certificates section make sure the Expiration date covers the desired period of time. If using multiple Muse Proxy applications, it is required to upload and use the same certificate for all applications because MS Azure uses the same entity ID with different certificates and this is not according to SAML standards.
– Then go to Configure Muse Proxy (the name the Enterprise application in Azure AD) and from there download the SAML XML Metadata. Note that the link for metadata only works if a certificate was configured in above (paragraph – SAML Signing Certificate Manage the certificate used by Azure AD to sign SAML tokens issued to Muse Proxy.)
Provide to the Muse Proxy technical team the URL with label App Federation Metadata Url from the SAML Certificates section and the downloaded file from label Federation Metadata XML

When done, setup the Muse Proxy application with the SAML authentication, by following the instructions from the Muse Proxy Administrator Console, Configuration left menu item, SAML Authentication.

Note: The above specific Azure instructions are based on our previous experience, the current Azure portal interface may differ.

A requirement for finalizing and testing the ADFS integration is for the customer to provide us a test account (username/password).

Many websites implement security mechanisms to protect against spam and abuse from automated computer programs (bots), the most used solutions are the CAPTCHAs.

There are several CAPTCHA implementations available, Google’s reCAPTCHA being very popular.
The reCAPTCHA functionality is based on embedding the Google security check that is incompatible with any rewriting proxy software, which is the man in the middle between the user’s browser and the accessed website, thus considered a potential security issue. Because the domain of the rewriting proxy is different than the publisher domain registered for the reCAPTCHA, the security verification is failing.

However, if the publisher can register the domain of Muse Proxy for reCAPTCHA (ex. proxy.domain.com), the domain security verification will work. From our experience, there are few publishers that support the integration of the proxy domains with reCAPTCHA based on the proxy IP address. Technically they generate a reCAPTCHA key for each proxy domain and use it when the access is made from that proxy IP address.

For some publishers we found that they can disable reCAPTCHA on their site for the Muse Proxy users.

The answer to the question if Muse Proxy supports reCAPTCHA depends on the capabilities of the publisher platform: Yes, if the publisher can offer one of the two solutions described above, and No if there is no coping from the publisher.

Besides Google’s reCAPTCHA, there are other CAPTCHA solutions that can be found on publisher websites. If the publisher can disable the CAPTCHA for the Muse Proxy users, this is the most viable option. If this is not possible, as a last resort, we can try crafting inside the Muse Proxy Source Profile, a set of filters to process the CAPTCHA’s JavaScript coding to pass the domain verification or to redirect to a re-written version of the publisher domain being verified. But this solution takes a lot of development time and may not have a successful outcome and may even be against the terms of service of the publisher/CAPTCHA’s solution.

Categories: General, Muse Proxy

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:
    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:
    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.
Categories: General, Muse 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:
    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.

In the $MUSE_HOME/tomcat/docs/Apache Tomcat embedded within Muse.pdf manual, chapter “ Secured Connections” you can find all details about securing the access to the Muse Embedded Tomcat server using SSL certificates.

Basically you need to generate a keystore from the private key and certificate, and enable it into the Tomcat’s configuration file: $MUSE_HOME/tomcat/conf/server.xml by uncommenting or adding if not already existing the connector:

Make sure the keystore name is correct and its password. Also inbound access on port 443 must be opened in the firewall.

Alternatively, for creating the keystore file, you can use EduLib’s CERTivity® KeyStores Manager tool. Get the free license, download and install it and follow the steps below for creating the keystore:

  1. File menu –> New KeyStore
    File name: keystore
    New KeyStore Type: jks
    Click on Save.
  2. KeyStore menu –> Import Key Pair
    – select PKCS #8
    – uncheck Private Key Encrypted
    – Private Key File: browse to your (.KEY) private key file
    – Certificate(s) File: browse to your (.CRT) certificates file
    – then OK
    – Alias should remain as suggested –> then OK
    – enter pass “changeit” without quotes (as it is default into the ${MUSE_HOME}/tomcat/conf/server.xml file) –> then OK
  3. File menu –> Save
  4. KeyStore menu –> Change Keystore Password
    – enter pass “changeit” without quotes (as it is configured into the ${MUSE_HOME}/tomcat/conf/server.xml file) –> then OK
  5. File –> Save
  6. Rename the resulted file from “keystore.jks” to “keystore” and place it into the ${MUSE_HOME}/tomcat/conf/ directory.

Load More