Search by

ids / login

ezani92

IDS authentication package

Package info

repo.fnbpos.net/ids/ids-login

pkg:composer/ids/login

Statistics

Installs: 1 093

Dependents: 0

Suggesters: 0

v4.8.0 2026-11-09 15:09 UTC

README

Laravel authentication package for IDS (Identity Service). Provides login, registration, QR code authentication, account management, and UI customization — all backed by the IDS API.

Requires: PHP 8.2+ | Laravel 11 or 12

Installation

composer require ids/login

Then run the interactive setup wizard:

php artisan ids:install

This will prompt you for your IDS credentials, feature preferences, and automatically configure your .env, publish config/migrations/assets, and run migrations.

Manual Installation

If you prefer manual setup:

# Publish config
php artisan vendor:publish --tag=ids-login-config

# Publish migrations
php artisan vendor:publish --tag=ids-login-migrations

# Publish assets (CSS, JS, phone input plugin)
php artisan vendor:publish --tag=ids-login-assets

# Run migrations
php artisan migrate

Configuration

After installation, configure via .env:

# Required
IDS_HOST=https://your-ids-server.com
IDS_UDID=your-udid
IDS_PASSWORD_CLIENT_ID=your-client-id
IDS_PASSWORD_SECRET=your-client-secret
IDS_CLIENT_CREDENTIAL_CLIENT_ID=your-cc-client-id
IDS_CLIENT_CREDENTIAL_SECRET=your-cc-secret
IDS_LOGIN_REDIRECT_TO=/home

# Optional: space-separated OAuth scopes to request at login (e.g. "nric:read").
# Only granted if the IDS server allows them for your client.
IDS_OAUTH_SCOPES=

# Feature Flags (all optional)
IDS_QR_LOGIN_ENABLED=true
IDS_ACCOUNT_ENABLED=true
IDS_USE_LIVEWIRE=false
IDS_RECAPTCHA_ENABLED=false
IDS_LOGIN_RESTRICTED=false
IDS_LOGIN_ALLOW_LOCAL_AUTH=false

# OTP delivery: dial codes that may receive OTP via SMS (comma-separated).
# All other countries get WhatsApp only. Use '*' to allow SMS everywhere.
IDS_OTP_SMS_COUNTRY_CODES=+60

# QR Login (required if QR enabled)
IDS_QR_REDIRECT_ID=your-redirect-id

# QR realtime via WebSocket (optional — QR falls back to 3s polling without it).
# Uses the app's standard Laravel broadcasting config. Reverb:
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=
REVERB_APP_KEY=
REVERB_APP_SECRET=
REVERB_HOST=broadcast.example.com
REVERB_PORT=443
REVERB_SCHEME=https
# ...or hosted Pusher instead:
# BROADCAST_CONNECTION=pusher
# PUSHER_APP_ID= / PUSHER_APP_KEY= / PUSHER_APP_SECRET= / PUSHER_APP_CLUSTER=ap1

# Recaptcha (required if recaptcha enabled)
RECAPTCHA_SITE_KEY=
RECAPTCHA_SECRET_KEY=

Full configuration reference: config/ids-login.php

Features

Authentication

  • Phone-first login — phone number and password on one page, with a one-time code (SMS / WhatsApp / authenticator app) or QR code as alternatives
  • Password login via IDS OAuth (password grant)
  • OTP login via the IDS otp grant — logging in with a one-time code also marks the phone number verified
  • QR code login with real-time WebSocket updates via Reverb or Pusher (toggleable, polling fallback; pusher-js is bundled)
  • Local auth fallback when IDS server is unreachable
  • Phone verification post-login flow
  • Registration with OTP verification
  • Password reset with OTP verification
  • OTP via SMS or WhatsApp — SMS is offered only for countries in IDS_OTP_SMS_COUNTRY_CODES (default: Malaysia); all other countries receive OTP via WhatsApp, enforced server-side
  • Recaptcha support (toggleable)
  • Force logout — a session revoked on IDS also ends here (see Session check & force logout)

Two-Step Login Flow

GET /login is the phone step, headed "Login / Register": the number, a password field with a Continue button, and OTP / QR code buttons as alternatives. Submitting calls the IDS /api/login/check endpoint; when the account exists, Continue authenticates right away while the alternatives go on to their own pages, each greeting the user by name. Flow state is kept in the ids_login session under the keys country_code, phone_no, phone_full, name, channel and otp_sent_at; ids.login.reset clears it. OTP delivery honours IDS_OTP_SMS_COUNTRY_CODES (blocked countries fall back to WhatsApp) and the resend button has a 60s cooldown. An unverified account that logs in with a password is redirected to the OTP step, since completing an OTP login verifies the phone.

A number with no account goes to GET /login/verify, headed "Register": the user enters a name and picks WhatsApp or SMS to verify the number, and the register API creates the account under that name before the OTP step.

Strings live under the login.* keys of the ids::ids lang file (en / ms / zh).

