OptimiDoc authenticates users at devices and in the web console by card, PIN or user name and password. When authentication fails, users cannot reach pull printing, scanning or copy accounting. This article explains how a card read is turned into a user match, then covers the most common authentication and card-reader problems and their resolutions. Menu paths refer to the React web console.
How Authentication Works
-
A user identifies themselves with a credential — a Card, a PIN, or a Login (user name) and password. Each is stored against the user in OptimiDoc.
-
When a reader sends a card number, OptimiDoc optionally runs it through a card-conversion pipeline (see cause 2) so the number matches the format stored on the user, then looks up the matching Card credential.
-
If no user matches, the attempt is recorded in Diagnostics > Unauthorised Accesses — this is the single most useful place to diagnose "unknown card" and "user not found," because it shows the exact card number or login that was rejected and lets you register it in one click.
-
Repeated invalid logins from the same source are throttled (see cause 3).
Symptoms
-
A card tap returns "card not recognised" / "unknown card," or the user is not found after a successful read.
-
A PIN is rejected with "invalid PIN."
-
Card authentication works for some users but not others (usually a format/conversion problem).
-
Web or panel login is refused with "Too many invalid login attempts."
-
Panel login fails specifically on Ricoh or Xerox devices.
Common Causes and Solutions
1. Card Not Registered to Any User
Cause: The card is read correctly but is not enrolled against any user.
Diagnostic steps:
-
Open Diagnostics > Unauthorised Accesses. A rejected card appears as an entry with Source = Authentication and the card number in the Value column (a rejected driverless-print login appears with Source = Spooler).
-
This is where you read the raw card number — you no longer need to dig through raw logs.
Solution:
-
From the Unauthorised Accesses entry, use Assign to an existing user (this stores the value as a Card credential — or a Login credential when the source is Spooler) or Create a new user (the card or login is pre-filled on the new-user form).
-
Alternatively, register the card on the user directly (edit the user and add the card number), or use self-registration at the device: the user logs in with user name and password, then taps the card when prompted.
-
For bulk enrolment, import card numbers via CSV user import.
2. Card Number Format Mismatch — Card Conversion
Cause: The reader returns the card number in a different representation (hexadecimal vs decimal, byte order, trimmed prefix/suffix, bit length) from what is stored on the user, so the lookup fails. This is the usual reason a card works for some readers but not others.
How card conversion actually works (Settings > Authentication):
-
The Card reader type (HP only) dropdown selects the physical reader: Other, HP CZ208A, or RF Ideas. Selecting HP CZ208A reveals Card type 1 and Card type 2 fields for the HP reader's card-type codes.
-
The Card conversion field applies a transformation to the raw card number before lookup. It is not a regular expression — it is a semicolon-separated pipeline of named conversion steps, for example
ASCII2Hex;Hex2Dec(convert ASCII to hex, then hex to decimal). Steps run left to right; a+concatenates the results of parallel branches. There are dozens of built-in conversion operations. In 26.07 and earlier the field was mislabelled Card conversion regex, which misled some administrators into typing an actual regular expression — that will not parse. -
Because writing the pipeline by hand is error-prone, use the Conversion Wizard (the wand button beside the field). Enter up to three input → expected output example pairs (the raw number your reader sends and the number stored on the user), and the wizard evaluates its library of known conversion pipelines against them. It returns Exact conversion matches and, if none fit perfectly, ranked Approximate conversion candidates (with a distance score and sample conversions). Select one to fill the Card conversion field, then Save.
Solution:
-
Read the raw number from Unauthorised Accesses and the stored number from the user profile.
-
Open the Conversion Wizard, enter the raw number as input and the stored number as expected output, and evaluate.
-
Apply the suggested pipeline, save, and re-test one card.
See Authentication (Card Reader).
3. "Too Many Invalid Login Attempts"
Cause: OptimiDoc throttles brute-force login attempts. More than five invalid attempts within a rolling five-minute window from the same client IP address are refused with HTTP 403 "Too many invalid login attempts."
Important characteristics:
-
The throttle is per source IP, not per account — there is no per-account lockout, so a user is never permanently locked out and an administrator does not need to "unlock" the account.
-
It is held in memory and auto-resets: once five minutes pass with fewer than the threshold, logins from that IP are accepted again.
-
Because it is per-IP, many users behind a single NAT/proxy address share the counter — a shared gateway hammering the login can throttle everyone behind it.
Solution:
-
Wait five minutes and retry, or resolve the source of the repeated failures (a stuck client, a wrong stored password, or a misconfigured card).
-
If many users behind one gateway are affected, investigate what is generating the failed attempts from that IP.
4. PIN Code Issues
Cause: The user's PIN is wrong or not set, or PIN login is not offered at the device.
Diagnostic and solution:
-
Check or reset the user's PIN credential on their user profile.
-
Ensure PIN login is enabled as a method for the device (some devices offer card only, PIN only, or both).
-
If PINs are generated automatically, confirm the generated length/format is accepted by the device.
5. Directory (Active Directory) Synchronisation — "User Not Found"
Cause: The user exists in Active Directory but has not been imported into OptimiDoc, or the import has not run recently.
Diagnostic steps:
-
Search for the user under Users. If absent, the directory import has not yet included them.
-
Review the import configuration and last-run status under Users > User Import.
Solution:
-
Run a synchronisation from Users > User Import, or wait for the scheduled automatic synchronisation to run.
-
Verify the import's search base/filter includes the user's organisational unit, and that the bind credentials have not expired.
6. Panel Login Fails on Ricoh or Xerox Devices
Cause: On some Ricoh and Xerox models, panel login could fail when the authentication ticket (carried in the AUTH cookie) grew larger than the device's HTTP header buffer.
Solution:
-
Recent releases slimmed the authentication ticket to stay within the device header limit, resolving these Ricoh/Xerox login failures. If you see panel-login failures with header/cookie-size symptoms on these vendors, upgrade to a current release. See the Release Notes.
7. Device-Side Authentication Configuration
Cause: The device's own authentication settings conflict with OptimiDoc, so the device intercepts login before OptimiDoc can process it.
Solution:
-
Configure the device to use OptimiDoc as its external authentication provider and disable any conflicting built-in/local device authentication.
-
This is delivered through each vendor's integration framework — Konica Minolta OpenAPI, Canon MEAP, and Xerox EIP. Ensure the relevant OptimiDoc login application is registered and set as the active login method on the device, and that the vendor licence for that framework is active where required.
General Diagnostic Workflow
-
Start at Unauthorised Accesses: Diagnostics > Unauthorised Accesses shows exactly what card/login was rejected and lets you enrol it immediately.
-
Identify the failure point: is the card read at all? Is the number transmitted but not matched (format — cause 2)? Is the user found but rejected?
-
Check the logs: Diagnostics > System Logs, filtered around the time of failure.
-
Test with a known-good card/user to isolate a reader/format problem from an account problem.
-
Review recent changes: new firmware, a new reader model, a directory change, or a configuration edit.
In Summary
Most authentication problems resolve at Diagnostics > Unauthorised Accesses, which shows the rejected card or login and enrols it in one click. When a card works on one reader but not another, the cause is almost always number format — use the Conversion Wizard rather than hand-writing the conversion pipeline. Remember the login throttle is per-IP and auto-resets, so there is no account to unlock; and directory "user not found" is an import timing issue, fixed by running a synchronisation.
Related articles