OpenID login demotes every administrator when no admin group is configured
traccar (Java) · traccar/traccar#5801 · Fix OpenID administrator flag not syncing for existing users.
Every recording behind this page is a real test run committed as a file, taken twice: on the commit before the
change and on the change itself. Nothing here needs a build, an account, or a login.
The project. Traccar is an open-source GPS tracking server: phones and vehicle trackers report their positions to it, and people log in to a web app to see where their devices are. Companies run it themselves, and staff can sign in with a company single-sign-on provider (OpenID Connect).
The bug. If the server has not been told which single-sign-on group means 'administrator', then every existing administrator who signs in through single-sign-on is silently downgraded to a normal user on that login. The pull request meant to keep the admin flag in sync with the provider; it also made 'no group configured' count as 'not an admin' and wrote that back.
Who it affects. Every self-hosted Traccar installation that uses OpenID login without setting openid.adminGroup. Administrators lock themselves out of admin features just by logging in.
1 What is loaded
| Project | GPS tracking server: device protocol decoders, a REST API for users, devices, groups and positions, a permissions model deciding who sees which devices, and password, LDAP and OpenID Connect login |
|---|---|
| Stack | Java 17 target, Gradle 9.3.1, Jersey 3 on Jetty 12, Guice, the project's own JDBC storage layer over H2 by default, Nimbus OAuth 2 SDK for OpenID Connect |
| base | 5288bee04a — the commit before the change (Support GV56 protocol) |
| head | b4a2743c6c — the change, squash commit of PR 5801 |
| Recordings | 56 (28 base, 28 head), tagged by branch base / head |
| The finding | introduced by this PR — novel, HEAD introduced it; upstream found it three weeks later as issue 5829 |
AppMap gold traces are recorded test runs checked in next to the code they
describe (gold_traces/**/*.appmap.json): every function call, SQL statement, HTTP request and exception a test
produced, with timing and data values stripped so two runs can be compared line by line.
2 Compare base and head
Open Compare, type base as branch A and head as branch B. The same tests were recorded
on both sides, so what differs is what the change did at runtime: new SQL, new call paths, new exceptions.
Then click any recording to read its call tree and the statements it ran.
Or just ask. The Ask the traces panel on the left is a chat over these same recordings: it runs the CLI's query tools for you and answers as if you were a developer on the project.
3 What the review found
The Review tab shows the behavioural review of this change as a pull-request comment (red / yellow / green), built only from the difference between the two sets of recordings.
Open the review →4 The case, in full
traccar: OpenID login demotes every administrator when no admin group is configured
track novel, HEAD introduced it; upstream found it three weeks later as issue 5829
upstream traccar/traccar
what it is GPS tracking server: device protocol decoders, a REST API for users, devices,
groups and positions, a permissions model deciding who sees which devices, and
password, LDAP and OpenID Connect login
stack Java 17 target, Gradle 9.3.1, Jersey 3 on Jetty 12, Guice, the project's own
JDBC storage layer over H2 by default, Nimbus OAuth 2 SDK for OpenID Connect
BASE 5288bee04a the commit before the change (Support GV56 protocol)
HEAD b4a2743c6c the change, squash commit of PR 5801
merged 25 Feb 2026
pull request 5801 "Fix OpenID administrator flag not syncing for existing users"
known bug the one the PR fixes: an existing user's administrator flag and name were not
updated on later OpenID logins. Nothing else was known going in.
outcome HEAD introduced a defect. Every existing administrator who logs in through
OpenID on a server with no openid.adminGroup is demoted on that login. Upstream
fixed it three weeks later as issue 5829 (commit 9c31a03b3, 19 Mar 2026). This
review found it from the recordings without knowing that.
Provenance: this case was run on 21 Sep 2026 in the sandbox that ran the other traccar cases, from
the queue in the appmap-rules taxonomy (traccar 5931, 5801, 5861). It was not rerun on a clean
machine and has no control run without the AppMap agent attached. The two companion cases from
the same run are traccar-openid-login-crashes-without-groups-claim (5861) and
traccar-memory-storage-fails-under-concurrent-readers (5931). They share the probe test and the
recording setup with this one.
The protocol in ../PROTOCOL.md was run as the reviewer of the merged pull request. The review is in REVIEW.md. Each stage is recorded below as it happened.
What the application does
traccar keeps a tc_users table with one row per person and an administrator flag on each row.
Administrators see every device and every user and may change server settings. A person can log
in with a password, or through an OpenID Connect provider: the browser is redirected to the
provider, comes back to /api/session/openid/callback with a code, the server exchanges it for
tokens, reads the userinfo endpoint, and calls LoginService.login(email, name, administrator).
The administrator argument is computed by OpenIdProvider from the provider's groups claim: a
member of the group named in openid.adminGroup is an administrator. When no openid.adminGroup
is configured the provider has no opinion on the flag. Administrators are then made by hand, in
the users table.
What the change did
On BASE LoginService.login created the user row on the first OpenID login, with the computed
flag, and on later logins looked the row up by email and returned it unchanged. A person added to
the admin group after their first login never became an administrator in traccar, and one removed
from it never lost the flag. The change adds an else if branch: when the provider's name or
administrator value differs from the stored row, both columns are written back with
UPDATE tc_users SET name = ?, administrator = ? WHERE id = ?.
Stage 0: the prerequisites
On the BASE worktree, ./gradlew test (whole suite, no agent), JAVA_HOME at Temurin 25.0.4.1
launching Gradle 9.3.1: 560 tests completed, 25 skipped, and the only failures are the four
stage 5 probe tests that fail by design on BASE. Every project test passes. The project has no test that starts the web server or reaches the storage
layer against a database on this revision, so "the app answers a real request" was met by the
probe at stage 5 rather than by an existing test: it runs the project's own Liquibase schema on H2
and drives the real OpenID callback. Nothing is mocked in the application except the servlet
request object handed to the callback. No container was needed.
Stage 1: what was known
The pull request number and title, and that the review should not assume the title is the whole story. The diff was read at stage 4, the description at stage 6.
Stage 2: the baseline on BASE
The recording setup is the one proven on the earlier traccar cases, cherry-picked onto BASE:
the com.appland.appmap Gradle plugin 1.2.0 with the agent attached to the real test task behind
-Pappmap (the plugin's own task is skipped under Gradle 9), -PappmapIgnoreTestFailures=true so a
failing assertion still yields its recording, appmap.yml recording org.traccar in full with the
decoder byte helpers, model plumbing, log formatter and config key plumbing excluded, and labels on
the security filter, login service, permissions service, session resource and cache manager.
The manifest carries 20 of the project's own tests, one to three per subsystem (protocol
decoding, the position pipeline, events, reports, geofences, calendar, geocoder, forwarding,
config). update --record on BASE: "Blessed 0, seeded 20". Every one is unit-shaped: no SQL, no
HTTP, no label.
Stage 3: the change applied
The same setup on HEAD (b4a2743c6c). Same 20 entries recorded: "seeded 20".
Stage 4: the drift and the coverage, before adding anything
appmap-review compare: 0 changed of 20, no SQL difference, no API difference. Then the diff was
read: one file, LoginService.java, the else if branch above. covers on the committed baseline:
No baseline runs a code object matching 'LoginService#login'
No baseline runs a code object matching 'OpenIdProvider'
No baseline runs a code object matching 'DatabaseStorage#updateObject'
So the quiet comparison meant nothing. The behaviors the change touches, written down before anything was added:
- An existing user added to the admin group should become an administrator on the next login, and one removed from it should lose the flag. A renamed user should get the new name.
- When no admin group is configured, OpenID has no opinion, and a flag set by hand must survive the login: an administrator stays one, a plain user stays plain.
- A first login still creates the row with the right flag.
- A provider that sends no groups claim at all, with and without a required group.
Stage 5: the probe, on both branches
OpenIdLoginProbeTest, eight JUnit 5 tests in src/test/java/org/traccar/database, identical on
both branches. It starts a stand-in identity provider on a local port (com.sun.net.httpserver)
answering /token with an unsigned id token and /userinfo with a configurable name and groups
claim, builds the project's Config, DatabaseStorage (H2 in memory, the project's Liquibase
schema through DatabaseModule.provideDataSource), LoginService and OpenIdProvider the way
the injector does, seeds a user row through the storage layer, calls the real
OpenIdProvider.handleCallback with a mocked servlet request, and reads the row back through the
storage layer. Mockito is used for the servlet request and session only.
The eight tests, and their result on each branch:
| Probe | BASE | HEAD |
|---|---|---|
| first login from the admin group creates an administrator | pass | pass |
| existing user added to the admin group becomes an administrator | fail | pass, one UPDATE tc_users |
| existing administrator removed from the admin group is demoted | fail | pass, one UPDATE tc_users |
| renamed user gets the new name on login | fail | pass, one UPDATE tc_users |
| no admin group: existing administrator stays an administrator | pass | fail, one UPDATE tc_users |
| no admin group: existing plain user stays a plain user | pass | pass |
| no groups claim, no group required: login succeeds | pass | pass |
| no groups claim, allow group required: refused, not a crash | fail, NPE | fail, NPE |
The three BASE failures in the middle are the bug the PR fixes. The HEAD failure in the fifth row is new. The last row fails the same way on both branches and is the subject of the 5861 case.
Recorded with manage.mjs update --record on each branch, the probe entries added to the
manifest: 28 entries, all recorded. covers afterwards: 7 of 28 baselines run
LoginService#login, 8 of 28 run OpenIdProvider#handleCallback.
One instrumentation effect fixed here: the probe's Hikari connection pool outlived the test and
its keepalive SELECT ? appeared inside later tests' recordings in the same JVM (CalendarTest,
PositionForwarderUrlTest). The pool is now closed in @AfterEach and every entry was
re-recorded. The SELECT ? still appears at the end of some probe recordings, from the probe's
own pool, and varies between runs. The review treats it as noise.
Stage 6: what was found, and by which stage
- Stage 2 alone flagged nothing: 0 of 20 changed, and
coverssaid why. - Stage 5 showed the fix: three traces that on BASE end at
SELECT * FROM tc_users WHERE email = ?and return the stale row, on HEAD continue intoDatabaseStorage#updateObjectandUPDATE tc_users SET name = ?, administrator = ? WHERE id = ?. The description says exactly this. - Stage 5 showed one thing beside it. In
withoutAnAdminGroupAnExistingAdministratorStaysAnAdministratorthe recording on HEAD hasLoginService#logincalled withadministrator = false, then the sameUPDATE tc_users SET name = ?, administrator = ?, then the assertion failing on the row read back. On BASE the same call is made withfalseand nothing is written. The cause is in the argument's type:OpenIdProvidercomputesboolean administrator = adminGroup != null && userGroups.contains(adminGroup), which isfalse, not "no opinion", when no admin group is configured. BASE ignored the value for existing users so the mistake was harmless. HEAD compares it with the stored flag and writes it back. Every administrator on a server that uses OpenID withoutopenid.adminGrouploses the flag on their next login, and the only way back is a manual edit that the next login undoes again. - The result: finding, high, introduced by HEAD. Upstream reported it as issue 5829 and fixed
it on 19 Mar 2026 (commit 9c31a03b3 "Fix OpenID admin reset") by making the argument a
Booleanthat isnullwhen no admin group is configured and skipping the write when it is. The 5861 revisions in the companion case carry that fix, and the same probe passes this row there. This review did not know about 5829 when the probe was written. The row was written from behavior 2 in the stage 4 list.
Tooling notes
- The plugin,
-Pappmapand Gradle 9 notes from the earlier traccar cases apply unchanged. - The agent records only methods annotated
@Test, so the identity provider start, the Liquibase migration and the seeding in@BeforeEachare outside every trace. The seededINSERT INTO tc_usersstill appears becauseseedUseris called from inside the test method. - A
HikariDataSourceleft open by one test writesSELECT ?keepalives into the recordings of later tests in the same JVM. Close it in@AfterEach. - The storage layer's INSERT column order varies between JVM runs (
ReflectionCachefills aHashMapfromClass.getMethods()), so the engine's two-run check reports traces that write a row as unstable in SQL text only. Read the changed traces for structure, not for column order.
Where the tests live and what they run against
- All tests are JUnit 5 tests in the repository, run by the project's Gradle build on both branches with the same command.
- The database is H2 in memory through the project's own
DatabaseStorageand Liquibase changelog, the project's default engine. TheUPDATEthat demotes the administrator is the same statement on any engine. - The identity provider is a stand-in on localhost. The id token is an unsigned JWT and the provider accepts any code. What the probe proves is what traccar does with the userinfo it receives, not the token exchange. Nothing in the change touches the token exchange.
What is in this folder
REVIEW.md the AppMap behavioral review, findings first
files/base/ every file the setup added on top of BASE: build.gradle, appmap.yml,
.gitignore, .gitattributes, the manifest, the sanitized baselines, the
stage 5 probe
files/head/ the same on top of HEAD, with the baselines re-recorded there
reproduce.sh rebuilds both branches in ./repo and runs the comparison
Nothing here is sent to the upstream project.
Reproduce the review
Needs git, Node, the AppMap CLI at ~/.appmap/bin/appmap or appmap on PATH, and the skills
from getappmap/skills (the script clones them next to this folder if absent).
./reproduce.sh rebuild the branches and compare the committed gold traces
RECORD=1 ./reproduce.sh also re-record every gold trace on both branches, bless, compare
Re-recording needs JAVA_HOME pointing at a JDK 21 or newer and network access for Gradle. No database and no container are needed.
The commits the setup made
On pr5801-base (5288bee04a):
0855a1e68 appmap: instrumentation and the manifest on the 5936 base revision (cherry-picked)
c9a0f5554 appmap: baseline gold traces on the 5801 base revision
6a3edf652 appmap: focused probe for the changed symbols, added to the gold traces
On pr5801-head (b4a2743c6c):
b21d934a6 appmap: instrumentation and the manifest on the 5936 base revision (cherry-picked)
20f49cd31 appmap: baseline gold traces on the 5801 head revision
1a42d1f13 appmap: focused probe for the changed symbols, added to the gold traces
Repositories, commits, issue and pull request numbers are named. The people who wrote them are not.
Copyright 2026 Elizabeth Lawler. CC BY 4.0.
5 Do this on your own repository
npm install -g @appland/appmap # the CLI
appmap install # add the agent to your project (Java, Ruby, Python, Node)
# run your tests once on base and once on head with the agent attached, then:
appmap index --appmap-dir traces
appmap query ui --appmap-dir traces # this UI, on localhost
appmap compare --base-dir traces/base --head-dir traces/head
Case files: evlawler/goldtrace-examples. Upstream: traccar/traccar#5801.