Server requirement: the IDS identity-server must support grant_type=otp on /oauth/token plus the /api/login/check and /api/login/request_otp endpoints (identity-server feat/two-step-login or later).

Account Management (toggleable)

  • Update display name, email, phone, password, language, avatar
  • OTP verification for email and phone changes
  • Profile picture upload
  • Devices & sessions: see and end your own sessions

UI Customization

  • Database-driven settings via /ids-settings
  • Custom logo, background, primary color, dark mode
  • Configurable layout alignment

Multi-Tenancy

Supports Stancl Tenancy with two modes:

# In config/ids-login.php
'tenancy' => [
    'enabled' => true,
    'mode' => 'multi_db',   // or 'single_db'
    'middleware' => ['tenant'],
],
  • multi_db — separate database per tenant (publish tenant migrations)
  • single_db — shared database with tenant_id column scoping

Session check & force logout

IDS can end a session at any time by revoking its tokens. This package logs in once and then runs on the app's own session, so it keeps asking IDS whether the stored token is still good and ends the local session when it is not.

It is on by default and needs no code changes:

  • Server side — the EnsureIdsSession middleware (alias ids.session) joins the web group by itself and checks the session on every request. That is a cache lookup in FEED mode, and in DIRECT mode a call to GET /api/session/status on IDS at most once per interval per session. Users without a stored IDS token, such as local-auth users, are skipped.
  • Browser side — an inline script is added before </body> on HTML pages for users with an IDS token. It polls GET /ids/session/status while the tab is visible and the user has been active, so a page whose session IDS ended goes to the login screen without waiting for the next click. It stays out of iframes. No build step involved. Where IDS offers it, realtime logout adds a websocket on top.

When IDS answers that the session is over, the user is logged out and the session invalidated. Every reason shows the same message, ids::ids.session_ended (en / ms / zh): "Your session has ended. Please log in again."

Normal requests redirect to the login page with that message. Inertia visits get a 409 with X-Inertia-Location set to the login URL, which makes the client do a full page visit. JSON, AJAX and Livewire requests get a 401 carrying the reason:

{"message": "Your session has ended. Please log in again.", "ids_session": "revoked_by_admin"}
IDS_SESSION_CHECK=true              # false turns all of this off
IDS_SESSION_CHECK_INTERVAL=60       # seconds between server-side checks per session, in DIRECT mode
IDS_SESSION_CHECK_TIMEOUT=2         # HTTP timeout for each call to IDS, in seconds
IDS_SESSION_WATCHER=true            # false stops the automatic script injection
IDS_SESSION_WATCHER_INTERVAL=30     # seconds between browser polls
IDS_SESSION_FEED=auto               # auto = by cache store, true = any store but array/null, false = DIRECT
IDS_SESSION_SYNC_ON_REQUEST=true    # false = only ids:sync-revocations syncs
IDS_SESSION_FEED_INTERVAL=10        # seconds between feed syncs per app
IDS_SESSION_VERIFY_INTERVAL=900     # seconds between direct checks per session, in FEED mode
#IDS_SESSION_REVOKED_TTL=           # seconds a revoked token stays in the cache; default and minimum: verify interval + 300
IDS_SESSION_REALTIME=auto           # auto = whenever IDS offers it, false = never

Run php artisan config:cache again if your deployment caches config, or changes to these values have no effect.

FEED and DIRECT mode

The app can learn that a session ended in two ways. It picks one by itself, and the browser side and the responses above are the same in both.

FEED modeDIRECT mode
Used whenClient credentials are set and the default cache store is redis, memcached, dynamodb, apc, octane or databaseAnything else, see below
A request or poll costsA cache lookupA call to IDS, at most once per interval per session
Calls to IDSOne app-wide sync every IDS_SESSION_FEED_INTERVAL seconds, plus one check per session every IDS_SESSION_VERIFY_INTERVAL secondsOne per session every IDS_SESSION_CHECK_INTERVAL seconds, or every IDS_SESSION_WATCHER_INTERVAL seconds with a tab open

FEED mode is the default. The app asks GET /api/session/revocations on IDS, with its client credentials token, which access tokens have ended. IDS lists them as hashes, never as tokens. Any web request or poll can carry this sync, a guest's too, but only one does per IDS_SESSION_FEED_INTERVAL seconds per app. It always runs after the response has been sent, in app()->terminating(), so no visitor waits for it. It does keep that PHP worker busy, for 2 seconds at most: a sync reads up to 5 pages of 500 inside that budget and leaves the rest for the next one. The login and logout routes stay out of it. Each hash stays in the default cache store for IDS_SESSION_REVOKED_TTL seconds.

A request or poll then hashes the jti of its own access token and looks it up. A hit logs the user out as described above, with the reason from the feed, without calling IDS. Before the response that costs one read of the feed's state, one of the hash and one of the poll state, and a guest none at all.

