Trusted Devices

Overview

Trusted Devices allows users to skip MFA on subsequent logins from a browser they have explicitly trusted. This balances security with convenience: the user still authenticates with their password every time, but the second factor is only required on new or untrusted browsers.

This feature is disabled by default and is activated by setting trusted_device_duration_days > 0 in Settings → MFA.

---

How it works

1. The user logs in normally (password + MFA).
2. On success, JustIAM returns a short-lived trust_device_token alongside the session JWT.
3. If the user chooses to trust the device, the frontend exchanges the token via POST /api/v1/me/devices, optionally supplying a friendly name.
4. JustIAM upgrades the trust record to the full configured TTL and writes a long-lived idp_device httpOnly cookie (Secure, SameSite=Strict) to the browser.
5. On the next login from the same browser, the idp_device cookie is sent automatically. JustIAM validates it against the stored token hash and skips the MFA step.
6. When the trust period expires (or the device is revoked), the cookie becomes invalid and MFA is required again at the next login.

---

Configuration

Setting	Description
trusted_device_duration_days	Number of days a device remains trusted. Set to 0 to disable the feature entirely (default).

Configure in Settings → MFA → Trusted Device Duration (days) or via the API / Terraform provider.

---

Managing trusted devices

Users can view and revoke their trusted devices at any time.

UI: Profile → Trusted Devices

API:

GET /api/v1/me/devices
Authorization: Bearer <jwt>

Response:

[
  {
    "id": "<uuid>",
    "name": "Work laptop",
    "last_seen_at": "2025-03-01T10:00:00Z",
    "expires_at": "2025-05-30T10:00:00Z"
  }
]

To revoke a device:

DELETE /api/v1/me/devices/{id}
Authorization: Bearer <jwt>

---

Confirming trust at login

After a successful MFA login, the login response includes a trust_device_token:

{
  "token": "<session-jwt>",
  "trust_device_token": "<short-lived-trust-token>"
}

To trust the current device, POST the token:

POST /api/v1/me/devices
Authorization: Bearer <session-jwt>
Content-Type: application/json

{
  "token": "<trust-device-token>",
  "name": "Work laptop"
}

The name field is optional; if omitted, JustIAM uses a default name.

On success (201 Created) the response sets an idp_device httpOnly cookie that the browser will automatically send on subsequent login requests, allowing JustIAM to skip MFA for this device.

---

Security notes

• The trust_device_token returned at login is short-lived (10 minutes) and single-use — it cannot be replayed once confirmed.
• After POST /me/devices, a long-lived idp_device cookie (HttpOnly, Secure, SameSite=Strict) is written to the browser for the configured duration. The cookie value is a random token; only its SHA-256 hash is stored in the database.
• Trusted device records are tied to the authenticated user; a device trusted by one user does not affect other users.
• Revoking a trusted device in the UI removes the DB record immediately. The browser cookie becomes invalid at the next login attempt.
• Administrators cannot remove trust records on behalf of users, but users can always revoke them in their profile.