Skip to main content

FAQ & Troubleshooting

Getting Started​

How do I begin a SAML integration project?​

You will be assigned a Candescent Integration Project Manager via Marketplace. Your PM is your primary contact for the duration of the certification of your integration.

What information do I need to provide?​

Complete the Setup Checklist with:

  • Partner and contact information
  • Application details
  • Assertion Consumer Service URL(s)
  • X509 certificates for each environment
  • Service Provider Entity ID

What is the typical integration process?​

  1. Initialization - Candescent PM provides relevant documentation and answers initial questions. Partner completes and returns the Setup Checklist

  2. Environment Setup - Once the partner provides a completed Setup Checklist, the Candescent team installs the connection in the internal QA site for initial testing

  3. Initial QA Validation - Testing using Candescent's standard test environment

  4. Configuration - Setup of trust, security, certificates, and endpoints

  5. Integration Testing - Testing in FI environments

  6. Certification and Go-Live - Final certification and production deployment

Technical Basics​

What SAML profile does Candescent support?​

Candescent Digital Banking supports SAML 2.0 IdP-Initiated Web Browser SSO with POST binding. The assertion is both signed and encrypted.

What role does Candescent play in the SAML flow?​

Candescent Digital Banking acts as the Identity Provider (IdP). Your application acts as the Service Provider (SP).

What attributes are included in the SAML assertion?​

AttributeDescription
FI_IDFinancial Institution identifier
USER_IDUser identifier on the FI's host system
USER_ACCOUNTSXML document with account list and nicknames
KEEP_ALIVE_URLURL to maintain online banking session
XML_DATAOptional custom data (structure agreed during development)
SESSION_IDOptional online banking session ID

What certificates do I need?​

  • Your certificate (SP): X509 certificate in PEM format for encrypting assertions. Production requires a certificate from a trusted CA; test environments can use self-signed certificates

  • Candescent certificate (IdP): Provided by your PM for verifying SAML assertion signatures

What security algorithms are supported?​

TypeSupportedRecommended
Digital SignatureRSA SHA1, SHA256, SHA384, SHA512RSA SHA256
EncryptionAES-128, AES-256, Triple DESAES-128

Common Issues & Solutions​

SAML assertion validation fails​

Possible causes:

  • System clock is not synchronized - ensure NTP is configured
  • Wrong certificate being used - verify you have the correct IdP certificate for the environment (test vs. production)
  • Certificate has expired - check certificate validity dates

Session times out while user is in third-party app​

Solution: Implement the keep-alive mechanism using the KEEP_ALIVE_URL attribute:

<script>
(function(d) {
  var iframe = d.body.appendChild(d.createElement('iframe')),
      doc = iframe.contentWindow.document;
  iframe.style.cssText = "display: none;";
  doc.open().write('<body onload="setTimeout(function() { window.location=\"' + KEEP_ALIVE_URL + '\" }, 0);">');
  doc.close();
})(document);
</script>

Unable to decrypt SAML assertion​

Possible causes:

  • Wrong private key being used
  • Encryption algorithm mismatch - verify you support the encryption algorithm Candescent is using
  • Certificate mismatch between what was provided and what's configured

Content not displaying correctly in mobile WebView​

Solution: Ensure your application is compatible with native device WebViews (iOS Safari WebView and Android WebView). Reference Apple and Google documentation for WebView compatibility requirements.

Multi-FI setup not working for new institutions​

Cause: For multi-FI vendors, the endpoint URL and certificate must be static across all implementations.

Solution: Use the same Assertion Consumer Service URL and encryption certificate for all FI integrations.

Session Management​

How long does the online banking session last?​

Session timeout is managed by Candescent Digital Banking. Use the KEEP_ALIVE_URL to prevent session timeout while the user is active in your application.

Can I track user activity with the online banking session?​

Yes, request the optional SESSION_ID attribute. This ID can be used to correlate activity in your application with activity recorded in online banking.

Tips for Success​

  • Synchronize system time: Use NTP to ensure accurate timestamps for SAML validation

  • Store certificates securely: Never expose private keys in code or logs

  • Use HTTPS everywhere: All endpoints must use TLS 1.2+

  • Test thoroughly: Validate in QA before moving to production environments

  • Implement keep-alive: Prevent session timeouts during user activity

  • Plan for certificate rotation: Have a process in place to update certificates before expiration

SAML Implementation Libraries​

Consider using established libraries rather than building from scratch:

LanguageLibrary
JavaOpenSAML
CZXID
PHPSimpleSAMLphp
.NETMicrosoft ADFS, Component Space
Pythonpython-saml (OneLogin)

Contact & Support​

For questions or support, reach out to your assigned Candescent Integration PM via Marketplace. Your PM will provide all necessary materials, guidance, and troubleshooting assistance.

References​