Muse Proxy FAQ
Muse Proxy
Load More
Load More
only4test
must not be used in production for generating new metadata for the setup of SAML authentication.
A new key pair with long-term (e.g. 10 years) validity must be generated and stored into the ${MUSE_HOME}/proxy/webcontexts/ssoRWP/WEB-INF/classes/security/samlKeystore.jks
keystore.
Oracle Java keytool or other Certificate Management GUI tools such as CERTivity will have to be involved in this process.
In this article we are describing the process of adding a new key pair in the SAML keystore using the CERTivity tool.
1) Access the tool page from the EduLib website:
https://www.edulib.com/tools/keystores-manager/
download it and obtain a license key by filling in the requested details in the Try form. Install the CERTivity tool by following the installation wizzard.
2) Get from the Muse Proxy server, the ${MUSE_HOME}/proxy/webcontexts/ssoRWP/WEB-INF/classes/security/samlKeystore.jks
file, onto the machine where the CERTivity tool is installed.
Open CERTivity, and from the File menu -> Open -> Open KeyStore menu, navigate on the location on disk where the samlKeystore.jks
was saved, and load it.
You will be prompted to enter the password, its value is stored in the ${MUSE_HOME}/proxy/webcontexts/ssoRWP/WEB-INF/securityContext-metadata.xml
file, in the bean
with ID keyManager
, the value of the entry
node with only4test
.
3) Once loaded, click the Generate Key Pair button from the toolbar to open the dialog:
4) In the Generate Key Pair dialog, fill in the requested fields, making sure the validity period is at least 10 years. Below is an example:
When saving the new key pair, you will be asked to enter a password.
5) Save the updated keystore by pressing the Save icon from the application’s toolbar.
6) Copy the updated samlKeystore.jks
file back on the Muse Proxy server, in the following path on disk:
${MUSE_HOME}/proxy/webcontexts/ssoRWP/WEB-INF/classes/security/
overwriting the existing one.
7) On the Muse Proxy server, edit the ${MUSE_HOME}/proxy/webcontexts/ssoRWP/WEB-INF/securityContext-metadata.xml
file, locate the bean
with ID keyManager
, and add a new entry
element in the map
node. This is how the new entry should look like:
(the passwords were removed intentionally for security purposes)
Make sure the file is valid XML after editing.
8) Access the Muse Proxy Administration Console, Configuration -> SAML Authentication and click the Restart SSO button, to restart the SAML servlet to load the updated keystore.
9) When creating new metadata, make sure the newly created key is selected for both Signing key and Encryption key:
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:
- Create a new keystore;
- Assign the newly created keystore;
- 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 theSSL_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 theMuse Proxy Advanced Configuration.pdf
manual, chapter2.3 SSL KeyStore File
.
When uploading it, the keystore password is requested, and the name with which to be saved on disk, if different.
- 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.
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.