CAST AIP Console
Page tree
Skip to end of metadata
Go to start of metadata

Summary: this page describes how to change the Console front-end port number to enable HTTPS, for Console ≥ 2.x, Enterprise mode.

Introduction

By default, an unsecure http connection will be used for end-user access to Console (port 8081) in Console ≥ 2.x, Enterprise mode. This page explains how to change the Console front-end port number to enable a secured connection using https for access. There are two ways you can do this:

  • By installing an NGNIX web server to handle the SSL connection and then configure it as a reverse proxy to forward requests direct to the existing Console insecure ports. CAST highly recommends using this option since it separates the SSL configuration from the Console installation and is more simple to configure.
  • Configure SSL directly in two Console services - SSO (Keycloak) and Gateway

Option 1 - Use NGINX in reverse proxy mode

There are three parts to the configuration process:

Install and configure NGINX

  • Define an appropriate domain or subdomain for end user access to Console for example: console.mydomain.com - a DNS entry should point to the appropriate internal (or external) IP address on which the NGINX server will be installed
  • Install NGINX - see the following third-party documentation:
Linuxhttps://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/
Microsoft Windowshttp://nginx.org/en/docs/windows.html (note that NGINX on Microsoft Windows is considered a "beta", therefore you should use at your own risk)
  • Generate a public/private key pair (e.g. example.crt and example.key) for use with NGINX. This is beyond the scope of this documentation, however, any SSL tool such as Openssl or keytool can do this. NGINX requires only the location of the public/private key pair and does not require the key pair to be imported into a Java keystore.
  • Configure SSL in NGINX for your designated domain or subdomain (e.g. console.mydomain.com) - see http://nginx.org/en/docs/http/configuring_https_servers.html.
  • Add the reverse proxy redirect information into your NGINX configuration file - see https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/. You will need to create two forward blocks: one to the Gateway service (8081) and one to the SSO (Keycloak) service (8086) . In the example below, the Gateway service is running on 192.168.200.10:8081 and the SSO (Keycloak) service is running on 192.168.200.11:8086:
#=========   forward / to AIP-Gateway  =======================
        location / {               
                proxy_http_version 1.1;
                proxy_set_header  X-Real-IP $remote_addr;
                proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
                chunked_transfer_encoding off;
                proxy_buffering off;
                proxy_cache off;
                proxy_redirect off;
                client_max_body_size 100M; # this is required for uploading the source code zip to console
                proxy_set_header Host      $host;               
                proxy_set_header X-Forwarded-Proto $scheme; # to forward the  original protocol (HTTP or HTTPS)
                proxy_pass      http://192.168.200.10:8081;               
        }
#=========   forward /auth to AIP-SSO Keycloak   =======================
        location /auth {               
                proxy_hide_header Access-Control-Allow-Origin;
                add_header Access-Control-Allow-Origin $http_origin;
                proxy_pass      http://192.168.200.11:8086;               
        }

Modify the aip_config schema

Connect to the CAST Storage Service/PostgreSQL instance on which the aip_config schema is located (this schema is installed by the Service Registry when it is first started up - in Enterprise mode for Docker, this schema will be located in the CAST Storage Service/PostgreSQL instance deployed in Docker, and for Enterprise mode for Java JAR installers, it will be located in the CAST Storage Service/PostgreSQL instance chosen during the Service Registry installation - see 2.x - Enterprise mode - Installation of AIP Console front-end via Java JAR installers).

Locate the properties table in the aip_config schema and then locate the keycloak.uri entry:

Click to enlarge

The Value column contains the URI used to access the SSO/Keycloak service - you need to change this value to the domain or subdomain you have configured in NGINX. Using the subdomain console.mydomain.com, you should enter https://console.mydomain.com:

Ensure the new value is saved.

Modify the SSO (Keycloak) redirect

