H· Hawiyati Documentation

PHP Integration Guide

Integrate Hawiyati SAML2 SP SDK with PHP 8.2+ applications. Covers Composer installation, minimum configuration, plain PHP and Laravel adapters, ACS callback, logout, and SP registration.

Known limitation: PHP 8.2+ and Composer were not installed in the development environment during v1.0.0. All code has been reviewed but PHPUnit tests were not executed locally. Run composer test before merging to production.

1. Prerequisites

RequirementMinimum version
PHP8.2
Extensionsopenssl, dom, libxml
Hawiyati IdP2.0
Network accessSP → IdP on port 443

For multi-instance or production deployments, the Predis library is required: composer require predis/predis

2. Add the dependency

composer require hawiyati/saml-sp:^1.0.0

3. Minimum configuration

Create a config.php that is not tracked in source control. Load all sensitive values from environment variables.

<?php
declare(strict_types=1);

use Hawiyati\Saml\Sp\SamlSpConfig;
use Hawiyati\Saml\Sp\TrustedIdp;

$trustedIdp = new TrustedIdp(
    entityId: 'https://idp.hawiyati.org',
    ssoUrl: 'https://idp.hawiyati.org/saml2/sso/redirect',
    signingCertPem: file_get_contents(getenv('IDP_CERT_PATH'))
);

$config = new SamlSpConfig(
    entityId: 'https://app.example.com/saml/metadata',
    acsUrl: 'https://app.example.com/saml/acs',
    trustedIdp: $trustedIdp,
    pendingRequestStore: new RedisPendingRequestStore($redis),
    replayStore: new RedisReplayStore($redis),
    clockSkewSeconds: 60
);

4. Protect a route

In plain PHP, check for the authenticated principal at the top of each protected page:

<?php
// protected.php
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/config.php';

session_start();

if (empty($_SESSION['saml_principal'])) {
    // Redirect to IdP
    $builder = new AuthnRequestBuilder($config);
    [$url, $pendingId] = $builder->buildRedirectUrl();
    $_SESSION['saml_pending'] = $pendingId;
    header('Location: ' . $url, true, 302);
    exit;
}

5. Handle the ACS callback

In acs.php, validate the SAML response and store the principal. Session regeneration must occur before writing to $_SESSION:

<?php
// acs.php
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/config.php';

session_start();

$validator = new ResponseValidator($config);
$principal = $validator->validate(
    samlResponse: $_POST['SAMLResponse'] ?? '',
    pendingId:    $_SESSION['saml_pending'] ?? ''
);

// MUST call before writing session data
session_regenerate_id(true);

$_SESSION['saml_principal'] = $principal;
unset($_SESSION['saml_pending']);

$relayState = $_POST['RelayState'] ?? '/';
header('Location: ' . $relayState, true, 302);
exit;

6. Display the current user

<?php
// me.php
session_start();
$principal = $_SESSION['saml_principal'];
echo '<p>NameID: ' . htmlspecialchars($principal->nameId) . '</p>';
foreach ($principal->attributes as $name => $values) {
    echo '<p>' . htmlspecialchars($name) . ': ' . htmlspecialchars(implode(', ', $values)) . '</p>';
}

7. Local logout

SAML Single Logout (SLO) is not implemented in v1.0.0.

<?php
// logout.php
session_start();
$_SESSION = [];
session_destroy();

// Expire the session cookie explicitly
setcookie(session_name(), '', [
    'expires'  => time() - 3600,
    'path'     => '/',
    'secure'   => true,
    'httponly' => true,
    'samesite' => 'Lax',
]);

header('Location: /', true, 302);
exit;

8. Local user mapping

Implement LocalAccountResolverInterface for JIT provisioning. The default PassThroughLocalAccountResolver accepts every authenticated principal.

class AppResolver implements LocalAccountResolverInterface {
    public function resolve(SamlPrincipal $principal): mixed {
        $user = $this->users->findByNameId($principal->nameId);
        if (!$user) {
            $user = $this->users->create($principal->nameId);
        }
        if (!$user->isActive) {
            throw new SamlValidationException('Account disabled');
        }
        return $user;
    }
}

9. SP registration in Hawiyati

<?php
// metadata.php
header('Content-Type: application/xml');
$generator = new MetadataGenerator($config);
echo $generator->generate();

After registration, download the IdP signing certificate from Admin → IdP → Certificates → Download PEM and reference it via IDP_CERT_PATH.

Laravel adapter

Add the service provider in config/app.php:

'providers' => [
    \Hawiyati\Saml\Sp\Laravel\SamlServiceProvider::class,
],

Publish the config: php artisan vendor:publish --tag=saml-config

Register the middleware in app/Http/Kernel.php:

protected $routeMiddleware = [
    'saml' => \Hawiyati\Saml\Sp\Laravel\SamlMiddleware::class,
];

10. Deferred extensions (not in v1.0.0)

FeatureStatusFallback behavior
SAML Single Logout (SLO)DeferredLocal session destroy only; IdP session remains active
IdP-initiated loginDeferredSP-initiated only
Encrypted assertionsDeferredOnly signed (unencrypted) assertions accepted
AuthnContext class negotiationDeferredNo RequestedAuthnContext in AuthnRequest
Multi-IdP federation per SPDeferredExactly one TrustedIdp per SamlSpConfig