Authoritative reference for all configuration keys across the three SDK implementations. For integration walkthroughs see the per-platform integration guides.
Developers · Current · 10 November 2026 · SDK 1.0.0
SP entity ID URI. Must match the value registered in Hawiyati.
acs-url
String
—
Yes
Assertion Consumer Service URL. Must start with https://.
clock-skew-seconds
int
60
No
Clock-skew tolerance in seconds. Maximum: 300.
protected-paths
List<String>
[] (all)
No
URL path prefixes to protect. Empty = protect all paths.
hawiyati.saml.sp.idp.* keys
Property
Type
Default
Required
Description
idp.entity-id
String
—
Yes
IdP entity ID URI.
idp.sso-url
String
—
Yes
IdP Single Sign-On URL for HTTP-Redirect binding.
idp.signing-cert-paths
List<String>
[]
Yes
Paths to PEM-encoded X.509 certificates used by the IdP to sign assertions. At least one required.
idp.metadata-url
String
—
No
Reserved. IdP metadata URL. Not used in v1.0.0.
Security note:signing-cert-paths must reference files outside of your SCM-tracked source tree. Use volume mounts, secrets managers, or classpath resources injected at build time from a secure pipeline. Never commit certificate content to a repository.
Optional hook after assertion validation. null = pass-through.
CorrelationCookiePrefix
string
"_saml_state_"
Prefix for the per-request correlation state cookie.
CorrelationCookieMaxAgeMinutes
int
15
Lifetime of the correlation cookie in minutes.
AuthCookiePrefix
string
"_saml_auth_"
Prefix for the signed-in auth-ticket cookie.
SamlSpConfig builder methods
Method
Type
Default
Required
Description
WithEntityId(string)
string
—
Yes
SP entity ID URI.
WithAcsUrl(string)
string
—
Yes
ACS URL. Must start with https://.
WithTrustedIdp(TrustedIdp)
TrustedIdp
—
Yes
Trusted IdP definition.
WithPendingRequestStore
—
—
Yes
Store for pending authentication requests.
WithReplayStore
—
—
Yes
Store for assertion replay detection.
WithClockSkewSeconds(int)
int
60
No
Clock-skew tolerance. Range: 0–300.
WithMaxMessageBytes(long)
long
524288 (512 KB)
No
Maximum SAML response body size in bytes.
WithSpSigningKey(RSA)
RSA
null
No
SP private key for signing AuthnRequest. Load from secrets manager only.
3. PHP (SamlSpConfig constructor)
Parameter
Type
Default
Required
Description
entityId
string
—
Yes
SP entity ID URI.
acsUrl
string
—
Yes
ACS URL. Must start with https://.
trustedIdp
TrustedIdp
—
Yes
Trusted IdP definition.
pendingRequestStore
PendingRequestStoreInterface
—
Yes
Store for pending authentication requests.
replayStore
ReplayStoreInterface
—
Yes
Store for assertion replay detection.
clockSkewSeconds
int
120
No
Clock-skew tolerance. Maximum: 300.
maxResponseBytes
int
524288
No
Maximum SAML response byte size.
4. Cross-platform security notes
IdP signing certificates must be stored outside SCM-tracked source trees. Use secrets managers, volume mounts, or build-time injection from a secure pipeline.
SP private keys (optional, for AuthnRequest signing) must never appear in configuration files or environment variables in plaintext. Use HSMs, cloud KMS, or OS-level key stores.
ACS URLs must start with https://. The SDK rejects configurations with http:// ACS URLs.
Clock skew should not be set above 300 seconds. Excessive tolerance weakens replay protection.
Protected paths: when using protected-paths (Java) or the equivalent, ensure the ACS URL and metadata URL are explicitly excluded from protection to avoid redirect loops.
Redis TLS: when using Redis adapters in production, configure Redis with TLS and require client certificate authentication. See the Operations Guide.