You will now need to add a new redirect to allow access to SSO (Keycloak) from the domain or subdomain you are using for secure access to Console. To do so, log in to the Keycloak admin panel using the existing insecure access url (see also Initial login to Keycloak and configure a redirect - v. 2.x) for example:

  • http://localhost:8086
  • http://my_host:8086
  • http://some_ip_address:8086

Click the Clients option and then click aip-console-client:

Click to enlarge

Now add a new redirect:

The URL should use the http protocol for the domain or subdomain you are using for secure access to Console:

  • http://console.mydomain.com/*

Ensure you save the changes:

You can optionally:

Restart all services and test access

Restart all CAST Console services and the NGINX server to ensure that all changes are correctly taken into account. Finally test access to CAST Console using your configured sub-domain and the https protocol: https://console.mydomain.com/

Option 2 - Configure SSL directly

CAST does not recommend this method since it is more complex and requires dedicated SSL configurations and certificates for two Console services:

  • SSO (Keycloak)
  • Gateway

Where the SSO (Keycloak) and the Gateway services are installed on the same machine, each service must use a dedicated SSL port (e.g 443 and 8443). CAST recommends that:

  • SSO (Keycloak) is defined with an alternative SSL port such as 8443 (this is the default for Keycloak https)
  • Gateway is defined with the standard SSL port 443 - this means end users will be able to use a simple URL to access Console, rather than having to append a port number.

You will also need to define an appropriate domain or subdomain for end user access to Console for example: console.mydomain.com and a corresponding DNS entry for the machine on which the two services are installed.

This method assumes that the SSO (Keycloak) and Gateway services are installed on the same machine.

SSO (Keycloak)

Enable SSL

  • See https://www.keycloak.org/docs/14.0/server_installation/index.html#_setting_up_ssl for general information.
  • CAST recommends using an alternative to the standard 443 port, such as 8443 (this is the default for Keycloak)
  • Keycloak requires a Java format Keystore (.jks) in which all required private keys, public CA signed/self-signed certificates must be stored.
  • These instructions use a private/public key pair as an example:
    • example.key (private key file)
    • example.crt (public or self-signed certificate file)

Enabling SSL directly in Keycloak requires:

  • Obtaining or generating a keystore that contains the private key and certificate for SSL/HTTPS traffic

  • Configuring the Keycloak server to use this keypair and certificate.

Obtaining or generating a keystore containing keys and certificates

The generation of a self-signed certificate or public CA signed certificate and corresponding private keys is beyond the scope of this documentation, however, when you have the certificate/private key pair, they need to be imported into a Java keystore called keycloak.jks that Keycloak will reference. Private .key files cannot be stored directly in a Java format Keystore (.jks), therefore you will need to first convert/combine the private .key and relevant certificate files into PKS12 format, which can then be imported into the Java format Keystore (.jks). To do so, run the following command using the openssl tool to generate the .P12 PKS12 format keystore:

openssl pkcs12 -export -in example.crt -inkey example.key -name keycloak -out keycloak.p12

Now run the following command using the Java keytool tool. This will import the PKS12 keystore into the Java format keystore (.jks):

keytool -importkeystore -srckeystore keycloak.p12 -destkeystore keycloak.jks -srcstoretype PKCS12

The resulting keycloak.jks file should then be moved to the following location:

%PROGRAMFILES%\CAST\CAST-Imaging-Console\AIP-SSO\opt\jboss\keycloak\standalone\configuration
or:
%PROGRAMFILES%\CAST\AIP-SSO\opt\jboss\keycloak\standalone\configuration

Configure keycloak to use keycloak.jks Java keystore

Open and edit the following file in a text editor:

%PROGRAMFILES%\CAST\CAST-Imaging-Console\AIP-SSO\opt\jboss\keycloak\standalone\configuration\standalone.xml
or:
%PROGRAMFILES%\CAST\AIP-SSO\opt\jboss\keycloak\standalone\configuration\standalone.xml

Add a new security-realm called UndertowRealm to the existing <security-realms> tag. This realm references the keycloak.jks keystore created earlier. You will also need to input the keystore password (defined during the keystore creation process) replacing <keystorepassword>:

