Skip to main content

Tomcat

Tomcat is the easiest way to deploy Universal Portal when the delivery team has access to the Controller's host, and if the Controller is accessed with an SSL.

Installation​

To install Universal Portal, simply drag and drop the .war file into the webapps folder where the Universal Controller is running.

info

You may rename the .war file to anything you like, but you must have a corresponding entry in your IdP settings that reflects the correct path. This IdP setting is generally known as the Redirect URI.

Universal Portal will be deployed to a URL corresponding to the name of the .war file. For example, for the file portal.war, the Portal URL will be your-domain.com/portal.

SSL​

End users must access Universal Portal via SSL.

Configuring SSL on Tomcat​

If the Controller is public facing, then configuring an SSL certificate on Tomcat directly satisfies the SSL requirement for Universal Portal.

To configure SSL on Tomcat, follow these steps:

  1. Combine key and certificate to PKCS``#12.

    openssl pkcs12 -export \
        -in certificate.crt \
        -inkey private.key \
        -out keystore.p12 \
        -name tomcat \
        -CAfile ca.crt \
        -caname root \
        -chain

    You will be prompted to enter a password for the resulting export.

  2. Convert .p12 to jks format.

    keytool -importkeystore \
        -destkeystore keystore.jks \
        -srckeystore keystore.p12 \
        -srcstoretype PKCS12 \
        -alias tomcat

    You will be prompted to input the password you entered in the previous step.

  3. Add connector configuration to server.xml.

    <Connector
        port="443"
        protocol="org.apache.coyote.http11.Http11NioProtocol"
        sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"
        maxThreads="150"
        maxPostSize="-1"
        SSLEnabled="true"
        scheme="https"
        secure="true"
        useSendfile="false"
        compression="on">
        <SSLHostConfig protocols="+TLSv1.3">
          <Certificate
                certificateKeystoreFile="/home/stonebranch/ssl_certificate/keystore.jks"
                certificateKeystorePassword="**************"
                type="RSA" />
        </SSLHostConfig>
    </Connector>

Configuring SSL on Cloud Load Balancers​

Cloud Load Balancers, such as Amazon's ALB, allow attaching signed certificates to their load balancers.

If the Controller is already served through a Cloud Load Balancer, and the load balancer is already configured with SSL, then the SSL requirement for Universal Portal is met.

Caching Policy​

When deployed as a war file, Universal Portal is backed with a custom Tomcat filter to fine tune caching of application assets.

If preferred, cache settings can be customized using the included filter's configuration settings to further improve caching performance.

<web-app
  xmlns="https://jakarta.ee/xml/ns/jakartaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                      https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
  version="5.0"
> 
  <error-page>
    <error-code>404</error-code>
    <location>/index.html</location>
  </error-page>

  <filter>
    <filter-name>NoCacheFilter</filter-name>
    <filter-class>com.stonebranch.NoCacheFilter</filter-class>

    <!--
    Leave commented to let browser handle caching of static
    assets. default value provided is equal to 1 hour.

    <init-param>
      <param-name>maxAgeSeconds</param-name>
      <param-value>3600</param-value>
    </init-param>
    -->

  </filter>

  <filter-mapping>
    <filter-name>NoCacheFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
</web-app>

Running Multiple Versions of Universal Portal​

You can install different versions of Universal Portal using different folder names within Tomcat. For canary deployments, this can help users migrate to a newer version of Universal Portal easily.

If adding multiple versions of Universal Portal to a Controller, keep the following considerations in mind:

  • Authentication state is shared.
    • If a user is logged onto the Portal running at /v1, then they will start authenticated at /v2.
    • If a user logs out from /v1, then they will also be logged out from /v2.
  • Localization preference is shared.
    • If a user sets their Portal to German at /v1, then /v2 will also switch to German.

CORS Requirements​

Because the Controller and Portal run on the same host domain, there are no CORS requirements in the Tomcat deployment model.