Each session still calls GET /api/session/status once after login and then every IDS_SESSION_VERIFY_INTERVAL seconds. That safety net catches what the feed does not carry: a token that simply expired, a hash evicted from the cache, an event that was missed. If IDS has pruned events the app never read, or its table was reset, it says so with reset: true, and every session whose last direct check is older than that does one on its next request. A cursor that went missing, say evicted by Redis, counts the same. php artisan cache:clear does not: it also takes the marker that tells a lost cursor from a first run, so the feed restarts from its newest event and what happened meanwhile is left to the safety net.

That longer interval has to be earned. It only applies while the last good sync is at most 3 × IDS_SESSION_FEED_INTERVAL seconds old. Past that a miss in the cache says nothing, so sessions go back to the 4.6 intervals, IDS_SESSION_CHECK_INTERVAL and IDS_SESSION_WATCHER_INTERVAL, until a sync works again. This covers a failing feed, refused client credentials, and an app nobody visited for a while, whose first request after the gap can make a direct check before the sync behind it runs.

A hash only has to outlive that check: a session unseen for IDS_SESSION_VERIFY_INTERVAL seconds asks IDS on its next request anyway. So the hash lives for that long plus 300 seconds, and a lower IDS_SESSION_REVOKED_TTL is raised to it.

DIRECT mode is how 4.6 worked, and what the app uses when:

  • IDS_CLIENT_CREDENTIAL_CLIENT_ID or IDS_CLIENT_CREDENTIAL_SECRET is not set;
  • the default cache store is not one of those above, which includes file, or it cannot be reached;
  • IDS_SESSION_FEED=false;
  • IDS answers the feed with 404 or 405, which means it is older than the feed. That is remembered for an hour, then the feed is tried again.

The store matters because the feed writes one key per revoked token and never reads a dead token's key again. Stores that expire keys by themselves are fine. The database store only deletes an expired row when that key is read, so the feed prunes its own rows: at most hourly it deletes what has expired under <cache prefix>ids_revoked: and touches nothing else in the table. The file store has no such way out, so it stays DIRECT. IDS_SESSION_FEED=true uses the feed on it anyway, except for array and null, and then the files in storage/framework/cache are yours to clean up.

One session alone stays on direct checks every IDS_SESSION_CHECK_INTERVAL seconds if its access token is not a JWT with a jti, because the feed cannot name it.

Load on IDS

calls to IDS per second = apps / feed_interval + sessions / verify_interval

With 10 apps and 5,000 sessions at the defaults, that is 10 / 10 + 5000 / 900, about 7 calls per second. The same sessions in DIRECT mode, each with a tab open, make 5000 / 30, about 167. A sync with more than one page to read adds a call per page. Each app counts on its own cache store, so tenants whose cache is separate, or servers each using a local store, each run the feed, and IDS allows one client 120 calls a minute across all of them.

Cache size

keys = revocations across all of IDS per (verify_interval + 300) seconds

The feed lists every app's revocations, so an app stores them all, not just its own. At the defaults a key lives 20 minutes, so a burst of 100,000 revocations in that window is 100,000 keys, about 25 MB of Redis at a rough 250 bytes each. Raising IDS_SESSION_REVOKED_TTL or IDS_SESSION_VERIFY_INTERVAL grows this in step. If Redis runs with noeviction and is shared with sessions, leave room for it.

How fast a revocation lands

After a revocation, the sync that picks it up comes within IDS_SESSION_FEED_INTERVAL seconds, and it runs after a response, so the request after that sync logs the user out. An open tab follows within IDS_SESSION_WATCHER_INTERVAL more, or within a second or so with realtime logout. A token that expired by itself takes up to IDS_SESSION_VERIFY_INTERVAL seconds, so lower that if it matters more than the load.

ids:sync-revocations

php artisan ids:sync-revocations

This runs one sync, for apps that want no web worker spent on it. The command takes the same turn as a request, so it skips if a sync ran within IDS_SESSION_FEED_INTERVAL seconds or the feed is backing off. To take the sync off requests altogether:

IDS_SESSION_SYNC_ON_REQUEST=false
Schedule::command('ids:sync-revocations')->everyFiveSeconds();

Schedule it at least every 3 × IDS_SESSION_FEED_INTERVAL seconds. Less often and the feed counts as stale between runs, so sessions fall back to the direct intervals. For a scheduler that runs once a minute, set IDS_SESSION_FEED_INTERVAL=30.

It exits with an error when the sync fails. With IDS_SESSION_SYNC_ON_REQUEST=false, nothing syncs if the scheduler stops. That fails safe, on direct checks.

Realtime logout (Reverb)

Polling tells an open tab within IDS_SESSION_WATCHER_INTERVAL seconds. With realtime, IDS tells it at once over a websocket, and the tab polls less while that works. It is on by default, needs no code or keys in the app, and everything else on this page keeps working without it.

  1. When IDS ends a session it publishes session.ended on the public channel ids-session.<token hash>, the same hash the feed uses.
  2. The tab hears it and calls GET /ids/session/status?verify=1. The event itself counts for nothing, so a forged or stray one cannot log anyone out.
  3. The app calls GET /api/session/status on IDS for this session, however recently it did. If the hash is in the cache already, it skips that call.
  4. The tab leaves on the same answer as always: active: false with a redirect.

