|These are the installation instructions for KeyMaster version 6.2.0 onwards. For older versions of KeyMaster, see here.|
You need to have the following already installed:
An Application Server
Java 7 or .NET framework 3.5
Single Sign-on (SSO) system with which to integrate KeyMaster
It will also be necessary to synchronise the server clocks if this is not done automatically by your system. Instructions on how to do this are below.
To ease log-file analysis across servers, time zones, and daylight savings transitions, we recommend that you set the system clocks of all hosts in a Caplin stack to UTC.
Synchronising the server clocks
Make sure that the clock on the server running the Liberator is synchronised with the clock on the server where KeyMaster Signature Generator is running. If the clocks on these two servers are set to different times, the Liberator may falsely decide that a user credentials token has expired and it is likely to reject all user credentials tokens for this reason.
If the clocks are not correctly synchronised you will see the following message in the Liberator log file:
NOTIFY: Signature expired for key_id [key id] - [timestamp] denying login
Follow the steps below:
1. Generate keys
KeyMaster comes with a default set of digital encryption keys for encrypting credential tokens. These digital keys are not supported for production use.
To generate a set of keys for production use, run the script below (OpenSSL required):
#!/bin/bash # Generate a new 2048-bit RSA private key in PKCS#1 format openssl genrsa -out privatekey_pkcs1.pem 2048 # Convert the PKCS#1 key file to PKCS#8 format openssl pkcs8 -topk8 -inform PEM -outform PEM -in privatekey_pkcs1.pem -out privatekey_pkcs8.pem -nocrypt # Export the public key in DER format openssl rsa -in privatekey_pkcs1.pem -pubout -outform DER -out keymaster_public.der
Private key in a format that KeyMaster .NET can read (PKCS#1)
Private key in a format that KeyMaster Java can read (PKCS#8)
Public key in a format that Liberator can read (DER)
To configure KeyMaster Java to use the new PKCS#8 private key, see KeyMaster Servlets.
To configure Liberator to use the new public key, see Installing Liberator.
2. Set up single sign-on
KeyMaster must be deployed behind a single sign-on system (SSO) in order to securely generate log-in tokens that contain credentials belonging to authorised users. The SSO system is responsible for authenticating a user and passing the username on to the KeyMaster.
If you do not already have an existing SSO system in place, you will need to set one up. Follow your Java web container documentation for detailed procedures on how to set up an SSO solution.
3. Deploy the Java servlet
The Java version of KeyMaster contains an example servlet call StandardKeyMasterServlet (included in the kit in source form and as a deployable war file), this can be used as is, or as the basis for you own customized servlet.
Follow the steps below:
First follow this guide to make server configurations for the Java servlet before deploying.
Now deploy your KeyMaster servlet in a WAR file on to your server.
Once you have deployed your servlet into the application server and installed your credentials, installed and configured the server, and configured KeyMaster to work with the server, the run-time module of KeyMaster will be able to generate user credentials tokens for the server to pass back to requesting clients (see next section). The servlet will return a token for StreamLink to log in to the Liberator.
Validate the deployment of the Java servlet
Once you have deployed and configured the Java servlet, we will want to validate that it has been deployed successfully.
Go to the URL of your KeyMaster servlet in a browser. If the servlet has been configured as outlined in KeyMaster servlets, the URL will be <server url>/<war name>/servlet/StandardKeyMaster.
Log in with the user that you added to the role configured in the security-constraint in the Server configuration guide.
Once you have logged in, you will see the KeyMaster token in your web browser.
Example (for user role 'admin'):
credentials=ok username=admin token=hf46Rt6wNOwAryZji9Eeu5ADkbSzLxoq93yUsf5w3da56atw0vB/gEQOpBi/O5xSgxI3Ixw7QA3kz6oVkmdpa2XbQCxCZa/HebBu1sSnEMm+dmJrceg6cvVVxqL2FCDZFceUfd2ThWunecU4VwbNXT2puDNsDX4dvFuyip2qwDY=~20140411112017~0~~~admin
4. Setup users
Details of how to set up user authentication and permissioning are here.
Now see the Hardening KeyMaster security guide for information on making KeyMaster production ready.