Product Documentation
    Prerequistes

    This application depends on the following technologies:

    • Strongkey's Appliance (SAKA) with SKFS

    • JDK 21

    • Payara Server 6.2024.4
    • A public fully qualified domain name (FQDN) for the machine.
    • Binary Distribution for SKSO
    • jwtsigningtruststore.bcfks
    • The installation script installs Payara running HTTPS on port 8181, so make sure all firewall rules allow that port to be accessed.

     

    NOTE: If FIPS is enabled, disable FIPS to perform asadmin commands using export _JAVA_OPTIONS=-Dcom.redhat.fips=false

    Setup

    1. Open a terminal and change directory to the target download folder.

    2. Extract the downloaded binary ditribution file to the current directory:

      shell> tar xvzf <SKSO-Distribution-file>

    3. Verify the machine's FQDN is set as its hostname. This is necessary to properly configure the self-signed certificate for the API. 

      Run the following command:

      shell> hostname

      If only the machine name is returned, and not the public FQDN, run the following command:

      shell> sudo hostnamectl set-hostname <SERVER PUBLIC FQDN>

      If no DNS is configured for this machine, please run the following command to add an entry to the /etc/hosts file.

      shell> echo `hostname -I | awk '{print $1}'` $(hostname) | sudo tee -a /etc/hosts
    4. Create the strongauth group and user and add it to /etc/sudoers 
      groupadd strongauth 
useradd -g strongauth -c"strongauth" -d /usr/local/strongauth -m strongauth
echo strongauth: "enter-password for strongauth user" | /usr/sbin/chpasswd
    5. Create a list of sudoers with following permissions
      cat >> /etc/sudoers <<-EOFSUDOERS
## SKSO permissions
Cmnd_Alias SKSO_COMMANDS = /usr/bin/systemctl start payara, /usr/bin/systemctl stop payara, /usr/bin/systemctl restart payara
strongauth ALL=SKSO_COMMANDS
EOFSUDOERS
    6. Make the following directories:
      mkdir -p /usr/local/strongauth/certs /usr/local/strongauth/bin /usr/local/strongauth/skfs/keystores /usr/local/strongauth/skso /usr/local/strongauth/skso/etc
    7. Unzip Payara
      unzip payara-6-XXXX.X.zip -d /usr/local/strongauth
    8. Change ownership of the files and start payara 
      cp payara.service /etc/systemd/system
systemctl daemon-reload
systemctl enable payara
    9. Either use a custom certificate or generate self signed certificate for Payara and import into the keystore and Java Truststores.

      GENERATE SELF SIGNED CERTIFICATE

      keytool -genkeypair -alias skso -keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -storepass changeit -storetype pkcs12 -keypass changeit -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -validity 365 -dname "CN=$(hostname),OU=\"strongauth Sign-On\"" 
      keytool -changealias -alias s1as -destalias s1as.original -keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -storepass changeit -storetype pkcs12
      keytool -changealias -alias skso -destalias s1as -keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -storepass changeit -storetype pkcs12
      sed -ri 's|^(com.sun.enterprise.server.logging.GFFileHandler.rotationOnDateChange=).*|\1true| s|^(com.sun.enterprise.server.logging.GFFileHandler.rotationLimitInBytes=).*|\1200000000|' /usr/local/strongauth/payara6/glassfish/domains/domain1/config/logging.properties
      keytool -exportcert -alias s1as -file /usr/local/strongauth/certs/$(hostname).der --keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -storepass changeit -storetype pkcs12
      keytool -importcert -noprompt -alias $(hostname) -file /usr/local/strongauth/certs/$(hostname).der --keystore /usr/local/strongauth/certs/cacerts -storepass changeit -storetype pkcs12
      keytool -importcert -noprompt -alias $(hostname) -file /usr/local/strongauth/certs/$(hostname).der --keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/cacerts.p12 -storepass changeit -storetype pkcs12

      IMPORT A CUSTOM CERTIFICATE

      Collect all the files (private key) generated and the signed certificate from the Trusted-Third Party Certificate Authority (TTPCA). Create a .pkcs12 file using the certificate and private keys collected. 

      openssl pkcs12 -export -in <signed_cert> -inkey <private-key>.key -out custom-keystore.p12 -name skso

      Now use this custom keystore (custom-keystore.p12) to import the certificate in Glassfish keystore by following the steps below. 

      keytool -importkeystore -srckeystore <PATH TO KEYSTORE>/custom-keystore.p12 -srcstoretype pkcs12 -destkeystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -deststoretype pkcs12
      keytool -changealias -alias s1as -destalias s1as.original -keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -storepass changeit -storetype pkcs12
      keytool -changealias -alias skso -destalias s1as -keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -storepass changeit -storetype pkcs12
      sed -ri 's|^(com.sun.enterprise.server.logging.GFFileHandler.rotationOnDateChange=).*|\1true| s|^(com.sun.enterprise.server.logging.GFFileHandler.rotationLimitInBytes=).*|\1200000000|' /usr/local/strongauth/payara6/glassfish/domains/domain1/config/logging.properties
      keytool -exportcert -alias s1as -file /usr/local/strongauth/certs/$(hostname).der --keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/keystore.p12 -storepass changeit -storetype pkcs12
      keytool -importcert -noprompt -alias $(hostname) -file usr/local/strongauth/certs/$(hostname).der --keystore usr/local/strongauth/certs/cacerts -storepass changeit -storetype pkcs12
      keytool -importcert -noprompt -alias $(hostname) -file /usr/local/strongauth/certs/$(hostname).der --keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/cacerts.p12 -storepass changeit -storetype pkcs12
    10. Change ownership of the files and start payara
      chown -R strongauth:strongauth /usr/local/strongauth
