Operations Guide
Production deployment topics: TLS trust, reverse proxies, multi-instance state, restart behavior, certificate rotation, IdP outage behavior, and offline installation.
1. Private CA trust
Hawiyati IdP deployments may present TLS certificates issued by a private or enterprise CA. The SP application must trust this CA for outbound HTTPS connections.
Java
keytool -importcert \
-alias hawiyati-idp-ca \
-cacerts \
-file /path/to/private-ca.crt \
-storepass changeit \
-noprompt
Or configure a custom trust store in application.yml:
server:
ssl:
trust-store: classpath:truststore.jks
trust-store-password: ${SSL_TRUSTSTORE_PASSWORD}
.NET
# Linux
cp private-ca.crt /usr/local/share/ca-certificates/hawiyati-ca.crt
update-ca-certificates
# Windows
certutil -addstore Root private-ca.crt
PHP
// Add to your Predis client constructor or curl options
$redis = new Predis\Client([
'scheme' => 'tls',
'ssl' => ['cafile' => '/path/to/private-ca.crt', 'verify_peer' => true],
]);
2. Reverse proxy headers
When the SP is behind a reverse proxy (nginx, AWS ALB, etc.), the SP must trust the proxy's forwarded headers to generate correct ACS URLs and to validate the Destination attribute in SAML responses.
Java
server:
forward-headers-strategy: framework # Trust X-Forwarded-* headers from the reverse proxy
.NET
builder.Services.Configure<ForwardedHeadersOptions>(opts =>
{
opts.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
opts.KnownNetworks.Clear();
opts.KnownProxies.Clear();
});
// ...
app.UseForwardedHeaders();
3. Multi-instance shared state
In-memory pending-request and replay stores are not shared across process instances. For multi-instance deployments, use the Redis adapters:
Java
hawiyati:
saml:
sp:
redis:
host: redis.internal
port: 6379
password: ${REDIS_PASSWORD}
tls: true
pending-request-ttl-seconds: 900 # 15 minutes
replay-ttl-seconds: 86400 # 24 hours
.NET
var redis = ConnectionMultiplexer.Connect("redis.internal:6379,ssl=true,password=${REDIS_PASSWORD}");
var samlConfig = SamlSpConfig.Create()
// ...
.WithPendingRequestStore(new RedisPendingRequestStore(redis, ttlSeconds: 900))
.WithReplayStore(new RedisReplayStore(redis, ttlSeconds: 86400))
.Build();
4. Restart behavior
In-memory stores: All pending authentication requests and replay detection entries are lost on restart. Any user mid-login (between redirect to IdP and ACS callback) will receive an error. Use Redis adapters in production to survive restarts.
Redis stores: State survives restarts. Pending request entries expire per their TTL. Replay entries expire per their TTL (default 24 hours).
5. Certificate expiry and rollover
When the IdP rotates its signing certificate:
- Hawiyati Admin Console will publish the new certificate in advance (typically 30 days before the old one expires).
- Download the new certificate from Admin → IdP → Certificates → Download PEM.
- Add the new certificate to
idp.signing-cert-paths(Java) alongside the old one — the SDK accepts any certificate in the list. This enables zero-downtime rotation. - After the old certificate expires and all SPs have been updated, remove the old certificate from the list.
6. Controlled IdP outage behavior
During an IdP outage, new SP-initiated SSO attempts will fail because the browser cannot reach the IdP SSO URL. Users who are already authenticated (session is valid) are not affected — the SP does not need to contact the IdP after a successful assertion is processed.
Recommendations:
- Set an appropriate session TTL (e.g., 8 hours for a business day) to minimize re-authentication frequency.
- Implement a user-friendly error page when the IdP redirect times out.
- Monitor IdP availability separately from SP availability.
7. Offline mirror installation
For air-gapped or offline environments, mirror the Maven artifacts to a local Nexus/Artifactory instance:
# Download to local Maven cache
mvn dependency:get -Dartifact=org.hawiyati:saml-sp-spring-boot-starter:1.0.0
# Deploy to internal mirror
mvn deploy:deploy-file \
-DgroupId=org.hawiyati \
-DartifactId=saml-sp-spring-boot-starter \
-Dversion=1.0.0 \
-Dpackaging=jar \
-Dfile=saml-sp-spring-boot-starter-1.0.0.jar \
-Durl=https://nexus.internal/repository/hawiyati/
For .NET: dotnet nuget push Hawiyati.Saml.Sp.1.0.0.nupkg --source https://nexus.internal/v3/index.json
For PHP: set up a Satis private Composer repository and add it to composer.json repositories.