Web Integration

🔗 Web Integration

This guide shows how to add the Auth Security XE collector to your login page and wire the checkaccessxe call on the backend. The examples use PHP and the reference guardiankey.class.php, but the contract is the same in any language.

Requirements: a server‑rendered (or server‑reachable) login page where you can inject a per‑load gkas_config, and a backend endpoint that processes the login POST.

---

1. Generate the config on page load (GET)

On each page load, generate a one‑time nonce (once), keep it in the session, and build the gkas_config the collector needs. url, salt, once and time bind the attempt together.

<?php
session_start();

// Fresh nonce per page load, stored in session for the POST to verify.
if ($_SERVER['REQUEST_METHOD'] === 'GET' || empty($_SESSION['gkas_nonce'])) {
    $_SESSION['gkas_nonce']      = bin2hex(random_bytes(16));
    $_SESSION['gkas_nonce_time'] = time();
}

$origin = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off' ? 'https' : 'http')
        . '://' . $_SERVER['HTTP_HOST'];

$gkas_config = [
    'url'  => $origin . $_SERVER['PHP_SELF'],
    'salt' => 'demo_salt',
    'once' => $_SESSION['gkas_nonce'],
    'time' => (string) time(),
];
?>

---

2. Load the collector and initialize it

Include the hosted GuardianKey script and call gkas_init(...) with the config, your form element and the name of the username field. The collector hooks the form; on submit it builds the gkas_solution and injects it as a hidden field before the POST goes out.

<form id="form" method="POST" action="">
  <input id="username" name="username" type="text" autocomplete="username">
  <input id="password" name="password" type="password" autocomplete="current-password">
  <input type="submit" value="Sign in">
</form>

<script src="https://guardiankey.io/js/gkas-setup-latest.js?v=1"></script>
<script>
  const gkas_config = <?= json_encode($gkas_config, JSON_UNESCAPED_SLASHES) ?>;
  // gkas_init(config, formElement, usernameFieldName, debug?)
  gkas_init(gkas_config, document.getElementById('form'), "username", false);
</script>

That is the entire frontend change: one <script> include and one gkas_init call. Everything the collector does is encapsulated; you never read or build the gkas_solution yourself.

💡 Pass true as the last argument to gkas_init to enable a debug panel during development.

---

3. Handle the login POST and call checkaccessxe

On submit, your backend receives username, password and gkas_solution. Validate the nonce, authenticate the user as usual, set the attempt flag ("0" when the password is correct, "1" otherwise), and call checkaccessxe with the same url/salt/once/time you generated on the GET — forwarding the gkas_solution unchanged.

<?php
require_once 'guardiankey.class.php';

$GKconfig = [
    'agentid'     => 'sdk',
    'key'         => 'BASE64_KEY',          // from your secure config — never in the page
    'iv'          => 'BASE64_IV',
    'service'     => 'TestServicePHP',
    'orgid'       => 'YOUR_ORG_ID',
    'authgroupid' => 'YOUR_AUTHGROUP_ID',
    'api_key'     => '',
    'reverse'     => 'True',
];
$GKconfig['api_key'] = hash('sha256', $GKconfig['key'] . $GKconfig['iv']);

$gk = new guardiankey($GKconfig);

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    // 1) Validate / consume the nonce (exists, not expired, not reused).
    //    (compare $_SESSION['gkas_nonce'] against $gkas_config['once'])

    // 2) Authenticate the user with your own system as usual.
    $passwordOk = check_password($_POST['username'], $_POST['password']);
    $attempt    = $passwordOk ? "0" : "1";

    // 3) Call XE with the same challenge inputs + the opaque solution.
    $ret = $gk->checkaccessxe(
        $_POST['username'],
        "",                       // useremail (optional)
        $gkas_config['url'],
        $gkas_config['salt'],
        $gkas_config['once'],
        $gkas_config['time'],
        $_POST['gkas_solution'],  // forward unchanged
        $attempt
    );

    $result = json_decode($ret);

    // 4) Act on the decision (see step 4).
}

---

4. Act on the decision

checkaccessxe returns the same response model as classic Auth Security. The response field drives your action:

response	Meaning	Suggested action
ACCEPT	Normal access	Allow login.
NOTIFY	Suspicious behavior	Allow, but consider extra verification (e.g. 2FA) and/or notify the user.
BLOCK	High risk	Deny access — even if the password was correct.

if (isset($result->response) && $result->response === 'BLOCK') {
    // Generic message to avoid information leakage.
    http_response_code(403);
    echo "Invalid username or password.";
} else {
    // ACCEPT (or NOTIFY with your own extra step) → proceed with the session.
    start_user_session($_POST['username']);
}

---

✅ Checklist

• GET builds a fresh once (nonce) per load and stores it in the session.
• Login page loads gkas-setup-latest.js and calls gkas_init(config, form, "username").
• POST validates/consumes the nonce.
• Attempt flag set: "0" correct password, "1" otherwise.
• checkaccessxe(...) called with the same url/salt/once/time and the unchanged gkas_solution.
• Decision handled: BLOCK denies; ACCEPT/NOTIFY proceed (with optional step‑up).

See the Backend & API reference for the full checkaccessxe signature, gkas_config fields and response shape.