What it needs. IDS with GET /api/session/realtime and Reverb configured, client credentials, a cache store other than array or null, assets published with php artisan vendor:publish --tag=ids-login-assets (or ids:update), and a browser that can reach the websocket host. FEED mode is not needed. A session whose token is not a JWT with a jti stays on polling, like a page that fails any other condition.

Discovery. The app asks IDS for the public key and host with its client token, once an hour per IDS host and client, after a response has been sent. So the first page after that hour polls, and pages after it listen. An IDS without the endpoint (404 or 405) and any error turn realtime off for an hour. The app secret stays on IDS, and a page only gets the public key, the host and the channel name. Never the token or its id.

Polling while connected. Once the channel is subscribed, a tab polls every IDS_SESSION_WATCHER_INTERVAL seconds or 120 seconds, whichever is longer. As soon as the connection is lost it goes back to IDS_SESSION_WATCHER_INTERVAL, and after reconnecting it polls once for whatever it missed. The feed and the server-side check do not change.

Limits. verify=1 makes one call to IDS per session per 10 seconds, so several tabs hearing one event cost one call. Past that limit it answers like a normal poll. The circuit breaker, the one call in flight and the 15 second back-off all apply, so a mass revocation cannot send every open tab to IDS at once. A tab that finds the call taken asks again 3 and 16 seconds later, and by then the feed usually has the hash.

Load. A tab in use holds one connection to the Reverb server. Apart from its relaxed polls that costs the app and IDS nothing until an event arrives, and an event costs up to three status requests per tab. A tab unused for half of SESSION_LIFETIME closes its connection, as it stops polling, and reconnects on its next poll after the user is back. A hidden tab that is not idle yet stays connected and acts on an event.

Size Reverb for the open tabs of every app that shares it. Without the uv PHP extension its default event loop is limited to about 1,024 open files, so a busy server needs it.

To turn it off:

IDS_SESSION_REALTIME=false

Fail-open

Only a 401 whose JSON body has an ids_session key, or a token listed in the feed, logs anyone out. A 401 without that key, a redirect, 403, 404, 429, 5xx, timeout, connection error or non-JSON answer counts as unknown: the user stays logged in and a warning is logged. An IDS outage never logs users out, but until IDS is back a revoked session is not noticed either.

The same goes for the feed. When a sync fails nobody is logged out, and the next one carries on from the same place, after refreshing the client token once on a 401. Once the last good sync is too old, sessions are checked directly again, as in 4.6.

Realtime adds no way to be logged out, only a sooner check. If the socket is blocked or Reverb is down, or pusher.min.js does not load, the tab polls as if realtime did not exist. If discovery fails, realtime is off for an hour and nothing else changes. Neither a failed discovery nor a failed connection opens the circuit breaker.

A failing feed backs off by itself and logs one warning each time:

The feed or its token call answersThe feed pauses for
Connection error, timeout or 5xx30 seconds
401 or 403, after one token refresh5 minutes
404 or 405, from the feed itselfAn hour, in DIRECT mode

Connection errors, timeouts and 5xx answers on a session's status call open a circuit breaker: a flag in the default cache store, per IDS host, for 30 seconds. While it is set every session skips the call to IDS, and so does the feed. A revocation can go unnoticed for as long as the breaker stays open. The feed reads that flag but never sets it: the feed can fail while IDS answers sessions fine, and the status call is then the only check left.

Only one call per IDS host can be in flight, a feed sync's included. Sessions that fall due meanwhile skip the check, stay logged in and try again on their next request, so a hanging IDS stalls a single request even when the breaker closes or many sessions fall due at once. The claim is released after the call and expires by itself after ceil(IDS_SESSION_CHECK_TIMEOUT) + 1 seconds if the process holding it dies.

Any other unknown answer, such as a 429, comes from an IDS that is working, so it only backs off that session: it retries after 15 seconds and other sessions carry on.

All of this lives in the default cache store. If that store is down or keeps nothing between requests (array, null), the breaker and the one-call limit do nothing: normal requests fall back to the 15 second limit in the session, and polls ask IDS every time.

@idsSessionWatcher

Apps that set IDS_SESSION_WATCHER=false can place the script themselves, usually at the end of the main layout:

    @idsSessionWatcher
</body>

It renders nothing for guests and users without an IDS token, and never twice on a page, including alongside automatic injection.

Content Security Policy

The script is inline, so a strict CSP needs a nonce on it. It uses the one set through Vite::useCspNonce() by default. If your nonce comes from somewhere else, point session_check.csp_nonce in config/ids-login.php at a callable or an invokable class that returns it:

'csp_nonce' => App\Support\CspNonce::class,

Use a class or [Foo::class, 'method'] rather than a closure, which config:cache cannot store. A resolver that fails or returns nothing falls back to Vite.

A response that has a Content-Security-Policy header when no nonce can be found does not get the script, which is logged once at debug level. The server-side check keeps working either way. The middleware only sees headers already set when it runs, last in the web group: a policy that another middleware adds afterwards still gets the script, so set csp_nonce in that case or the browser blocks it.

