ids / login
IDS authentication package
Requires
- php: ^8.2
- giggsey/libphonenumber-for-php-lite: ^8.0 || ^9.0
- guzzlehttp/guzzle: ^7.0
- pusher/pusher-php-server: ^7.0
Requires (Dev)
- livewire/livewire: ^3.0
- orchestra/testbench: ^9.0|^10.0
- phpunit/phpunit: ^11.0
Suggests
- livewire/livewire: Required for Livewire view mode (^3.0)
Provides
None
Conflicts
None
Replaces
None
- dev-master
- v4.8.0
- v4.6.1
- v4.6.0
- v4.5.1
- v4.5.0
- v4.4.2
- v4.4.1
- v4.4.0
- v4.3.0
- v4.2.3
- v4.2.2
- v4.2.1
- v4.2.0
- v4.1.9
- v4.1.8
- v4.1.7
- v4.1.6
- v4.1.5
- v4.1.4
- v4.1.3
- v4.1.2
- v4.1.1
- v4.1.0
- v4.0.49
- v4.0.48
- v4.0.47
- v4.0.46
- v4.0.45
- v4.0.44
- v4.0.43
- v4.0.42
- v4.0.41
- v4.0.40
- v4.0.39
- v4.0.38
- v4.0.37
- v4.0.36
- v4.0.35
- v4.0.34
- v4.0.33
- v4.0.32
- v4.0.31
- v4.0.30
- v4.0.29
- v4.0.28
- v4.0.27
- v4.0.26
- v4.0.25
- v4.0.24
- v4.0.23
- v4.0.22
- v4.0.21
- v4.0.20
- v4.0.19
- v4.0.18
- v4.0.17
- v4.0.16
- v4.0.15
- v4.0.14
- v4.0.13
- v4.0.12
- v4.0.11
- v4.0.10
- v4.0.9
- v4.0.8
- v4.0.7
- v4.0.6
- v4.0.5
- v4.0.4
- v4.0.3
- v4.0.2
- v4.0.1
- v4.0.0
- v3.4.48
- v3.4.47
- v3.4.46
- v3.4.45
- v3.4.44
- v3.4.43
- v3.4.42
- v3.4.41
- v3.4.40
- v3.4.39
- v3.4.38
- v3.4.37
- v3.4.36
- v3.4.35
- v3.4.34
- v3.4.33
- v3.4.32
- v3.4.31
- v3.4.30
- v3.4.29
- v3.4.28
- v3.4.27
- v3.4.26
- v3.4.25
- v3.4.24
- v3.4.23
- v3.4.22
- v3.4.21
- v3.4.20
- v3.4.18
- v3.4.17
- v3.4.16
- v3.4.15
- v3.4.14
- v3.4.13
- v3.4.12
- v3.4.11
- v3.4.10
- v3.4.9
- v3.4.8
- v3.4.7
- v3.4.6
- v3.4.5
- v3.4.4
- v3.4.3
- v3.4.2
- v3.4.1
- v3.4.0
- v3.3.0
- v3.2.1
- v3.2.0
- v3.1.4
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- v3.0.27
- v3.0.25
- v3.0.23
- v3.0.21
- v3.0.20
- v3.0.19
- v3.0.18
- v3.0.17
- v3.0.16
- v3.0.15
- v3.0.13
- v3.0.12
- v3.0.11
- v3.0.10
- v3.0.9
- v3.0.8
- v3.0.7
- v3.0.6
- v3.0.5
- v3.0.4
- 3.0.2
- 3.0.1
- v3.0
- dev-dev
- dev-dev_v4
- dev-dev-daniel
- dev-dev_satrya
- dev-dev-rezha
This package is auto-updated.
Last update: 2026-11-09 16:09:36 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
otpgrant — 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=otpon/oauth/tokenplus the/api/login/checkand/api/login/request_otpendpoints (identity-serverfeat/two-step-loginor 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_idcolumn 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
EnsureIdsSessionmiddleware (aliasids.session) joins thewebgroup by itself and checks the session on every request. That is a cache lookup in FEED mode, and in DIRECT mode a call toGET /api/session/statuson 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 pollsGET /ids/session/statuswhile 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 mode | DIRECT mode | |
|---|---|---|
| Used when | Client credentials are set and the default cache store is redis, memcached, dynamodb, apc, octane or database | Anything else, see below |
| A request or poll costs | A cache lookup | A call to IDS, at most once per interval per session |
| Calls to IDS | One app-wide sync every IDS_SESSION_FEED_INTERVAL seconds, plus one check per session every IDS_SESSION_VERIFY_INTERVAL seconds | One 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_IDorIDS_CLIENT_CREDENTIAL_SECRETis 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.
- When IDS ends a session it publishes
session.endedon the public channelids-session.<token hash>, the same hash the feed uses. - 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. - The app calls
GET /api/session/statuson IDS for this session, however recently it did. If the hash is in the cache already, it skips that call. - The tab leaves on the same answer as always:
active: falsewith aredirect.
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 answers | The feed pauses for |
|---|---|
| Connection error, timeout or 5xx | 30 seconds |
| 401 or 403, after one token refresh | 5 minutes |
| 404 or 405, from the feed itself | An 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/statusexists 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
webstack. A poll is a normal web request, so whatever else is in yourwebgroup (locale, activity logging, analytics) runs everyIDS_SESSION_WATCHER_INTERVALseconds for each visible tab. Have such middleware skip theids.session.statusroute 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_LIFETIMEcounts from the last real request, even with a tab open. The script also stops polling after half ofSESSION_LIFETIMEwithout 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_endedfor 10 minutes or until the next login. A guest poll that finds it answersactive: falsewith 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:cacheagain 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 thewebgroup, 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, whichids:sync-revocationsdoes not cover. - Routes outside
webare not checked. Add theids.sessionmiddleware to those that use the session. - Console. The middleware only joins the
webgroup for web requests and your test suite, so artisan commands and queue workers skip it. - Tests in your app. A strict mock of
IdsApiClientneedssessionStatus(), which returnsIdsApiClient::SESSION_ACTIVE, a reason ornull. Or setIDS_SESSION_CHECK=falseinphpunit.xml. Thearraycache store keeps tests in DIRECT mode with realtime off; on any other store, setIDS_SESSION_FEED=falseandIDS_SESSION_REALTIME=falseas well. window.Pusher. Where realtime is on,pusher.min.jssets 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 isrevoked_by_admin,revoked_by_user,revoked,expiredorinvalid, 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 with | What the page does |
|---|---|
| The list | Shows 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 error | Shows 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):
| Route | Answer |
|---|---|
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 astwo_factor_rememberwith every password and OTP grant, so this device skips the step. - Success logs in exactly like a normal login: same user sync,
Auth::loginand 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).
| Route | Answer |
|---|---|
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.:
| Name | Method | URI |
|---|---|---|
login | GET | /login (phone step) |
ids.login.phone | POST | /login/phone |
ids.login.method | GET | /login/method (legacy; redirects to the phone step) |
ids.login.password | GET | /login/password |
ids.login.submit | POST | /login |
ids.login.otp | GET | /login/otp |
ids.login.otp.verify | POST | /login/otp |
ids.login.otp.channel | POST | /login/otp/channel |
ids.login.otp.resend | POST | /login/otp/resend |
ids.login.two_factor | GET | /login/two-factor ("Confirm it's you") |
ids.login.two_factor.verify | POST | /login/two-factor |
ids.login.two_factor.otp | POST | /login/two-factor/whatsapp |
ids.passkey.prompt | GET | /login/passkey (once, after registering; auth) |
ids.passkey.prompt.store | POST | /login/passkey |
ids.passkey.prompt.options | POST | /login/passkey/options |
ids.passkey.prompt.skip | POST | /login/passkey/skip |
ids.login.qr | GET | /login/qr |
ids.login.reset | GET | /login/reset |
ids.logout | POST | /logout |
ids.session.status | GET | /ids/session/status (polled by the session watcher; ?verify=1 after session.ended) |
ids.register | GET | /register |
ids.register.submit | POST | /register |
ids.register.otp | GET | /register/otp |
ids.register.verify-otp | POST | /register/verify-otp |
ids.password.request | GET | /password/reset |
ids.password.otp | POST | /password/reset/otp |
ids.password.reset | POST | /password/reset |
ids.phone.verify | GET | /phone-verification |
ids.qr.callback | POST | /qr-login/callback |
ids.qr.status | GET | /qr-login/status |
ids.account | GET | /my-account |
ids.account.sessions.page | GET | /my-account/sessions |
ids.account.passkeys.page | GET | /my-account/passkeys |
ids.account.name | POST | /account/name |
ids.account.phone | POST | /account/phone |
ids.account.email | POST | /account/email |
ids.account.password | POST | /account/password |
ids.account.language | POST | /account/language |
ids.account.avatar | POST | /account/avatar |
ids.account.sessions | GET | /account/sessions |
ids.account.sessions.logout | POST | /account/sessions/{id}/logout |
ids.account.sessions.logout_others | POST | /account/sessions/logout-others |
ids.account.passkeys | GET | /account/passkeys |
ids.account.passkeys.options | POST | /account/passkeys/options |
ids.account.passkeys.store | POST | /account/passkeys |
ids.account.passkeys.rename | POST | /account/passkeys/{id}/rename |
ids.account.passkeys.delete | POST | /account/passkeys/{id}/delete |
ids.account.passkeys.two_factor | POST | /account/passkeys/two-factor |
ids.settings | GET | /ids-settings |
ids.settings.store | POST | /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:
| Column | Type | Description |
|---|---|---|
ids_id | string | IDS system user ID |
ids_hash | string | Encrypted IDS identifier |
phone_no | string | Full phone number with country code (e.g. +60129718420) |
country_code | string | Country code (e.g. +60) |
country_phone_no | string | Local phone number without country code (e.g. 129718420) |
is_active | boolean | User 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,
EnsureIdsSessionjoins thewebgroup 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, setIDS_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
webstack, about twice a minute for each visible tab. Check what else is in yourwebgroup; see Good to know. Published Livewire views need the new flash block.
ids:updatedoes not republish views. If you published them, add this to the phone step oflogin-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> @endifBlade 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:cacheandphp artisan route:cacheagain 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:updateneeded 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:updatedoes not republish views. If you copiedmy-account.blade.phporaccount-manager.blade.phpfrom 4.6.0, remove the card and add@include('ids::partials.sessions-link')above Go Back. A copiedaccount-manager.blade.phpthat keeps the card breaks: its session methods moved to theids-account-sessionscomponent.
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_idandpasskey_originsin IDS (the app's host or a parent domain, and its exacthttps://origin). Passkeys only work on https, or onlocalhost. - CSP. The new inline scripts use the same nonce as the session watcher
(
session_check.csp_nonce, elseVite::cspNonce()). Without one, a strict CSP blocks them: the passkey button then does nothing, and the WhatsApp code still works. - Published views.
ids:updatedoes not republish views. To get the My Account row in a copiedmy-account.blade.phporaccount-manager.blade.php, add@include('ids::partials.passkeys-link')above the sessions link. A copiedlogin-flow.blade.phpneeds 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,octaneordatabasecache store, requests and polls stop calling IDS one by one. Onfilenothing changes unless you setIDS_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_INTERVALnow only applies to DIRECT mode. In FEED mode each session calls IDS everyIDS_SESSION_VERIFY_INTERVALseconds, 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_INTERVALseconds. - 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:cacheagain 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 /loginnow renders the phone step instead of the combined phone + password form. Theloginandids.login.submitroute names are unchanged.POST /login(ids.login.submit) now only acceptspassword; 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/qrstep. - The flat
ids::ids.loginlang key became the nestedlogin.*array — if you published translations, republish or merge. - Requires an identity-server with the
otpgrant 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:installto 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