Skip to main content

Overview

🧠 Auth Security XE​

Auth Security XE (the checkaccessxe flow) extends Auth Security with a frontend collector. On top of the server‑side event that classic Auth Security already sends, XE adds a small JavaScript snippet on your login page that captures device and behavioral signals into an opaque gkas_solution token. That token is sent to GuardianKey together with the login event, producing a richer, more accurate real‑time risk decision (ACCEPT / NOTIFY / BLOCK) and a stronger device identity.

It is the web counterpart of the Mobile SDK: the browser runs the JavaScript collector, while native apps run the SDK — both feed the same checkaccessxe backend call.

🆚 Auth Security vs. Auth Security XE​

Auth Security (classic)Auth Security XE
Signal sourceBackend event only (IP, user, result, User‑Agent…)Backend event + frontend collector (gkas_solution)
Frontend changeNoneAdd a <script> and one init call on the login page
Backend callcheckaccess(...)checkaccessxe(...)
Device identityContextual onlyStronger, device‑bound identity signals
DecisionACCEPT / NOTIFY / BLOCKACCEPT / NOTIFY / BLOCK (same response model)

XE is additive: you keep the same risk model, console and response handling, and gain the frontend signals. If you already integrate classic Auth Security, moving to XE is mostly adding the collector and switching the backend call.

🧩 What you integrate​

PieceWho provides itRole
Collector script (gkas-setup-latest.js)GuardianKey (hosted)Runs on your login page; builds the gkas_solution token on submit.
Your login pageYouLoads the script, builds gkas_config, calls gkas_init(...).
Your backendYouGenerates the per‑load nonce, validates it, calls checkaccessxe with your GuardianKey credentials.

🔐 GuardianKey credentials (key/iv/agentid/…) live only on your backend. The browser never holds them. The page only receives a short‑lived gkas_config (url/salt/once/time) from your own backend.

🔄 Flow​

   ┌──────────────┐  1. GET login page                ┌──────────────┐
   │   Browser    │ ────────────────────────────────▶ │ Your backend │  generate nonce (once),
   │ (login page) │ ◀──────────────────────────────── │              │  build gkas_config
   └──────────────┘   HTML + gkas_config {url,salt,    └──────────────┘
          │                       once,time}
          │ 2. gkas_init(config, form, "username")
          │    collector hooks the form; on submit builds gkas_solution
          ▼
   ┌──────────────┐  3. POST (username, password,     ┌──────────────┐   checkaccessxe   ┌────────────┐
   │   Browser    │ ───── gkas_solution) ───────────▶ │ Your backend │ ────────────────▶ │ GuardianKey│
   │              │ ◀──────────────────────────────── │              │ ◀──────────────── │    XE      │
   └──────────────┘   page reacts to the decision     └──────────────┘   risk decision   └────────────┘
                                                              │
                                                              ├─ ACCEPT → allow login
                                                              ├─ NOTIFY → allow + extra verification
                                                              └─ BLOCK  → deny access
  1. Page load (GET) — your backend generates a one‑time nonce (once), stores it in the session, and embeds a gkas_config (url, salt, once, time) in the page.
  2. Collector init — gkas_init(gkas_config, form, "username") hooks your login form; when the user submits, it builds the gkas_solution and injects it into the form as a hidden field.
  3. Submit (POST) — the form posts username, password and gkas_solution. Your backend validates the nonce, sets the attempt flag, and calls checkaccessxe, forwarding the gkas_solution unchanged. It then acts on the decision.

📦 Collected signals​

The collector gathers a range of device and behavioral information (such as device/identity signals, interaction behavior, environment, geolocation, among others) and packs it into the opaque gkas_solution token.

What matters for integration:

  • Best‑effort. Missing browser capabilities or denied permissions (e.g. geolocation) never break the flow — the corresponding signal is simply omitted.
  • No passwords, no typed content. GuardianKey does not collect credentials.
  • No backend schema work. Your backend forwards the token as‑is; the reference guardiankey.class.php already wraps it for checkaccessxe.

⏭️ Next steps​