H· Hawiyati Documentation

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:

  1. Hawiyati Admin Console will publish the new certificate in advance (typically 30 days before the old one expires).
  2. Download the new certificate from Admin → IdP → Certificates → Download PEM.
  3. 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.
  4. 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.