Product Documentation

Install SKFS on a single node.


Prerequisites

  • Rocky Linux 9.3

  • Openjdk 21

  • Openldap-clients and Openldap-servers 
  • Virtual Machine (VM) with a minimum of 20GB space and 4GB memory assigned to it; some default VMs do not allocate sufficient space and memory,  verify before getting started

  • A public fully qualified domain name (FQDN). It is very important to have a hostname that is at least top-level domain (TLD)+1 (i.e., acme.com, example.org, etc.). Otherwise FIDO2 functionality may not work

  • The installation script installs Payara running HTTPS on port 8181, make sure all firewall rules allow port 8181 to be accessed

  • StrongKey FIDO Server (SKFS) must be installed before the sample service provider web application and sample WebAuthn Java client

Installation

NOTE: If the install fails for any reason, follow the instructions for Removal and restart from the beginning.

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

  2. If this is fresh installation of the Rocky Linux OS, run the following commands:
    shell> dnf install initscripts
    
    shell> ln -s /usr/lib64/libncursesw.so.6.2 /usr/lib64/libncurses.so.5 
    shell> ln -s /usr/lib64/libncursesw.so.6.2 /usr/lib64/libtinfo.so.5
    
  3. Install wget if it has not been already.

    shell> sudo yum install wget

    or

    shell> sudo apt install wget
  4. Download the latest binary distribution file fido2server-v4.14.0-dist.tgz from SourceForge:

    shell> wget https://sourceforge.net/projects/strongkeyfido/files/v4.14.0/server/fido2server-v4.14.0-dist.tgz
  5. Verify if sha256sum for the distribution matches db406e4a94f876c0bbad4e1d6a2e83b054bf4b058cc63088a196b0c1dbb87f16
    shell> sha256sum fido2server-v4.14.0-dist.tgz
  6. Extract the downloaded file to the current directory:

    shell> tar xvzf fido2server-v4.14.0-dist.tgz
  7. Be sure the machine's FQDN is set as its hostname. This is necessary to properly configure the self-signed certificate for the API. Verify using 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. DO NOT run this if the machine does not have a configured FQDN and is still running as localhost.

    shell> echo `hostname -I | awk '{print $1}'` $(hostname) | sudo tee -a /etc/hosts

    NOTE: If running this installation as part of a different installation, stop here and return to the originating instructions.

  8. Edit the SKFS installation script using your preferred text editor (in this example, we will use vi)
    shell> sudo vi install-skfs.sh

    The installation script contains configurable values that allow one to customize how the SKFS will function. In particular, here is a recommended value to be changed:

    RPID: The RPID (relying party identifier) is a valid domain string identifying the WebAuthn Relying Party on whose behalf a given registration or authentication ceremony is being performed. The RPID for a WebAuthn operation should be set to the caller’s origin's effective domain. By default, the RPID is set to "strongkey.com"

    If your SKFS installation requires the use of JWTs or SAML for SSO, here are some recommended values to be edited:

    SSO_KEYSTORE_PASS: Property to determine password of the SSO keystore

    JWT_CREATE: Property to determine if authentication web service should return a JWT
    JWT_DURATION: Property to determine how long a JWT will be active for (in seconds)
    JWT_KEYGEN_DN: Property to determine the distinguished name of the JWT certificates created
    JWT_CN_LIST=Property to determine the common name for the JWT certificates
    JWT_KEY_VALIDITY: Property to determine how long the key is valid for (in days)

    SAML_RESPONSE: Property to determine if authentication web service should return a SAML Assertion
    SAML_CITRIX: Property to determine whether the SKFS is communicating with Citrix ADC as an SP for SAML authentication
    SAML_DURATION: Property to determine amount of time a SAML assertion will be active (in minutes)
    SAML_KEYGEN_DN: Property to determine the distinguished name of the SAML certificates created
    SAML_CN_LIST=Property to determine the common name for the SAML certificates
    SAML_TIMEZONE: Property to determine time zone code used for the returned SAML response (case sensitive)
    SAML_KEY_VALIDITY: Property to determine how long the key is valid for (in days)
  9. Execute the install-skfs.sh script as follows:

    NOTE: If you are installing on Ubuntu VM, please make sure you are using bash as your default. If the default is set to sh, please execute sudo dpkg-reconfigure dash to change the default to bash before continuing.
    shell> sudo ./install-skfs.sh

    The installation script will create a strongkey user account with the home directory of /usr/local/strongkey. All software required for SKFS will be deployed to the /usr/local/strongkey directory and be run by the strongkey user. The default password for the strongkey user is ShaZam123.

  10.  The installation script also creates eight different domains configured with eight different policies. If you wish to change the RPID and/or any other rules for the policy post installation, please refer this section.

  11. Using the following command, confirm SKFS is running. The API Web Application Definition Language (WADL) file comes back in response.

    shell> curl -k https://localhost:8181/skfs/rest/application.wadl
  12. Use the ping web service or the sample skfsadminclient tool to ping and test whether the SKFS installation was successful.
    shell> java -jar skfsclient/skfsadminclient.jar P       
    
    Example:
    java -jar skfsclient/skfsadminclient.jar P https://example.strongkey.com:8181 1 REST PASSWORD fidoadminuser Abcd1234!
    

To test this installation of SKFS, check out the Basic Java Sample application or a JAVA proof of concept (PoC) application, which also involves user registration via emails.

StrongKey has also built various sample demos to showcase the capabilities of StrongKey’s open-source FIDO® Certified server (SKFS). Learn more from the code for these sample applications on SourceForge.

NOTE: Both the signing and secret keys in the keystore use default values and should be changed after installation is completed. The keystore and the TrustStore are located in /usr/local/strongkey/skfs/keystores. Run the following command from usr/local/strongkey/keymanager to see the usage and syntax for the keymanager tool, then change them both (The default password for the files is Abcd1234!):

shell> java -jar keymanager.jar