19. Enabling HTTPS

19. Enabling HTTPS
Prev	Part VII. Security	Next

By default, the REST endpoints use plain HTTP as a transport. You can switch to HTTPS by adding a certificate to your configuration, as shown in the following skipper.yml example:

server:
  port: 8443                                         
  ssl:
    key-alias: yourKeyAlias                          
    key-store: path/to/keystore                      
    key-store-password: yourKeyStorePassword         
    key-password: yourKeyPassword                    
    trust-store: path/to/trust-store                 
    trust-store-password: yourTrustStorePassword

	As the default port is `7577`, you may choose to change the port to a more common HTTPs-typical port.
	The alias (or name) under which the key is stored in the keystore.
	The path to the keystore file. Classpath resources may also be specified, by using the classpath prefix: `classpath:path/to/keystore`
	The password of the keystore.
	The password of the key.
	The path to the truststore file. Classpath resources may also be specified, by using the classpath prefix: `classpath:path/to/trust-store`
	The password of the trust store.

	Tip
	You can reference the YAML file using the following parameter: `--spring.config.location=skipper.yml`

	Note
	If HTTPS is enabled, it completely replaces HTTP as the protocol over which the REST endpoints interact. Plain HTTP requests then fail. Therefore, you must make sure that you configure the Skipper shell accordingly.

19.1 Using Self-Signed Certificates

For testing purposes or during development, it might be convenient to create self-signed certificates. To get started, run the following command to create a certificate:

$ keytool -genkey -alias skipper -keyalg RSA -keystore skipper.keystore \
          -validity 3650 -storetype JKS \
          -dname "CN=localhost, OU=Spring, O=Pivotal, L=Holualoa, ST=HI, C=US"  
          -keypass skipper -storepass skipper

CN is the only important parameter here. It should match the domain you are trying to access, e.g. localhost.

Then add the following to your skipper.yml file:

server:
  port: 8443
  ssl:
    enabled: true
    key-alias: skipper
    key-store: "/your/path/to/skipper.keystore"
    key-store-type: jks
    key-store-password: skipper
    key-password: skipper

That is all you need for the Skipper Server. Once you start the server, you should be able to access it at https://localhost:8443/. As this is a self-signed certificate, you should hit a warning in your browser. You need to ignore that.

19.2 Self-Signed Certificates and the Shell

By default, self-signed certificates are an issue for the shell. Additional steps are necessary to make the shell work with self-signed certificates. Two options are available:

19.2.1 Add the Self-signed Certificate to the JVM Truststore

In order to use the JVM truststore option, we need to export the previously created certificate from the keystore:

$ keytool -export -alias skipper -keystore skipper.keystore -file skipper_cert -storepass skipper

Next, we need to create a truststore which the Shell uses:

$ keytool -importcert -keystore skipper.truststore -alias skipper -storepass skipper -file skipper_cert -noprompt

Now you can launch the Skipper shell by using the following JVM arguments:

$ java -Djavax.net.ssl.trustStorePassword=skipper \
       -Djavax.net.ssl.trustStore=/path/to/skipper.truststore \
       -Djavax.net.ssl.trustStoreType=jks \
       -jar spring-cloud-skipper-shell-1.0.2.RELEASE.jar

	Tip
	If you run into trouble establishing a connection over SSL, you can enable additional logging by setting the `javax.net.debug` JVM argument to `ssl`.

Remember to target the Skipper server with a config command similar to the following:

skipper:>skipper config --uri https://localhost:8443/api

19.2.2 Skip Certificate Validation

Alternatively, you can bypass the certification validation by providing the following optional command-line parameter: --spring.cloud.skipper.client.skip-ssl-validation=true.

When you set this command-line parameter, the shell accepts any (self-signed) SSL certificate.

	Warning
	If possible, you should avoid using this option. Disabling the trust manager defeats the purpose of SSL and makes your site vulnerable to man-in-the-middle attacks.