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.
composer test before merging to production.
1. Prerequisites
| Requirement | Minimum version |
|---|---|
| PHP | 8.2 |
| Extensions | openssl, dom, libxml |
| Hawiyati IdP | 2.0 |
| Network access | SP → 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)
| Feature | Status | Fallback behavior |
|---|---|---|
| SAML Single Logout (SLO) | Deferred | Local session destroy only; IdP session remains active |
| IdP-initiated login | Deferred | SP-initiated only |
| Encrypted assertions | Deferred | Only signed (unencrypted) assertions accepted |
| AuthnContext class negotiation | Deferred | No RequestedAuthnContext in AuthnRequest |
| Multi-IdP federation per SP | Deferred | Exactly one TrustedIdp per SamlSpConfig |