Realtime logout also needs the websocket host in connect-src, or in default-src if there is no connect-src:

Content-Security-Policy: connect-src 'self' wss://broadcast.example.com; ...

Use wss://, with the port if it is not 443. To a browser https://broadcast.example.com and a bare broadcast.example.com do not cover a websocket, so the package does not count them either. A policy that does not allow the host leaves the page polling, and no pusher.min.js is loaded. The pusher.min.js tag uses the same nonce as the script.

A policy the package cannot read, because a middleware adds it later or the script comes from @idsSessionWatcher, is found out in the browser. If it refuses the socket, the script stops trying after that one violation and keeps polling.

Good to know

  • Deploy IDS first. Until GET /api/session/status exists on IDS, every check is unknown: nobody is logged out, but each session retries every 15 seconds and logs a warning.
  • Polls run the full web stack. A poll is a normal web request, so whatever else is in your web group (locale, activity logging, analytics) runs every IDS_SESSION_WATCHER_INTERVAL seconds for each visible tab. Have such middleware skip the ids.session.status route if that matters.
  • Polls do not save the session. They overlap real requests, and saving would undo what those requests stored. What a poll learns goes to the default cache store under ids_session_check:<hash of the session id>, and the session is only saved when the poll logs the user out.
  • Idle timeout. Because a poll does not save the session, it does not keep it alive either: SESSION_LIFETIME counts from the last real request, even with a tab open. The script also stops polling after half of SESSION_LIFETIME without real input (pointer, keyboard, scroll, touch), so an unused tab stops asking IDS.
  • Only IDS moves a page. The script leaves the page only when IDS says the session is over. A poll that finds a guest, because the local session ran out or the user logged out, answers {"active": false, "ids_session": "guest"} and the page stays, so nobody loses a form to a poll. The next submit or click gets the usual 419 or login redirect.
  • Other tabs follow. When IDS ends a session, the reason stays in the new session as ids_session_ended for 10 minutes or until the next login. A guest poll that finds it answers active: false with that reason and a redirect, so every open tab leaves on its next poll. Hidden tabs do so when they become visible. Only the first tab to reach the login page shows the message. With realtime every tab hears the event and leaves within a few seconds, hidden ones included.
  • Route cache. Run php artisan route:cache again after updating. With an older route cache the watcher stays off; the server-side check still works.
  • Tenancy. With tenancy.enabled, the check waits until the tenant is initialized, because users may live in the tenant database. On a route where tenancy middleware runs after the web group, one request is served before a revoked user is logged out. Stancl's stock provider runs its middleware first, so this does not apply there. Routes that never initialize a tenant are skipped, and a poll on one reports the session as active. Either can still carry a feed sync, which runs after the response, when a tenant's own credentials are in place. Tenants on the same IDS host and client share one feed and its hashes. A tenant with its own client has its own feed, which ids:sync-revocations does not cover.
  • Routes outside web are not checked. Add the ids.session middleware to those that use the session.
  • Console. The middleware only joins the web group for web requests and your test suite, so artisan commands and queue workers skip it.
  • Tests in your app. A strict mock of IdsApiClient needs sessionStatus(), which returns IdsApiClient::SESSION_ACTIVE, a reason or null. Or set IDS_SESSION_CHECK=false in phpunit.xml. The array cache store keeps tests in DIRECT mode with realtime off; on any other store, set IDS_SESSION_FEED=false and IDS_SESSION_REALTIME=false as well.
  • window.Pusher. Where realtime is on, pusher.min.js sets this global on the page. It is the same library Laravel Echo uses, and a client your app has already created is not affected. If your bundle sets the global itself the script uses that one.

Apps not using this package

Apps that talk to IDS without ids/login do not get any of this. They must call GET /api/session/status with Authorization: Bearer <user access token> and Accept: application/json themselves:

  • 200 {"active": true, "ids_session": "active"} means the token is valid.
  • 401 {"active": false, "ids_session": "<reason>"} means the session is over. The reason is revoked_by_admin, revoked_by_user, revoked, expired or invalid, and new reasons may follow, so treat any value the same way.

Treat only a 401 with ids_session as definitive, and anything else as unknown, including a 401 without that key. Without the Accept header IDS redirects instead of answering 401. The endpoint is throttled to 60 requests a minute per token, so one app server polling for all its users is not limited as a whole.

Devices & sessions

With account management on, Devices & sessions has its own page at /my-account/sessions (ids.account.sessions.page), reached from the Manage devices & sessions row above Go Back on My Account. It needs no code changes: Blade mode uses the my-sessions view and Livewire mode the ids-account-sessions component. Users see every session they have on IDS, across apps: app name, device, app version, IP and when they logged in, with a This device badge on the current one, which always comes first. IDS lists up to 50, newest first, and the page says "and N more" past that.

  • Log out on a row ends that session after a confirmation. The current device has no such button: it logs out with the app's normal logout. The routes still accept it, and then the user is also logged out here and sent to the login page.
  • Log out all other devices ends everything but the current session. It is disabled when there is nothing else to end.