systemctl daemon-reload
systemctl start payara
    11. Perform Payara tasks 
      asadmin set server.network-config.network-listeners.network-listener.http-listener-1.enabled=false
      asadmin set server.network-config.protocols.protocol.http-listener-2.http.request-timeout-seconds=7200
      asadmin set server.network-config.protocols.protocol.http-listener-2.ssl.ssl3-tls-ciphers=+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,+TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA
      asadmin set server.network-config.protocols.protocol.http-listener-2.http.trace-enabled=false
      asadmin set server.network-config.protocols.protocol.http-listener-2.http.xpowered-by=false
      asadmin delete-jvm-options $(/usr/local/strongauth/payara6/glassfish/bin/asadmin list-jvm-options | sed -n '/\(-XX:NewRatio\|-XX:MaxPermSize\|-XX:PermSize\|-client\|-Xmx\|-Xms\)/p' | sed 's|:|\\\\:|' | tr '\n' ':')
      asadmin create-jvm-options -Djtss.tcs.ini.file=/usr/local/strongauth/lib/jtss_tcs.ini:-Djtss.tsp.ini.file=/usr/local/strongauth/lib/jtss_tsp.ini:-Xmx512m:-Xms512m:-Djdk.tls.ephemeralDHKeySize=2048:-Dproduct.name="":-XX\\:-DisableExplicitGC
    12. Configure JWT keystores from SKFS 
      cp jwtsigningtruststore.bcfks /usr/local/strongauth/skfs/keystores
    13. Create a configuration file for SKSO
      sudo vi /usr/local/strongauth/skso/etc/skso-configuration.properties
    14. Add the configuration properties property to configure SKSO VM instances with SAKA-SKFS
      skso.cfg.property.apiuri=https://**[hostname of SAKA Server]**:8181
      skso.cfg.property.referer=https://**[hostname for Citrix ADC]**/
      skso.cfg.property.rpid=<RPID for SAKA>
      skso.cfg.property.citrix.integration=true
      skso.cfg.property.jwtverificationips=<IPaddress of SKSO-01,IP address of SKSO-02>

    15. If not utilizing the default domain(1) on SAKA, there is an option to modify the DomainID(did) property as demonstrated below:

      skso.cfg.property.did=2

    16. SKSO uses the JWT returned by SKFS for the user authentication state management.  Enable it by changing the following config property for SKFS to return a JWT

      skfs.cfg.property.jwt.create=true
    17. Create a disclosure agreement file like this. 
      vi /usr/local/strongauth/skso/etc/disclosure.txt ​
    18. To change the Disclosure Agreement file location, modify the Config property. 
      skso.cfg.property.disclosurefilelocation=/usr/local/strongauth/skso/etc/disclosure.txt ​

    19. Change ownership of skso directory

      chown -R strongauth:strongauth /usr/local/strongauth/skso

    20. SKSO application is packaged as a .war file which can directly be deployed on Payara Application server by running the following command

      asadmin deploy skso.war​

    21. Restart payara

      systemctl restart payara

    22. SKSO uses strict contents-security-policy to protect against XSS attacks. To allow SKSO to submit form to Citrix for SAML Auth, Add 'Form-Action-Policy' to Payara System Properties with the URL where Citrix is expecting SAML response by running the following command as strongauth user

      asadmin create-system-properties FORM_ACTION_SOURCE=https\\://<CITRIX_FQDN>​

    23. Restart payara

      systemctl restart payara

    24. Optionally import the certificate of the AD servers, Tellaro servers and/or the Tellaro load balancers in SKSO payara trustore. Download all the necessary certificates before running the following command.

      keytool -import -file <certificate file> -keystore /usr/local/strongauth/payara6/glassfish/domains/domain1/config/cacerts.p12 -storepass changeit -alias <alias>
      systemctl restart payara