SurePassID Identity Provider

SAML2 web.config Settings & Caching Reference

This document describes the SAML2‑specific appSettings keys used by the SurePassID SAML2 IdP (SurePassIdp/web.config) and explains how the SAML request‑ID and session cache works.

1. SAML2‑Specific appSettings

All keys live under <appSettings> in SurePassIdp/web.config. Sensitive keys (Saml.PersistentNameIdSalt, DB credentials, mail password, etc.) should be encrypted following Documentation/Setup/WebConfig-Encryption-Guide.md.

1.1 IdP Identity & URLs

1.2 NameID Generation

Note: In the shipped web.config this key is deliberately disabled by prefixing the key name with IGNORE. (IGNORE.Saml.PersistentNameIdSalt). Remove the IGNORE. prefix to activate a custom salt; otherwise the fallback chain applies.

1.3 Email Templates (password / account recovery)

1.4 Diagnostic Tracing

Security: Leave Saml2.TraceSensitiveData=false in production so logs cannot leak tokens or PII.

2. SAML Cache Settings

The IdP uses a cache for two purposes:

1. Replay‑attack prevention — tracking SAML request IDs that have already been seen.
2. Single Logout (SLO) support — tracking active SAML sessions so they can be located and terminated (per user, per SP, or per session index).

2.1 Configuration Keys

Example:

<appSettings>
  <!-- Cache provider: "InMemory" (default) or "SqlServer" -->
  <add key="SamlCache.Provider" value="InMemory" />

  <!-- Optional: Request ID expiration in minutes (default: 5) -->
  <add key="SamlCache.RequestIdExpirationMinutes" value="5" />

  <!-- Optional: Session expiration in hours (default: 8) -->
  <add key="SamlCache.SessionExpirationHours" value="8" />
</appSettings>

3. How Caching Works

3.1 Provider Selection (SamlSessionCacheProvider)

• SamlSessionCacheProvider.Instance is a thread‑safe, lazily initialized singleton (double‑checked locking).
• On first access it reads SamlCache.Provider plus the two expiration keys via GetConfigInt(...) (values must be positive integers; otherwise the default is used).
• Behavior by provider value:
  • SqlServer → constructs SqlServerSamlSessionCache(requestIdExpMinutes, sessionExpHours) (SurePassClassLib/Utility/SqlServerSamlSessionCache.cs), a durable, cross‑node cache backed by the schema in Documentation/Development/Database/SamlSessionCache_Schema.sql.
  • Anything else / empty → uses the in‑memory cache. The provider sets the static SamlRequestIdCache.CacheExpiration and SamlRequestIdCache.SessionExpiration from config, then returns an InMemorySamlSessionCacheWrapper that adapts the static SamlRequestIdCache to the ISamlSessionCache interface.
• SamlSessionCacheProvider.CurrentProviderName returns the effective provider name.
• Reset() and SetInstance(...) exist primarily for testing.

3.2 In‑Memory Cache (SamlRequestIdCache)

Captures these metrics.

Tunable expirations (set from config by the provider):

• CacheExpiration — request‑ID retention (default 5 min).
• SessionExpiration — session retention (default 8 hours).

3.3 SQL Server Cache (SqlServerSamlSessionCache)

• Durable, shared across web‑farm nodes (the in‑memory cache is per‑process only).
• Uses the same requestIdExpirationMinutes / sessionExpirationHours values, passed as SQL parameters (@ExpirationMinutes, @ExpirationHours) so expiration is enforced in the database.
• Requires the schema/table from Documentation/Development/Database/SamlSessionCache_Schema.sql (see Documentation/Setup/Saml-Session-Cache-Setup.md for setup steps).

4. Choosing a Provider

Important: With InMemory, request‑ID and session state are not shared between nodes and are lost on app‑pool recycle. For any multi‑node or high‑availability deployment, use SqlServer.

5. Quick Reference — All SAML2 Keys

<!-- IdP identity & URLs -->
<add key="Server.AppId" value="https://saml2.surepassid.com" />
<add key="System.IdpRootURL" value="https://saml2.surepassid.com/" />
<add key="System.Login2FAMethods" value="SENDEMAIL,SENDSMS,SENDVOICE,PUSHAPP" />

<!-- NameID generation (store encrypted; remove IGNORE. prefix to activate) -->
<add key="Saml.PersistentNameIdSalt" value="your-secret-salt" />

<!-- Email templates -->
<add key="Saml2.AccountLoginInfoTemplateName" value="ServicePass_AccountLoginInfo" />
<add key="Saml2.PasswordChangedTemplateName" value="ServicePass_PasswordChanged" />

<!-- Diagnostic tracing -->
<add key="Server.Trace" value="1" />
<add key="Server.TracePath" value="C:\temp" />
<add key="Saml2.TraceSensitiveData" value="false" />

<!-- SAML cache -->
<add key="SamlCache.Provider" value="InMemory" />
<add key="SamlCache.RequestIdExpirationMinutes" value="5" />
<add key="SamlCache.SessionExpirationHours" value="8" />