The other device finds out on its next session check, like any other revoked token: see Session check & force logout. Its ids_session reason is revoked_by_user, and it sees the usual "Your session has ended" message.

The page loads its list after it opens, showing a skeleton, so a slow IDS never holds it up, and only reloads after an action. In Livewire that runs through wire:init. Its styles are inline in the views (ids-sp- classes), so it looks right even in an app that has not published assets again.

What IDS answers the list withWhat the page does
The listShows it
404, 405, or anything that is not a list (older IDS)Says "Not available yet", and My Account drops its link for the rest of that login
401, 403, 429, 5xx, a timeout or a connection errorShows an error with Try again

Users without an IDS token, such as local-auth users, do not get the link. A plain 401 from these calls never logs anyone out: as everywhere, that takes a 401 with ids_session from the session check.

The JSON routes behind the page sit in the account route group (web, auth, and the tenancy middleware if enabled):

RouteAnswer
GET /account/sessions{"success": true, "supported": true, "data": [...], "meta": {"total": 57, "more": 7, "others": 56}}
POST /account/sessions/{id}/logout{"success": true, "data": {"ended": 1, "current": false, "redirect": null}}
POST /account/sessions/logout-others{"success": true, "data": {"ended": 3}}

Each row in data has id, app, device, app_version, ip_address, logged_in_at, current and details, the translated lines to display. app and device are never empty: they fall back to "Unknown app" and "Unknown device". On an older IDS supported is false. When the current session ends, redirect holds the login URL. Failures answer 422 with a translated message, or 404 if the session had already ended.

device and app_version come from the client that logged in, so treat them as untrusted if you build your own UI on this: escape them, and do not put them in HTML.

IDS throttles this API to 30 requests a minute per user. Do not poll it.

Passkey 2-step verification

An optional second step after the normal password or OTP login. It needs an identity-server with passkey 2FA, and only OAuth clients with Passkey 2FA switched on in IDS ask for it (per app). Users turn it on for themselves by adding a passkey under My Account. Everyone else, and every other app, logs in exactly as before: no code or config changes are needed in the app.

At login. When IDS answers the password or OTP grant with 403 code 4032 (no token issued), the user lands on Confirm it's you (/login/two-factor), in Blade and Livewire mode alike, like the QR step. The challenge is kept in the session, never the password.

  • Where the device has a passkey built in, the passkey prompt starts by itself; Use passkey starts it again.
  • Send a code to WhatsApp (+6012****420) sends a code to the user's verified phone, then shows a 6-digit code field. A new code can be sent after a minute.
  • Remember this device for 30 days is ticked by default. IDS then returns a token, kept in the encrypted, HttpOnly cookie ids_2fa_remember (SameSite=Lax, Secure on https), and sent as two_factor_remember with every password and OTP grant, so this device skips the step.
  • Success logs in exactly like a normal login: same user sync, Auth::login and redirect to the intended URL.
  • A wrong passkey or code keeps the step with an error. After 5 wrong tries, or after 5 minutes, the user goes back to the start with "That took too long. Please log in again."

Browsers without passkeys (feature detection on window.PublicKeyCredential and PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()): the step says "This browser can't use passkeys. Use your phone or get a code on WhatsApp.", puts the WhatsApp option first, and keeps Use passkey for a passkey on a phone (QR / nearby device). A browser without WebAuthn at all, as some in-app browsers, does not get the button. Nothing waits on a browser that never answers the check.

After registering. Right after a new account is registered and logs in, in an app where IDS offers passkeys (its options call answers 200), the user is asked once: "Add a passkey for extra security?" Add passkey / Skip. Only devices with a built-in passkey see it; elsewhere the page skips itself. Existing users are never prompted.

My Account. A Passkeys & 2-step verification row sits above Manage devices & sessions and opens /my-account/passkeys (ids.account.passkeys.page): the 2-step verification switch, the user's passkeys (name, added, last used) with Rename and Remove, and Add a passkey. A browser that cannot create passkeys gets a note instead of the button; renaming and removing still work. The row only appears once IDS has listed passkeys for that login, so an older IDS (404) never shows it. Styles and scripts are inline (ids-sp-/ids-pk- classes), so no asset publish is needed, and the inline scripts carry the page's CSP nonce (see Content Security Policy).

RouteAnswer
GET /account/passkeys (ids.account.passkeys){"success": true, "supported": true, "two_factor_enabled": true, "data": [{"id", "name", "created_at", "last_used_at", "rp_id", "usable", "details"}]}
POST /account/passkeys/options (ids.account.passkeys.options){"success": true, "options": {...PublicKeyCredentialCreationOptions}}
POST /account/passkeys (ids.account.passkeys.store), credential = the JSON string{"success": true, "data": {"id", "name"}}
POST /account/passkeys/{id}/rename (ids.account.passkeys.rename), name{"success": true, ...}
POST /account/passkeys/{id}/delete (ids.account.passkeys.delete){"success": true, ...}
POST /account/passkeys/two-factor (ids.account.passkeys.two_factor), enabled{"success": true, ...}