<security-realm name="UndertowRealm">
	<server-identities>
		<ssl>
			<keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="<keystorepassword>" />
		</ssl>
	</server-identities>
</security-realm>

For example:

Click to enlarge

Now locate the existing <subsystem xmlns="urn:jboss:domain:undertow:12.0"> tag, and modify the <https-listener> and the<http-invoker> to use the security-realm you just added - i.e. change security-realm="ApplicationRealm" to security-realm="UndertowRealm":

Click to enlarge

Change Keycloak port binding offset

Althought Keycloak is configured to listen for https requests by default on port 8443, a custom port offset for the 8086 http port is configured by CAST. This port offset needs modifying to 0 to ensure that https requests are accepted correctly on port 8443 (and not 8449). To do so, modify and edit the following file with a text editor:

%PROGRAMFILES%\CAST\CAST-Imaging-Console\AIP-SSO\opt\jboss\keycloak\bin\service\system.properties
or:
%PROGRAMFILES%\CAST\AIP-SSO\opt\jboss\keycloak\bin\service\system.properties

Change the jboss.socket.binding.port-offset parameter to 0:

jboss.socket.binding.port-offset=0
keycloak.import=../standalone/tmp/aip-realm.json
jboss.bind.address.management=0.0.0.0
jboss.bind.address=0.0.0.0

Modify the aip_config schema

See the section above: Modify the aip_config schema. You should enter a value that matches the Keycloak secure URL. For example:

  • if you have enabled SSL on port 8443, you should enter https://console.castsoftware.com:8443
  • if you have enabled SSL on the standard port 443 (not reccommended), you should enter https://console.castsoftware.com

Modify the SSO (Keycloak) redirect

See the section above: Modify the SSO (Keycloak) redirect - note that the redirect URL should be entered using the https protocol, not http.

Restart SSO/Keycloak

Restart the SSO/Keycloak service to ensure that all changes are correctly taken into account.

Gateway

Enable SSL

You can take inspiration from this third party documentation: https://docs.spring.io/spring-cloud-skipper/docs/1.0.0.BUILD-SNAPSHOT/reference/html/configuration-security-enabling-https.html

Enabling SSL directly in the Gateway service requires:

  • Obtaining or generating a keystore that contains the private key and certificate for SSL/HTTPS traffic

  • Configuring the Gateway to use this key pair

Obtaining or generating a keystore containing keys and certificates

Assuming that the Gateway and SSO/Keycloak services are on the same host server, you can re-use the Java keystore (keycloak.jks) created for the SSO/Keycloak service. Therefore, copy the existing keycloak.jks file to the following location:

%PROGRAMDATA%\CAST\CAST-Imaging-Console\AIP-Gateway\
or:
%PROGRAMDATA%\CAST\AIP-Gateway\

Configure SSL for the Gateway

You will need to enable SSL for the Gateway service - this is done by adding the appropriate SSL configuration (port number, SSL directives) to the following file (CAST recommends using the standard 443 port):

%PROGRAMDATA%\CAST\CAST-Imaging-Console\AIP-Gateway\application-default.yml
or:
%PROGRAMDATA%\CAST\AIP-Gateway\application-default.yml

Edit the existing server entry to add in the required SSL configuration (key-alias, key-store-password and key-password were defined when the key pair and keystore were created), for example:

server:
	port: 443
	ssl:
		enabled: true
		key-alias: <aliasname>
		key-store: <path to keystore file, e.g. keycloak.jks>
		key-store-type: PKCS12
		key-store-password: <keystore password>
		key-password: <key password>

Save the file.

Restart Gateway

Restart the Gateway service to ensure that all changes are correctly taken into account.

Restart Node(s) and Service Registry services

The final step is restart the Node(s) and the Service Regsitry services so that the changes made to the SSO/Keycloak and the Gateway services are taken into account.

  • No labels