SSO Platform Documentation
Version 1.0 — Last updated August 2026
Overview
SSO Platform is a centralised Single Sign-On platform. It lets users register once and access multiple systems using a single identity. Authentication is handled via email OTP — no passwords to store or manage.
Integration is simple: register your system in the admin panel, receive a secret key, and add a single PHP callback file to your application.
Quick Start
Get a system integrated in 3 steps:
- Step 1 — Admin registers your system at
/admin/systems.phpand sets the Redirect URL. - Step 2 — Download the auto-generated
.phpcallback file from the Guide column. - Step 3 — Place the callback file at your Redirect URL path. Done.
User Registration
New users register at /register.php. They provide name, email, phone, and optionally upload a face photo and staff card for verification.
Accounts are in pending status until an admin approves them. Rejected accounts cannot sign in.
Email domain restriction can be configured in admin Settings to only allow specific company domains (e.g. company.com.my).
Register a System
In the admin panel, go to Systems → Register New System and fill in:
| Field | Required | Description |
|---|---|---|
| System Name | Yes | Display name shown on user dashboard |
| Base URL | Yes | Root URL of your application (e.g. https://app.example.com) |
| Redirect URL | Yes | Full URL of your SSO callback file (e.g. https://app.example.com/sso-callback.php) |
| System Logo | No | JPG/PNG/SVG shown on dashboard card |
| Description | No | Short description shown on dashboard |
On save, a unique secret key is generated. Keep this private — it is used to verify tokens.
Download Integration Guide
From the Systems table, the Guide column has two download buttons per system:
.json— JSON file with credentials, verify URL, and flow documentation.php— Ready-to-use PHP callback file with secret key pre-filled
The .php file is named sso-callback-{slug}.php. Rename and place it at your Redirect URL path.
Callback File
When SSO redirects a user to your app, it appends ?sso_token=TOKEN to your Redirect URL. Your callback file must verify this token before granting access.
<?php
// sso-callback.php
$sso_token = $_GET['sso_token'] ?? '';
$secret_key = 'YOUR_SECRET_KEY';
$verify_url = 'https://www.sso.krh.com.my/verify-token.php';
if (!$sso_token) exit('No token.');
$response = file_get_contents(
$verify_url . '?token=' . urlencode($sso_token)
. '&secret=' . urlencode($secret_key)
);
$data = json_decode($response, true);
if (!$data || !$data['ok'])
exit('SSO failed: ' . ($data['error'] ?? 'Unknown'));
$user = $data['user'];
session_start();
$_SESSION['user_id'] = $user['id'];
$_SESSION['user_name'] = $user['name'];
$_SESSION['user_email'] = $user['email'];
header('Location: /dashboard');
exit;
Verify Token API
Your callback calls this endpoint to validate an SSO token.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| token | Yes | The sso_token value from the redirect URL |
| secret | Yes | Your system's secret key from the admin panel |
Response Format
The endpoint always returns JSON.
Success
{
"ok": true,
"user": {
"id": 1,
"name": "Ahmad Ali",
"email": "ali@example.com"
}
}Failure
{
"ok": false,
"error": "Invalid or already used token"
}Error Codes
| HTTP | Error Message | Cause |
|---|---|---|
| 400 | Missing token or secret | Required parameters not provided |
| 401 | Invalid or already used token | Token does not exist or was already consumed |
| 401 | Token has expired | Token older than 5 minutes |
| 403 | Invalid secret key | Secret does not match the system that owns the token |
| 403 | User account is not active | User was rejected or deactivated after token was issued |
| 405 | Method not allowed | Only GET requests are accepted |
User Management
Access at /admin/users.php. Admin can:
- View all registered users with status (pending / approved / rejected)
- Approve or reject pending registrations
- View uploaded face photo and staff card
- Pending count shown as badge in sidebar
System Management
Access at /admin/systems.php. Admin can:
- Register, activate, deactivate, and delete systems
- View live network status per system
- Copy secret key and download integration guide
Access Control
Each system can be set to All Approved Users or Specific Users. Click the Access button in the systems table to manage.
Settings
Landing Page
- Site Name — shown in navbar and browser title
- Navbar Logo — replaces default icon
- Hero Title & Subtitle — main heading and description on landing page
SMTP
Configure SMTP for OTP email delivery. TLS (port 587) and SSL (port 465) supported. Use Test Connection to verify before saving.
Allowed Domains
Comma-separated email domains allowed to register. Leave blank to allow all.
Security Model
- No passwords stored — OTP-only auth eliminates credential theft risk
- CSRF protection — all POST forms validated with per-session token
- Token one-time use — SSO tokens consumed immediately on verification
- Secret key binding — tokens can only be verified by the system that owns them
- Secure sessions — httponly cookies, strict mode enabled
- Parameterised queries — all DB operations use prepared statements
Token Lifecycle
- Generated — secure random token created when user clicks Launch
- Short-lived — valid for 5 minutes from generation
- Single use — consumed on first successful verification, cannot be replayed
- System-bound — wrong secret key returns an error
- User-bound — impersonation not possible
ok === true before starting a session. Never grant access on a failed or missing response.