Failures answer 422 with a translated message (or IDS's own, such as "add a passkey first"), or 404 when the passkey is already gone.

What it calls on IDS. POST /oauth/token with grant_type=two_factor (challenge_id and passkey or otp, remember=1), POST /api/two_factor/whatsapp_otp with the client token, and /api/account/passkeys* and PUT /api/account/two_factor with the user's token. Challenges, assertions, codes and remember tokens never reach the logs.

Views

Ships with Blade views (default) and optional Livewire components.

Blade (default)

Works out of the box. Vanilla JS, no jQuery. To customize:

php artisan vendor:publish --tag=ids-login-views

Livewire (opt-in)

Set IDS_USE_LIVEWIRE=true in .env. Requires livewire/livewire ^3.0:

composer require livewire/livewire

Components: ids-login-flow (two-step login), ids-login-form (legacy single-step), ids-register-form, ids-forgot-password-form, ids-account-manager, ids-account-sessions, ids-account-passkeys

In Livewire mode the Blade views stay registered as a fallback, so pages without a Livewire counterpart (e.g. the QR step) keep working.

Routes

All routes are prefixed with ids.:

NameMethodURI
loginGET/login (phone step)
ids.login.phonePOST/login/phone
ids.login.methodGET/login/method (legacy; redirects to the phone step)
ids.login.passwordGET/login/password
ids.login.submitPOST/login
ids.login.otpGET/login/otp
ids.login.otp.verifyPOST/login/otp
ids.login.otp.channelPOST/login/otp/channel
ids.login.otp.resendPOST/login/otp/resend
ids.login.two_factorGET/login/two-factor ("Confirm it's you")
ids.login.two_factor.verifyPOST/login/two-factor
ids.login.two_factor.otpPOST/login/two-factor/whatsapp
ids.passkey.promptGET/login/passkey (once, after registering; auth)
ids.passkey.prompt.storePOST/login/passkey
ids.passkey.prompt.optionsPOST/login/passkey/options
ids.passkey.prompt.skipPOST/login/passkey/skip
ids.login.qrGET/login/qr
ids.login.resetGET/login/reset
ids.logoutPOST/logout
ids.session.statusGET/ids/session/status (polled by the session watcher; ?verify=1 after session.ended)
ids.registerGET/register
ids.register.submitPOST/register
ids.register.otpGET/register/otp
ids.register.verify-otpPOST/register/verify-otp
ids.password.requestGET/password/reset
ids.password.otpPOST/password/reset/otp
ids.password.resetPOST/password/reset
ids.phone.verifyGET/phone-verification
ids.qr.callbackPOST/qr-login/callback
ids.qr.statusGET/qr-login/status
ids.accountGET/my-account
ids.account.sessions.pageGET/my-account/sessions
ids.account.passkeys.pageGET/my-account/passkeys
ids.account.namePOST/account/name
ids.account.phonePOST/account/phone
ids.account.emailPOST/account/email
ids.account.passwordPOST/account/password
ids.account.languagePOST/account/language
ids.account.avatarPOST/account/avatar
ids.account.sessionsGET/account/sessions
ids.account.sessions.logoutPOST/account/sessions/{id}/logout
ids.account.sessions.logout_othersPOST/account/sessions/logout-others
ids.account.passkeysGET/account/passkeys
ids.account.passkeys.optionsPOST/account/passkeys/options
ids.account.passkeys.storePOST/account/passkeys
ids.account.passkeys.renamePOST/account/passkeys/{id}/rename
ids.account.passkeys.deletePOST/account/passkeys/{id}/delete
ids.account.passkeys.two_factorPOST/account/passkeys/two-factor
ids.settingsGET/ids-settings
ids.settings.storePOST/ids-settings

QR and Account routes are only registered when their feature flags are enabled.

User Model

The package adds these columns to your users table:

ColumnTypeDescription
ids_idstringIDS system user ID
ids_hashstringEncrypted IDS identifier
phone_nostringFull phone number with country code (e.g. +60129718420)
country_codestringCountry code (e.g. +60)
country_phone_nostringLocal phone number without country code (e.g. 129718420)
is_activebooleanUser active status

Configure column mapping in config/ids-login.php under attributes if your column names differ.

Updating

composer update ids/login
php artisan ids:update

Translations

Supports English, Malay (ms), and Chinese (zh). Publish to customize:

php artisan vendor:publish --tag=ids-login-translations

Upgrade to 4.6

  • The session check is on by default. After updating, EnsureIdsSession joins the web group and users with an IDS token get the watcher script on their pages. See Session check & force logout.
  • To turn it off, set IDS_SESSION_CHECK=false. To keep the server-side check without the script, set IDS_SESSION_WATCHER=false.
  • It needs an identity-server with GET /api/session/status. Deploy that first.
  • With an older IDS nothing breaks. The answer counts as unknown, so everyone stays logged in, but a revoked session is not noticed either. Each session retries every 15 seconds and logs a warning until IDS is upgraded.
  • Polls run the full web stack, about twice a minute for each visible tab. Check what else is in your web group; see Good to know.
  • Published Livewire views need the new flash block. ids:update does not republish views. If you published them, add this to the phone step of login-flow.blade.php, or the login page will not say why the user landed there:

    @if(session('message'))
        <div class="ids-alert ids-alert-error">{{ session('message') }}</div>
    @endif
    

    Blade views already show it.

  • Devices & sessions needs an identity-server with /api/account/sessions. With an older IDS the page says "Not available yet", so the order of deploying the two does not matter here.
  • Caches. Run php artisan config:cache and php artisan route:cache again if your deployment uses them. With an older route cache the watcher stays off.

Upgrade to 4.6.1

  • Devices & sessions moved from a card on My Account to its own page, see Devices & sessions.
  • No ids:update needed for it. The page and the My Account row carry their own styles. Package CSS and JS URLs now end in ?v=<version>, so browsers drop their cached copies after an upgrade.
  • Published views need updating. ids:update does not republish views. If you copied my-account.blade.php or account-manager.blade.php from 4.6.0, remove the card and add @include('ids::partials.sessions-link') above Go Back. A copied account-manager.blade.php that keeps the card breaks: its session methods moved to the ids-account-sessions component.

Upgrade to 4.8

  • Passkey 2-step verification. Nothing changes until IDS has it and this app's OAuth client has Passkey 2FA switched on. Then users who turned it on get Confirm it's you after their password or code. No code or config changes, no ids:update: the new pages carry their own styles and scripts.
  • The order of deploying does not matter. An older IDS never answers 4032, and My Account only shows the new row once IDS lists passkeys.
  • Before switching it on for an app, set its passkey_rp_id and passkey_origins in IDS (the app's host or a parent domain, and its exact https:// origin). Passkeys only work on https, or on localhost.
  • CSP. The new inline scripts use the same nonce as the session watcher (session_check.csp_nonce, else Vite::cspNonce()). Without one, a strict CSP blocks them: the passkey button then does nothing, and the WhatsApp code still works.
  • Published views. ids:update does not republish views. To get the My Account row in a copied my-account.blade.php or account-manager.blade.php, add @include('ids::partials.passkeys-link') above the sessions link. A copied login-flow.blade.php needs nothing: the second step is its own page.
  • Logging. OTP codes in request payloads are now redacted too.

Upgrade to 4.7

  • FEED mode is on by default. With client credentials and a redis, memcached, dynamodb, apc, octane or database cache store, requests and polls stop calling IDS one by one. On file nothing changes unless you set IDS_SESSION_FEED=true. See FEED and DIRECT mode. No code changes are needed.
  • It needs an identity-server with GET /api/session/revocations, but the order of deploying the two does not matter. Until IDS has it the app stays in DIRECT mode, which works like 4.6, and tries the feed again every hour.
  • IDS_SESSION_CHECK_INTERVAL now only applies to DIRECT mode. In FEED mode each session calls IDS every IDS_SESSION_VERIFY_INTERVAL seconds, 900 by default. A revocation arrives through the feed in seconds, but a token that expired by itself can now take that long to notice. While the feed is failing the old interval is back.
  • The first sync starts at the newest event. A revocation from before it is not in the feed, so the safety net catches it, within IDS_SESSION_VERIFY_INTERVAL seconds.
  • To stay on the 4.6 behaviour, set IDS_SESSION_FEED=false.
  • A published config keeps working. You do not need to publish it again, and the new env variables work with it. If your deployment caches config, run php artisan config:cache again or they have no effect.
  • The scheduler is optional. See ids:sync-revocations.
  • Realtime logout is on by default too. Until IDS offers it, the only change is one call an hour to ask, after a response. To get it, make sure your assets are published and, if you have a CSP, add the websocket host to connect-src. See Realtime logout.
  • The sync needs nothing on your side, but it runs in app()->terminating(). Under PHP-FPM that is after the response is sent. A server that holds the connection until PHP exits will keep the client waiting for it, up to the 2-second budget.

Upgrading to v4.1

  • GET /login now renders the phone step instead of the combined phone + password form. The login and ids.login.submit route names are unchanged.
  • POST /login (ids.login.submit) now only accepts password; the phone number comes from the phone-step session. Direct posts without completing the phone step redirect back to /login.
  • The QR panel moved from the login page to its own /login/qr step.
  • The flat ids::ids.login lang key became the nested login.* array — if you published translations, republish or merge.
  • Requires an identity-server with the otp grant and login-check endpoints (see the server requirement note above).

Upgrading from v3

See the Migration Guide in the design spec.

Key breaking changes:

  • PHP 8.2+ required (was 8.1+)
  • Config keys restructured (run php artisan ids:install to regenerate)
  • Route names now prefixed with ids.
  • Account routes changed from /ajax/update/* to /account/*
  • jQuery removed — views use vanilla JS
  • All vplus references removed

License

Proprietary - IDS