Certificate Authentication
Overview
The Fusion Registry supports authentication via the use of an X509 certificate (in the PKCS12 format). In order to support Certificate Authentication the Fusion Registry must be configured to communicate via the HTTPS protocol.
Authentication
The web application container (e.g. Apache Tomcat) is responsible for Authenticating the Certificate - as such the Certificate must be in the container's trust store.
The container has receives a request, authenticates it, and passes the request onto the Fusion Registry as a pre-authenticated request. Fusion Registry then extracts the Certificate's CNAME in order to know who the user is.
Authorization
From Registry 11, the Canonical Name (CNAME) of the certificate will be used to match a group as defined by the Fusion Security Manager. To allow permissions for a Certificate, the Group ID (Certificate CName) must be given allow permissions using Fusion Security Manager.
Certificate Authentication Setup Procedure
Generating Self-Signed Certificates
Overview
The following gives an example of how to create self-signed certificates these certificates will be used for applications to authenticate with the tomcat server.
Whilst trusted authorities such as Verisign are typically used to generate Certificates for website to run under https, a self-signed Certificate can be generated locally using applications such as Java Keytool, which is freely available as part of the Java JDK distribution (under Java/bin).
Self-signed certificates will not be trusted by web browsers, as they have not been created by a trusted authority, however for internal use, to distribute to users of an application, they are perfectly adequate (if you trust yourself).
The certificates created in this example are not the same certificates that are used to enable Tomcat to run under https.
It is assumed that the Certificate to enable https will be generated by a trusted authority, and that Tomcat has already been configured to run under https.
This process makes use of Java Keytool this is a command line application for certificate creation and management.
Generate a certificate for the client of Fusion Metadata Registry
This process creates a self-signed certificate to be given to the user of the Fusion Registry. This certificate contains the user’s username in the Certificates Common Name (CN). This process consists of two steps as follows:
1. Generate a p12 file which contains the private key and certificate. This generation step prompts a number of questions on the command line. The first question is ‘what is your first name’ this value here should be the username of the user that the certificate will be issued to.
keytool -genkeypair -alias regClient -keyalg RSA -validity 365 -keystore regClient.p12 -storetype PKCS12
2. Export the certificate from the p12 file to a .cer file
keytool -exportcert -alias regClient –keystore regClient.p12 –storetype PKCS12 –file regClient.cer
Configuring Tomcat for Certificates
Tomcat can be configured to use certificate authentication. It is important to note that Tomcat can be configured to enforce all clients use a certificate, or it can be configured to allow certificates to be used, but not enforce that they are. The latter use-case enables clients to use the Registry anonymously or sign in using Basic Authentication, whist also supporting certificates. The former use case will reject any access from a user who does not have a certificate.
To support certificate authentication, modify the server.xml file located in Tomcat/conf. The Connector is used to set the keystore, truststore, and if the client must show a certificate (clientAuth=true) or if a certificate is optional (clientAuth=want).
To configure Tomcat, perform the following steps:
1. Create a trust store for the Registry, containing the Registry client certificate file:
keytool -importcert -alias regClient -storetype PKCS12 -keystore regtomcat.truststore -file regClient.cer
2. Place both the registry p12 file and the Registry truststore inside the tomcat/conf folder for Fusion Registry.
3. Modify the [tomcat]/conf/server.xml
Link Certificate to Organisations
Once a Certificate has been added to the tomcat truststore, it will be used to authenticate the request.
Tomcat acts as the authentication service, and therefore no other authentication is required (LDAP and Fusion Security play no role in authentication in this instance).
The Fusion Registry receives the pre-authenticated request, and needs to determine which Organisation(s) the certificate is linked to.
The link between the certificate an Organisation(s) is based on the certificate’s CName. The management of this connection is performed in the FMR's Certificate Manager, which can be accessed under Security.
The Certificate Manager is used to define a Certificate by its CName and connect this to an email address, and any number of Organisations.
Testing
To test Certificate Authentication:
- Launch the Fusion Registry web application.
- Open your Chose Web Browser and in the Settings area, navigate to ‘Manage Certificates if you are suing Chrome or View Certificates if you are using Firefox’.
- Load the registry client certificate into the web browser (regClient.p12 for example)
- Navigate to the Fusion Registry web page using https. The web browser may ask which certificate you wish to use: select 'regClient'. The Fusion Registry application should show the user as being logged in, and it will not be possible to log out.
Alternatively a test can be performed in code such as Java, see the following code snippet which requests information from a secure resource. The expected response will simply be an empty JSON array. If the user associated with the certificate does not have admin permissions or if the certificate is not being checked correctly, then the response will be an error or HTML text representing a redirect to the HTML home page.
Alternatively a test can be performed in code such as Java, see the following code snippet which requests information from a secure resource. The expected response will simply be an empty JSON array. If the user associated with the certificate does not have admin permissions or if the certificate is not being checked correctly, then the response will be an error or HTML text representing a redirect to the HTML home page.
Troubleshooting
If there are issues getting certificate authentication working try the following:
1. Remove the following from tomcat/conf/server.xml
<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />'
2. Ensure the Java version used to create the self-signed certificate is the same as the Java version used to run Tomcat. Tomcat may report Java version on startup, if not it will likely be set in your JAVA_HOME or JRE_HOME environment variable
