Configuring SAML Authentication for Innoslate with Java 21

This outlines the process for configuring SAML authentication in Innoslate version 4.12 and above using Java 21. SAML (Security Assertion Markup Language) authentication relies on a certificate to verify the identity of the response publisher, ensure the signature's integrity, and confirm that the data has not been tampered with during transit.

Note: Innoslate 4.12 requires Apache Tomcat 11, which is included in the Innoslate installer.

Prerequisites

• Java 21 installed (e.g., JDK 21.0.X)
• OpenSSL installed and configured in your system path
• Administrative access to the host operating system terminal/command prompt
• Access to the Identity Provider (IdP) metadata file (e.g., IDPMetadata.xml)
• Innoslate version 4.12 or higher installed with Apache Tomcat 11 (e.g., C:\Innoslate4\apache-tomcat)
• A certificate (e.g., saml.crt) and its corresponding unencrypted private key (e.g., saml.pem or saml.key)

Part 1: Configuring the Service Provider Keystore

Innoslate requires a Java KeyStore (.jks) file to manage the cryptographic keys used for SAML communication. Depending on your organization's security infrastructure, follow either Option A for standard deployments or Option B for strict CA-signed deployments.

Option A: Standard Configuration (Self-Signed Keypair)

If your organization allows self-signed certificates for SAML transaction signing, generate a new keystore natively using the Java keytool utility:

1. Open your command prompt (Windows) as an Administrator.

2. Execute the following command to generate the keystore file and keypair container. Replace your_password with your actual secure environment password.

keytool -genkeypair -alias saml -keyalg RSA -keystore SPKeystore.jks -storepass your_password -keypass your_password -validity 3650 -keysize 2048

Option B: Advanced Configuration (CA-Signed Certificate Bundle)

For federal, defense, or strict corporate networks, you may need to use a certificate issued by a trusted Certificate Authority (CA). To prevent validation errors, you must bundle your leaf certificate alongside its intermediate and root CA certificates into a complete trust chain.

1. Extract and Bundle Using OpenSSL: Ensure your certificate file (saml.crt) contains your server's leaf certificate followed directly by your intermediate and root CA certificate blocks. Export them with your private key into a clean PKCS12 file:

openssl pkcs12 -export -in saml.crt -inkey saml.pem -out SPKeystore_clean.p12 -name saml

Set an export password that matches your planned Innoslate application settings.

2. Convert to a Compliant JKS Format: Migrate the PKCS12 bundle into a production-compliant Java KeyStore (.jks) container:

keytool -importkeystore -srckeystore SPKeystore_clean.p12 -srcstoretype PKCS12 -destkeystore SPKeystore.jks -deststoretype JKS -srcalias saml -destalias saml

Ensure the source, destination, and key passwords match identically when prompted.

3. Verify the Completed Chain: Confirm that the Java runtime recognizes the complete certificate path layout:

keytool -list -v -keystore SPKeystore.jks

Verify that the output displays exactly 1 entry, shows Entry type: PrivateKeyEntry, and lists a Certificate chain length: 3 (or 2, depending on your CA root infrastructure).

Part 2: File Placement & Deployment

1. Copy your newly built SPKeystore.jks file and your Identity Provider's IDPMetadata.xml file.
2. Navigate to your Innoslate installation's designated SAML directory:
   • C:\Innoslate4\apache-tomcat\webapps\innoslate4\WEB-INF\classes\saml
3. Paste both files directly into this directory.
4. Provide your public server certificate (saml.crt) to your IdP administrator to complete the trust relationship on their dashboard.

Part 3: Configuring settings.properties file

1. Open your application configuration file located in the web application directory:
   C:\Innoslate4\apache-tomcat\webapps\innoslate4\WEB-INF\classes\settings.properties
2. Update or append the following properties to match your configuration values:

AUTHENTICATION_TYPE=SAML
KEY_ENTRY_ID=saml
KEY_STORE_NAME=SPKeystore.jks
KEY_STORE_PASSWORD=password
PRIVATE_KEY_PASSWORD=password
SP_ENTITY_ID=https://innoslate.dev.na.doe.gov
METADATA_NAME=IDPMetadata.xml
SAML_RESPONSE=SAMLResponse

Property Descriptions:

AUTHENTICATION_TYPE: Specifies the system authentication wrapper logic. Set to SAML.

KEY_ENTRY_ID: The core alias of the private key stored inside your Java Keystore (e.g., saml).

KEY_STORE_NAME: The exact filename of your keystore file located in the application's saml directory.

KEY_STORE_PASSWORD: The master password required to unlock the Java Keystore container.

PRIVATE_KEY_PASSWORD: The explicit password required to read the private key entry itself.

SP_ENTITY_ID: A globally unique URI identifier for your Innoslate instance, matching character-for-character with what is registered inside your IdP application portal.

METADATA_NAME: The filename of the trusted IdP metadata XML file.

SAML_RESPONSE: The expected inbound payload parameter name for the Base64-encoded authentication assertion. Defaults to SAMLResponse.

Part 4: Verification and Application Cache Reset

To ensure that Tomcat completely purges its environmental memory cache and loads the brand-new keystore settings:

1. Stop the Innolate service (C:\Innoslate4\utilities\force_stop_innoslate.cmd)
2. Navigate to your Tomcat runtime folder and delete all files inside these cache directories: 
   • C:\Innoslate4\apache-tomcat\work\
   • C:\Innoslate4\apache-tomcat\temp\
3. If an old, cached metadata file exists at C:\Innoslate4\apache-tomcat\webapps\innoslate4\WEB-INF\classes\saml\sp-metadata.xml, delete it to force the system to rebuild its metadata parameters.
4. Start the Innoslate service.
5. Test the authentication loop by navigating to your Innoslate URL and selecting the SAML login option. If problems persist, check your application log files (innoslate.log or innoslate4-stderr.[YYYY-MM-DD].log.out) for standard cryptographic validation outputs.

Part 5: Troubleshooting & Notes

• Browser Caching After Updates: When logging in to a newly configured or updated version of Innoslate, always clear your browser cache or test via an incognito window first to avoid stale redirection tokens.
• Verify Keystore Integrity: If Tomcat fails to start or throws cryptographic errors, you can verify that the keystore has your single valid private key and matching alias by executing:

keytool -list -v -keystore SPKeystore.jks -storepass <your_password>

Ensure the output explicitly states Certificate chain length: 3 (or 2) and shows Entry type: PrivateKeyEntry.

• Log Analysis: If a user receives a generic error screen during a login loop, inspect the Apache Tomcat logs located in ..\apache-tomcat\logs\catalina.out or the application's root innoslate.log file. Search specifically for strings originating from org.pac4j.saml to find the exact SAML exception.
• Matching Entity IDs: Ensure that the value provided in SP_ENTITY_ID within settings.properties matches character-for-character with what has been configured in your Identity Provider (IdP) control portal. A single mismatched character or missing trailing slash will cause signature validation failure.
• Database & File Backups: Always create a standalone backup of your settings.properties file and your underlying database before modifying core application security parameters.

Still having issues? Reach out to Support.