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

ProjectGPS 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
StackJava 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
base5288bee04a — the commit before the change (Support GV56 protocol)
headb4a2743c6c — the change, squash commit of PR 5801
Recordings56 (28 base, 28 head), tagged by branch base / head
The findingintroduced 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.

Browse the recordings →

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.

Open Compare → SQL → Functions → Search →

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:

  1. 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.
  2. 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.
  3. A first login still creates the row with the right flag.
  4. 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 covers said 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 into DatabaseStorage#updateObject and UPDATE tc_users SET name = ?, administrator = ? WHERE id = ?. The description says exactly this.
  • Stage 5 showed one thing beside it. In withoutAnAdminGroupAnExistingAdministratorStaysAnAdministrator the recording on HEAD has LoginService#login called with administrator = false, then the same UPDATE tc_users SET name = ?, administrator = ?, then the assertion failing on the row read back. On BASE the same call is made with false and nothing is written. The cause is in the argument's type: OpenIdProvider computes boolean administrator = adminGroup != null && userGroups.contains(adminGroup), which is false, 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 without openid.adminGroup loses 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 Boolean that is null when 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, -Pappmap and 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 @BeforeEach are outside every trace. The seeded INSERT INTO tc_users still appears because seedUser is called from inside the test method.
  • A HikariDataSource left open by one test writes SELECT ? 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 (ReflectionCache fills a HashMap from Class.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 DatabaseStorage and Liquibase changelog, the project's default engine. The UPDATE that 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.