H· Hawiyati Documentation

Configuration Reference

Authoritative reference for all configuration keys across the three SDK implementations. For integration walkthroughs see the per-platform integration guides.

1. Java/Spring Boot (hawiyati.saml.sp.*)

Bind prefix: hawiyati.saml.sp — Source: SamlSpProperties.java

Top-level keys

PropertyTypeDefaultRequiredDescription
entity-idString—YesSP entity ID URI. Must match the value registered in Hawiyati.
acs-urlString—YesAssertion Consumer Service URL. Must start with https://.
clock-skew-secondsint60NoClock-skew tolerance in seconds. Maximum: 300.
protected-pathsList<String>[] (all)NoURL path prefixes to protect. Empty = protect all paths.

hawiyati.saml.sp.idp.* keys

PropertyTypeDefaultRequiredDescription
idp.entity-idString—YesIdP entity ID URI.
idp.sso-urlString—YesIdP Single Sign-On URL for HTTP-Redirect binding.
idp.signing-cert-pathsList<String>[]YesPaths to PEM-encoded X.509 certificates used by the IdP to sign assertions. At least one required.
idp.metadata-urlString—NoReserved. 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.

2. .NET/ASP.NET Core options

Source: SamlAuthenticationOptions.cs, SamlSpConfig.cs

SamlAuthenticationOptions properties

PropertyTypeDefaultDescription
ConfigSamlSpConfig(required)Core SAML SP configuration.
LocalAccountResolverILocalAccountResolver?nullOptional hook after assertion validation. null = pass-through.
CorrelationCookiePrefixstring"_saml_state_"Prefix for the per-request correlation state cookie.
CorrelationCookieMaxAgeMinutesint15Lifetime of the correlation cookie in minutes.
AuthCookiePrefixstring"_saml_auth_"Prefix for the signed-in auth-ticket cookie.

SamlSpConfig builder methods

MethodTypeDefaultRequiredDescription
WithEntityId(string)string—YesSP entity ID URI.
WithAcsUrl(string)string—YesACS URL. Must start with https://.
WithTrustedIdp(TrustedIdp)TrustedIdp—YesTrusted IdP definition.
WithPendingRequestStore——YesStore for pending authentication requests.
WithReplayStore——YesStore for assertion replay detection.
WithClockSkewSeconds(int)int60NoClock-skew tolerance. Range: 0–300.
WithMaxMessageBytes(long)long524288 (512 KB)NoMaximum SAML response body size in bytes.
WithSpSigningKey(RSA)RSAnullNoSP private key for signing AuthnRequest. Load from secrets manager only.

3. PHP (SamlSpConfig constructor)

ParameterTypeDefaultRequiredDescription
entityIdstring—YesSP entity ID URI.
acsUrlstring—YesACS URL. Must start with https://.
trustedIdpTrustedIdp—YesTrusted IdP definition.
pendingRequestStorePendingRequestStoreInterface—YesStore for pending authentication requests.
replayStoreReplayStoreInterface—YesStore for assertion replay detection.
clockSkewSecondsint120NoClock-skew tolerance. Maximum: 300.
maxResponseBytesint524288NoMaximum 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.