GR:Gravity/Server/Setup/HTTPS
Server SSL Certificate Setup
Setting up the Gravity OSGi (Web) server as a certificate provider allows clients to access the Gravity server over a secure connection using the HTTPS protocol. You can setup the server to use a certificate key-store that you provide or use the certificate key-store generated by the server. By default the Gravity OSGi server will use an internally created key-store when the 'web.https.port' property has been set in the server configuration. The key-store will contain a self-signed certificate with the common-name set to the configured server.contact.name. Note that as the internally created certificate is self-signed, it will not be automatically be trusted by clients (see Setup Gravity client to accept SSL certificates).
The procedure described here does not apply to the Tomcat based Gravity server. If you want to use (self-signed) server certificates then you must switch to the Gravity OSGi server.
If you are running Gravity server behind a reverse proxy then the server must be configured as outlined in Gravity Server behind a Reverse Proxy
Setup using your own key-store
To configure the Gravity standalone jetty server as a certificate provider you need to provide a java key store file in JKS format, and the storepass password. The following configuration properties need to be set in the gravity properties file:
- web.ssl.keystore.file=?/home/user/keystore.jks?
- web.ssl.keystore.password=?secret?
The properties file is located in the Gravity installation directory under ?Gravity-Installation-Dir?/.data/store/_config_admin_config.properties.
Note the key-store file must be fully qualified. On Windows preferably use forward slashes as the path separator, for example c:/temp/keystore.jks. If you cannot use forward slashes then you must escape a backslash with a second backslash, for example c:\\temp\\keystore.jks. The provided key-store password will be automatically encrypted when the Gravity server processes the configuration file during startup. Also if the key-store was created with the keypass and storepass option then both passwords must be the same.
If the key-store has multiple certificates then you can define the certificate to be used by setting the certificate alias, for example:
- web.ssl.keyalias=cert - v1.1
Note. If the key-store contains more than 1 certificate but no key-store alias is defined then the first certificate will be used, this may not necessarily be the one the server should be using. Also if the web.ssl.keystore.file is updated with a different file name or location then the web.ssl.keystore.password must be set as clear text again (will be automatically encrypted upon Gravity startup).
Finally a HTTPS port needs to be assigned for the HTTPS requests:
- web.https.port=?45053?, this port must be open on the firewalls leading to the Gravity server.
If it also required to redirect HTTP requests to HTTPS then the following configuration property must be set:
- web.https.only=true
An example of a HTTPS configuration:
web.https.only=true web.http.port=45050 web.https.port=45053 web.ssl.keystore.file=c:/data/certificates/server.jks web.ssl.keystore.password=secret
With the above example configuration, if loading the jks key-store was successful then a line similar to the one below will be logged in the gravity.log:
INFO c.r.g.s.j.JettyServerComponent: successfully started the jetty server ..., port=45050/45053, https-only=true, bind-address=0.0.0.0
If loading the jks key-store failed then an exception will have been logged previous to the above INFO line and only port 45050 will be available for HTTP communication.
If Gravity was previously configured to use an internally created jks key-store then the property 'web.ssl.server.internal.keystore=true' needs to be removed.
Setup using the Server key-store
If you do not have your own SSL certificate key-store but you still want to have a secure (encrypted) connection between the server and a client then the Gravity server can create a keystore for you containing a self-signed certificate. To enable this option you need to set the configuration property 'web.https.port=?45053?' and optionally the property 'web.https.only=true'.
A keystore and certificate will be created in the server's home location in the directory '.data/store'. The keystore and certificate base name will be the same as the server's contact name (server.contact.name in the properties file). The keystore is of type java keystore and file will have the extension jks, the certificate will have the extension .crt. The certificate's common name (a.k.a. host or domain name) and subject alternate name (SAN) will be set with the server's contact name as this is the name that will be used by clients to contact the server.
Note that using a self-signed certificate is under most circumstance considered unwise, you are advised not to use self-signed certificates over a public connection unless you are completely aware of the consequences (see section About SSL Certificates). Then again self-signed certificates can be useful if you require encryption but do not need to verify the identity of the Gravity site you are accessing as might be the case with a Gravity site running in your intranet.
If the Gravity server has a self-signed certificate then the property '.web.ssl.is.server.internal.keystore=true' will be set in the server's configuration file.
Using self-signed certificates in a web client
When a web client tries to access the server over a secure HTTPS connection then the server will send its certificate to the client and the web client will respond with a dialog asking you to accept or reject the certificate. In the case of a self-signed certificate the web client will also warn you that the certificate has not been signed by a Certificate Authority and that there is insufficient information to verify its identity, requiring a second confirmation to accept the certificate.
For self-signed certificates you can avoid questions about certificate authenticity by importing the (Gravity server) certificate into the web client and, depending on the web client, assigning it as a trusted certificate. Once loaded the web client will check its list of trusted SSL certificates before presenting a dialog. Upon request your Gravity administrator should be able to provide you with a certificate for the Gravity server you wish to access.
Note that if the Gravity server is accessible via different names or additional IP addresses then the host name in the URL won't match the server's certificate domain/host name and the web client will handle the name mismatch as a security exception.
To fix this you must either add a Security Exception for the failing URL. Optionally, you could also add an entry to your 'hosts' file that maps the server's host name to the IP address that you are using to access the server.