Monitoring and logs
OmniPasskey records passkey registration, authentication, renaming, and deletion activity in System Logs. Authorized administrators and helpdesk staff can review success and failure events together with username, IP address, passkey nickname, browser user agent, platform hint, and recorded error text.
The dashboard complements that detailed log view with higher-level adoption and health signals such as successful and failed authentications, passkeys per user, monthly active users, and average authentications.
Use System Logs
System Logs provides one operational view of passkey activity. IdP authentication records Success or Error when an outcome is available, including initialization or service failures and reported terminal browser errors. Background challenge preparation for AutoFill or username typing creates no audit entry; unused preparations remain unlogged. Outcome entries retain the original request’s IP address and available browser context. A username recorded on a failed attempt is submitted diagnostic context and does not establish the user’s identity.
Other operations, including registration, can begin with Init and change to Success or Error.
The page initially shows the previous 24 hours. Use the keyword field to search usernames and set start and end times for routine searches. To investigate a reported login failure, paste the full reference into Support reference on the main page or in Advanced search. The reference matches the audit request ID exactly, ignoring surrounding spaces. The date range and other filters still apply: widen the range for older attempts and clear unrelated filters if no result appears. Both admin and helpdesk operators can use this lookup. Results update automatically, and changing the reference returns to the first page.
Use the advanced-search button beside End time to open additional IP address, operation, status, and error-message filters. The main search controls wrap on smaller screens while keeping the button beside the date field. Operations include authentication, registration, user deletion, administrator deletion, and renaming; statuses include Init, Success, and Error. Use Reset advanced filters to return to the default time window and clear every filter, including the support reference.
Results show time, IP address, username, operation, status, passkey name, user agent, platform, mobile hint, and error message. The support reference remains searchable and appears in the selected entry’s detail summary, rather than in a table column. If no matching audit entry exists, search the IdP logs for that same reference. Use Dashboard for higher-level authentication and adoption trends.
Passkey sign-in challenges expire after five minutes. Each browser session retains at most eight recent requests, including their temporary diagnostic state; starting another request evicts the oldest when that limit is reached. Submitted challenges are consumed once, terminal browser failures invalidate them, and abandoned state is pruned on subsequent passkey requests. An expired or evicted sign-in must be started again. Background preparation and eviction do not create audit entries.
Treat System Logs as audit data because entries contain usernames, network addresses, device context, and failure details. Restrict access to the admin and helpdesk roles that need it, include the history in database backups when required, and define retention according to your organization’s privacy and audit policy. Scheduled maintenance does not purge System Logs automatically.
Correlate runtime signals
| Signal | Best for | Notes |
|---|---|---|
| System Logs | Registration failures, device policy denials, inline-registration errors, and end-user history. | Use this as the first stop because it presents the request outcome closest to the browser ceremony. |
| IdP authn audit log | Service-provider assurance issues, MFA routing questions, and overall IdP outcome tracking. | Enable idp.authn.audit.enabled=true when you need the standard IdP audit trail alongside OmniPasskey System Logs. |
| IdP passkey view debug panels | Browser prompt behavior, conditional mediation, and client-side passkey API state. | Temporarily set idp.authn.passkey.ui.debug=true to expose scrollable on-page diagnostics in the login, username-collection, and inline-registration views. Application diagnostics stay in these panels instead of the browser console. The output can contain usernames, helper-cookie state, request details, and WebAuthn objects, so redact it before sharing. |
When a ceremony needs deeper investigation, use its timestamp, username, operation, status, and error details to compare the System Logs entry with IdP events from the same time window.
Scheduled maintenance tasks
| Task | Purpose | Typical cadence |
|---|---|---|
| Registration cache cleanup | Expires abandoned registration attempts so old browser requests cannot be reused. | Daily |
| Metadata and icon refresh | Refreshes authenticator metadata and icon mappings used for attestation verification and device display. | Daily |
| Dashboard aggregation | Builds the hourly rollups used by the dashboard for authentication and adoption metrics. | Hourly |
Metadata icon conversion uses Pillow 13.0.0. Raster icons are limited to PNG, JPEG, GIF, and WebP, with a 2 MiB decoded input limit and at most 16,777,216 pixels. Raster icons are resized to fit within 512 by 512 pixels while preserving their proportions. SVG icons are rendered in safe mode onto a 512-by-512 canvas. Unsupported, oversized, or corrupt icons are skipped without bypassing metadata signature verification.
If your policy depends on trusted attestation or device-specific allow-lists, treat metadata refresh failures as production-impacting: devices may appear unidentified, lose their friendly names and icons, or be denied by the Default Registration Rule. When Allow Untrusted Registrations is set to Do not allow devices with untrusted attestation to register, missing or unreadable metadata fails closed and registration returns a temporary-service error. The refresh validates a downloaded FIDO blob before publishing it and can fall back to a previously verified blob. Metadata publication is independent of icon publication, and a failed icon refresh leaves the last-known-good mapping in place.
An initial package installation can finish while reporting an HTTP 429 Too Many Requests metadata download and using cached metadata. That fallback does not mean a fresh download succeeded. Check the verified blob’s nextUpdate date: a valid signature does not establish that the metadata is still current. If that date has passed, resolve the refresh failure before relying on current metadata-based trust decisions. Let the scheduled refresh retry, or rerun /var/www/registration-server/env/bin/python /var/www/registration-server/manage.py download_metadata after the upstream limit clears. An individual Metadata icon dimensions are too large warning means that icon was skipped by the image limits above; it does not by itself mean metadata verification failed. The authenticator description and verified metadata remain available, but its icon may appear generic. No authentication-policy change is needed. If the warning persists, provide the AAGUID and warning to support; rerunning the refresh with the same oversized image will not resolve it.
Dashboard totals or charts are not updating
Successful and failed authentication totals and time-series charts use completed hourly rollups. The current hour is not included until the next hourly run. The Passkey Users and Mean Auths cards read the logs directly, so they can change before the rollups. Reload the dashboard or change Dashboard time range at the top of the page to update all time-based views; the page does not refresh automatically.
If System Logs show recent activity but the charts remain empty, check that the operating system's cron or crond service is running. Run these commands as the account that owns the application's scheduled jobs:
/var/www/registration-server/env/bin/python /var/www/registration-server/manage.py crontab show
# Register the application's scheduled jobs if they are missing:
/var/www/registration-server/env/bin/python /var/www/registration-server/manage.py crontab add --verbosity 0
# Backfill missing completed hours immediately:
/var/www/registration-server/env/bin/python /var/www/registration-server/manage.py shell -c 'from webauthn.cron import aggregate_dashboard; aggregate_dashboard()'
The hourly entry should name webauthn.cron.aggregate_dashboard. Aggregation resumes after the last stored hour and interprets timezone-free database timestamps as UTC.
Backup and recovery priorities
At minimum, a customer-facing OmniPasskey service should protect the shared passkey database and the configuration files that define hostnames, relying-party values, authorization rules, and IdP behavior.
- Back up the shared database so you retain passkey registrations, policy settings, device rules, and audit history.
- Back up your management interface configuration, including
.env,env.js,passkey-database.properties, andomnipasskey.conf. - Back up IdP-side passkey configuration, including
passkey.properties,passkey-database.properties, and your MFA map. - Retain any custom branding files such as
logo.pngandtheme.json.
Change management
Changes that require coordinated updates
- Relying-party ID
- Management interface hostname
- Database backend or credentials
- Inline-registration backend URL
Changes that should trigger validation
- Admin or helpdesk authorization rules
- Attestation and enrollment policy
- Resident-key and authenticator-attachment requirements
- IdP MFA flow transitions
When a value changes on either the management or IdP side, verify that the same semantic value still exists everywhere it is required. Misalignment usually shows up as browser WebAuthn errors, missing user records, or backend lookup failures.
Validation checklist
Troubleshoot passkey API requests
Something went wrong while fetching passkeys. means the management page could not load the expected API response. It can result from an HTTP error, a network failure, or a response that is not JSON. Inspect the request before changing database or authentication settings.
- Open the browser’s developer tools, select Network, enable Preserve log, and reload the affected page.
- Filter for
registrations. For My Passkeys, inspect/registration-server/webauthn/registrations/?p=1; admin and helpdesk pages use their corresponding privileged API paths. - Check the request URL, HTTP status, redirect chain, response content type, and response body. The request origin must match
API_BASEin/var/www/html/passkey/env.js, including any nonstandard HTTPS port. A final HTTP 200 can still be a login page after an authentication redirect. - Match the request path and time to the Apache access and error logs. After correcting the cause, repeat the same page load and confirm the registrations request returns HTTP 200 with JSON.
| Observed response | Next check |
|---|---|
| HTTP 400 | Inspect the response and server error details. A Django DisallowedHost error means the request hostname is missing from DJANGO_ALLOWED_HOSTS; follow the allowed-host checks below. Other HTTP 400 responses require their own error details. |
| HTTP 302 to sign-in, or HTTP 200 containing a login page | Check the SP session and redirect chain. If requests alternate between success and sign-in immediately after authentication, check pgrep -a -x shibd for duplicate daemons serving the same SP socket; see Common issues and fixes. |
| HTTP 401 or 403 | Read the response to distinguish Apache authorization, CSRF, and application policy failures. For Apache denials, inspect the authenticated username or released entitlement and the path’s rules in omnipasskey.conf; a working account page does not grant admin or helpdesk access. For CSRF failures, check the token and request origin. Registration can also return a JSON policy rejection after successful sign-in; see registration origin checks and the registration error reference. |
| HTTP 404, or HTTP 200 containing the application HTML | Check API_BASE, the requested path, the enabled Apache omnipasskey.conf, and its WSGIScriptAlias. Confirm the API request reaches Django rather than the frontend fallback page. |
| HTTP 500 | Inspect the matching application traceback in the Apache error log. Use it to distinguish Python/runtime errors from database connection, credential, permission, or missing-schema errors before changing configuration. |
| No HTTP response or a browser-blocked request | Inspect the browser Console and Network error for DNS, TLS, connection, mixed-content, or cross-origin failures. Confirm the browser can reach the configured HTTPS API origin. |
Follow the server logs
Use the paths configured by the active Apache virtual host’s ErrorLog, CustomLog, or TransferLog directives. On Debian/Ubuntu, logs are normally under /var/log/apache2/; the access log may be access.log or other_vhosts_access.log. For example, run the following with permission to read the logs, then reproduce the error:
tail -F /var/log/apache2/error.log \
/var/log/apache2/other_vhosts_access.log
Rocky Linux/RHEL normally uses /var/log/httpd/. The shipped SP HTTPS virtual host uses ssl_error_log and ssl_access_log; its additional ssl_request_log does not include the HTTP status. Follow the configured files, or the service/container logs if your deployment sends them there. An access-log entry can show a recognized user and still return HTTP 400 because Django validates the host after SP authentication. An absent DisallowedHost traceback in the default error log does not establish that the host was accepted; inspect the loaded settings below. Request failures before a passkey operation begins may have no entry in System Logs.
Fix HTTP 400 caused by a disallowed host
The package installer seeds DJANGO_ALLOWED_HOSTS using the detected machine hostname. That may differ from the public management hostname, particularly behind a proxy or in a container. For a request to https://app.example.edu:8443, Django must allow app.example.edu. A typical diagnostic is:
Invalid HTTP_HOST header: 'app.example.edu:8443'. You may need to add 'app.example.edu' to ALLOWED_HOSTS.
Check the configured value without printing the rest of the environment file:
grep '^DJANGO_ALLOWED_HOSTS=' /var/www/registration-server/.env
To inspect what a fresh Django process loads, run the following in the installed application environment, using the same operating-system user and environment as the Apache WSGI service where possible:
cd /var/www/registration-server
env/bin/python manage.py shell -c 'from django.conf import settings; print(settings.ALLOWED_HOSTS)'
Add the public hostname to the existing list in /var/www/registration-server/.env, preserving any other required hosts. Use hostnames without a scheme, port, or path; the frontend’s API_BASE still needs the full HTTPS origin, including the port when applicable. For example:
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,app.example.edu
Keep an explicit host list and DJANGO_DEBUG=false. A service-level DJANGO_ALLOWED_HOSTS environment variable takes precedence over the environment file; update that source too if present. Preserve DJANGO_SECRET_KEY and the other installation settings.
For an environment-file change, validate and gracefully reload Apache as root or with sudo so the WSGI workers load it:
# Debian / Ubuntu
apache2ctl configtest && apache2ctl graceful
# Rocky Linux / RHEL
httpd -t && httpd -k graceful
If you changed the service/container environment instead, restart or recreate that service through its deployment manager so the new environment takes effect. Refresh the management page and verify HTTP 200 with JSON for the registrations request. If a different error appears, investigate that response using the table above. See Application environment file for the related settings.
Fix registration rejected for this site
Passkey registration is not allowed from this site. Contact your administrator if this is an expected registration page. identifies a registration origin rejection. The begin or completion request returns HTTP 403 with JSON problem type https://omnipasskey.com/registration-origin-not-allowed. Successful sign-in and a working passkey list do not establish that the page is allowed to register passkeys.
- Record the page’s exact origin: scheme, hostname, and port. In the browser console,
location.originshows it. For management registration, inspect the begin request’sOriginheader. For inline registration, use the IdP page’s origin and confirm it matchesidp.authn.passkey.relyingPartyOrigin. - In Manage Settings → Registration Allowed Origins, allow the intended origins, one per line. For example, use
https://app.example.edu:8443for management andhttps://idp.example.edu:9443for inline registration. Allowinghttps://app.example.eduallows the default HTTPS port 443, not port 8443. Do not enter paths, wildcards, or the server-to-server backend URL. - Every allowed hostname must equal the shared relying-party ID or be its subdomain. With
ID=example.edu, the example hosts above meet that requirement. Keep the RP ID hostname-only; changing it can make existing passkeys unusable. Correct the intended hostname and configuration instead of changing the RP ID to admit an unrelated site. - Check the effective setting if an environment-file edit has no effect. A saved
registration_allowed_originsdatabase value overridesREGISTRATION_ALLOWED_ORIGINS. Run the read-only command below in the installed application environment, using the same operating-system user and environment as the WSGI service where possible.
cd /var/www/registration-server
env/bin/python manage.py shell -c 'from webauthn.services import PasskeySettingsService; print(PasskeySettingsService.get_registration_allowed_origins())'
When no database override exists, set the comma-separated environment default in /var/www/registration-server/.env, for example:
REGISTRATION_ALLOWED_ORIGINS=https://app.example.edu:8443,https://idp.example.edu:9443
Validate and reload Apache after changing the environment file; see the reload commands and service-environment precedence. A saved management setting applies to new registration requests without an Apache reload. If neither the database setting nor the environment default exists, the fallback is https://<ID>, which may not be the public registration page.
| Setting | What it controls |
|---|---|
DJANGO_ALLOWED_HOSTS | Hostnames Django accepts, without schemes or ports. This does not grant registration permission. |
| Registration Allowed Origins | Exact HTTPS browser origins allowed to register, including nonstandard ports. |
ID / idp.authn.passkey.relyingPartyId | The shared WebAuthn relying-party domain, without a scheme, port, or path. |
API_BASE | The frontend’s API origin, including any nonstandard port. Correct routing does not grant registration permission. |
After correcting the list, start a fresh registration from the intended page. Verify the begin request returns HTTP 200 with registration options, complete the browser prompt, and confirm the completion response contains {"status":"OK"} and the passkey appears in My Passkeys. Completion must use the origin recorded at begin time and that origin must still be allowed. See Registration origins and precedence for configuration details.
Troubleshoot customer-visible messages
Record the exact message, action, page origin, browser and operating-system versions, and attempt time. For API failures, capture the HTTP status and JSON type, detail, and instance; the problem names below are the suffixes of https://omnipasskey.com/ types. For IdP sign-in failures, retain the error code and support reference. Wording can be customized, so use those identifiers and the matching server logs to identify the failure. Redact cookies, tokens, and raw WebAuthn responses before sharing diagnostics.
Use the certificate-trust checks, registration reference, inline-registration reference, sign-in reference, or management reference below. For technical diagnostics, see the IdP error codes, validation and service diagnostics, and browser exception names.
Registration fails because the browser does not trust the site
The message The browser or passkey provider did not complete registration. This can mean cancellation, timeout, or an unsupported request. Try again or use another authenticator. was also observed during a customer installation test when the browser did not trust the site’s TLS certificate. Treat certificate trust as a possible cause, especially when no passkey prompt appears or registration stops immediately. This generic message does not prove that the user canceled, that a prompt appeared, or that attestation verification failed.
- Inspect the certificate and connection information in the affected browser for the exact registration hostname: the management host for My Passkeys, or the IdP host for inline registration. Check the certificate hostname, validity dates, complete issuer chain, and whether that browser and device trust the issuing CA. An HTTPS URL, a page opened after bypassing a certificate warning, or a successful TLS check from the server does not establish trust in the customer’s browser.
- Correct the certificate or chain presented by the server. For a private test CA, install its trust certificate through the intended client’s operating-system or browser trust mechanism. Reopen the exact HTTPS origin and verify that the browser reports a trusted connection without a certificate warning. Do not use warning bypasses or disabled certificate validation as the passkey setup procedure.
- Start a fresh registration. If begin succeeds but there is no completion request, inspect browser diagnostics and the passkey provider as well as certificate trust. A
NotAllowedErrorremains ambiguous: cancellation, timeout, browser/provider limitations, and unmet requirements can produce similar symptoms. If completion reaches the server, inspect its actual response and the matching audit outcome.
For Chrome on Windows, obtain the public root CA certificate from the test operator and check its SHA-256 fingerprint against the operator’s value. With the supplied file named customer-test-ca.cer in the current directory, run the following command to install it into the current Windows user’s Trusted Root Certification Authorities store:
certutil -user -addstore Root .\customer-test-ca.cer
Alternatively, open the certificate, select Install Certificate → Current User, and explicitly choose Trusted Root Certification Authorities. Import the CA certificate, not the site certificate or a private key. Close all Chrome windows, reopen both the management and IdP HTTPS origins using the configured hostnames and ports, and confirm that each connection is trusted. A regenerated CA must be imported again even if its name is unchanged. Chrome accepts locally managed trust anchors on Windows; see the Chrome certificate-verifier documentation and Microsoft’s certificate import reference.
When replacing the server certificate, install the matching TLS certificate and private key on each service that terminates HTTPS, validate its configuration, and reload or restart that service. Check the certificate actually served on both public origins after the reload. Keep SAML signing and encryption credentials separate from this TLS replacement.
Site TLS trust and authenticator attestation trust are separate checks. Changing Allow Untrusted Registrations does not make the browser trust the site’s certificate. Likewise, a server HTTP 403 with registration-origin-not-allowed requires the origin allowlist fix; adding an origin does not repair certificate trust.
Registration messages and API problems
| Message or problem | Diagnosis and recovery |
|---|---|
Error initiating passkey creation., Failed to create passkey., Unknown error creating passkey., or a generic setup failure | Identify the first failed stage: CSRF initialization, begin request, browser creation, or completion request. Inspect Network and the matching server logs using the API procedure. A browser creation failure can occur after a successful begin response; a generic message alone does not identify a database failure. |
A passkey prompt is already open., interrupted registration, or Passkey setup did not finish. | Complete or cancel any pending prompt, including one in another window or on a connected device, then retry from one tab. If no prompt appeared, check browser certificate trust, provider availability, and browser support. A timeout or cancellation-style error does not prove a user action. |
Your browser blocked passkey registration for this site. or Passkey registration requires a secure HTTPS page. | Open the intended page directly over trusted HTTPS, check browser permissions, and verify the RP ID matches the page’s hostname or parent domain. Avoid embedding registration in a cross-origin frame; the server rejects cross-origin registration client data. Use the certificate checks even if the page loaded. |
| Browser or authenticator unsupported, device unavailable, unmet requirements, or browser could not process the request | Connect and unlock the selected authenticator, check browser and OS support, and use an approved device capable of the requested algorithms, discoverable credentials, attachment, and PIN/biometric verification. Review the configured requirements; a generic browser error does not reveal which one failed. For malformed browser options, inspect the begin response and confirm the frontend and registration server came from the same release. |
This passkey registration request is no longer valid.registration-request-unavailable (410) | Start a new registration; do not resubmit an old challenge. Registration state expires after ten minutes and can also have been consumed or removed. If a fresh request fails immediately, compare the backend instances’ database/schema configuration and clocks. If a previous completion response was lost, check My Passkeys before creating another credential. |
Registration could not be verified, required PIN/biometric verification was not confirmed, or approval was not confirmedregistration-verification-failed (400) | Use a fresh request from the intended top-level page. Correlate its request ID with the validation diagnostic to distinguish origin/challenge/RP ID failures from missing User Present or User Verified flags. Complete the prompt; configure a security key’s FIDO2 PIN when verification is required. Touching the key alone does not confirm user verification. Keep required verification enabled and follow the more detailed verification guidance below. |
Trusted authenticator metadata is unavailable and registration is temporarily pausedattestation-service-unavailable (503) | Review metadata refresh. Run /var/www/registration-server/env/bin/python /var/www/registration-server/manage.py download_metadata with the scheduled-task user’s environment and permissions. Check download/verification errors, the verified blob’s freshness, and whether the application can read it. Restore usable verified metadata before retrying; weakening the trust policy does not fix the metadata service. |
Invalid attestation policyinvalid-attestation-policy (400 when saving settings; 503 during registration) | Blocking untrusted attestation conflicts with an Attestation Conveyance Preference of none. Review both settings together. If trusted attestation is required, request an appropriate direct, indirect, or enterprise attestation and use an approved authenticator that supplies it. Conveyance alone does not enforce trust. |
Attestation missing, not trusted, or could not be verifiedattestation-verification-failed (400) | Read the response detail and server diagnostic to distinguish missing attestation, an untrusted chain, and an invalid attestation statement. Check the device’s supported attestation and current verified metadata. Use an approved authenticator for the configured policy. An integrity failure should not be treated as a reason to bypass attestation checks. |
Authenticator or passkey type is not allowedregistration-not-allowed, authenticator-attachment-not-allowed, or backup-policy-not-satisfied (403) | Review the authenticator’s AAGUID rule and Default Registration Rule, the platform/cross-platform attachment setting, or the backup eligibility policy named by the response. Choose an approved authenticator that meets that policy. Backup eligibility means capability to sync or back up; it does not establish that a backup has occurred. |
This passkey is already registered.credential-already-registered (409), or browser reports an already registered authenticator | Refresh My Passkeys; an earlier attempt may already have succeeded. Use the existing credential or another authenticator. A browser InvalidStateError occurs before server completion and is distinct from the server’s duplicate-credential response. Do not delete a working credential merely to clear this message. |
Current policy requires explicit passkey setupconditional-registration-policy-conflict (409) | Use the visible setup button. Required user verification and policies that block untrusted attestation require explicit setup instead of automatic Conditional Create. The normal inline flow selects this fallback; if the conflict repeats, confirm the IdP plugin, browser helper, and backend versions match. |
Invalid request or request body too largeinvalid-request, inline-registration-invalid-request (400), request-body-too-large, or inline-registration-request-body-too-large (413) | Inspect the response detail for the missing or invalid field, request ID, or JSON body. These JSON request bodies are limited to 256 KiB. Check for a proxy rewriting the request and mismatched frontend, plugin, or backend versions. Start a new operation after correcting the cause; do not replay captured WebAuthn responses or remove request limits. |
We could not confirm whether your passkey was registered., session appears expired, connection/service failure, or unexpected response | Inspect the raw response and redirect chain. An authentication redirect, HTML response, network loss, or malformed JSON cannot establish whether completion saved the credential; success requires JSON status: "OK". A session message can also result from an unstructured 401/403 response, so inspect Apache authorization and CSRF errors. Restore access, then check My Passkeys and System Logs before retrying. Follow manual-removal guidance only for the newly created credential that the server explicitly rejected, not an uncertain save. |
Inline-registration messages
Inline registration runs through the browser, the IdP servlet, and the registration backend. Correlate the IdP’s logs/idp-process.log with Apache and application logs at the same time. Keep the backend restricted to the intended IdP; exposing it publicly does not fix a failed inline request. Registration policy errors use the reference above.
| Message | Diagnosis and recovery |
|---|---|
Could not check passkey setup status., Could not start inline registration., or Could not complete inline registration. | Check idp.authn.passkey.inlineRegistration.backendUrl, DNS, TLS trust, connectivity from the IdP, and backend access rules. HTTP 502 can reflect a transport or response-parsing failure; inspect the IdP exception and any backend problem detail. A failed completion response leaves the save uncertain, so check the registered passkeys before retrying. |
| Inline registration backend is not configured | Set the backend URL to the registration API endpoint described in inline-registration configuration and restart the IdP after changing its configuration. This URL must reach the restricted backend API directly. |
| Inline registration is only available after another factor identifies the user | Review the MFA transition and the preceding factor’s authenticated identity. Begin through the normal sign-in flow; directly opening setup cannot supply that identity. Keep the identity check enabled. |
Inline registration request could not be authenticated (inline-registration-forbidden, 403), or backend authentication could not be prepared (500) | Confirm the IdP and registration server share the same database/schema and can write/read inline_registration_tokens. Inspect the IdP exception for token-creation failures. Backend tokens have a 30-second lifetime, are bound to a request purpose, and are consumed once; check clock synchronization and delays. Retry through a fresh flow instead of reusing a token or bypassing backend authentication. |
Passkey request could not be validated. | Check the IdP servlet’s CSRF validation, browser session/cookies, and any proxy behavior affecting the request. Reload and start sign-in again to obtain current state. Do not disable CSRF validation. |
Could not record the inline registration error. | The error-reporting request failed as well. Preserve the original registration message and inspect both requests in the IdP and backend logs. A missing audit entry does not establish success. |
Additional passkey sign-in messages
| Message or symptom | Diagnosis and recovery |
|---|---|
| Username required, no passkey found, or selected passkey unavailable | Use the intended canonical username and a credential for that account and RP ID. Browser AutoFill requires a discoverable passkey. A provider finding no usable credential does not establish that the database has no registration; compare the account and stored credentials through an authorized management page. |
| Choose the same passkey, incomplete passkey response, or no usable credential returned | Start a fresh sign-in in one tab. When a verification retry requests the same credential, select that credential and complete its PIN or biometric step. If responses remain incomplete, check the plugin and passkey.js versions and reload the page to refresh browser assets. Preserve the support reference for server diagnosis. |
| A prompt is already open, sign-in is in progress, or the request was canceled/interrupted | Finish or cancel pending prompts, including those in other windows, then retry. If none appears, check the IdP site’s certificate trust and browser/provider diagnostics. A biometric prompt completing is not proof that the IdP accepted the assertion or finished sign-in. |
| Passkey service unavailable or sign-in could not be completed | Use the error code and support reference to find the IdP failure and distinguish initialization, database, policy, and assertion-verification errors. Use another permitted sign-in method while the cause is corrected. Confirm recovery through the final SP session and IdP authentication audit; browser success alone is insufficient. |
The common issues table also covers account mismatch, MFA and factor restrictions, backup policy, expired sign-in requests, missing user verification, signature/counter failures, and support-reference lookup.
IdP sign-in error codes
The following are the plugin’s public errorCode values. Search the support reference in System Logs and logs/idp-process.log; some failures do not display a reference. Message wording may be customized.
| Error code | What to check |
|---|---|
request-expired | Start a new sign-in. Check session cookies, proxy routing, and clock synchronization if fresh requests immediately expire; requests can also be consumed or evicted. See challenge lifetime and limits. |
account-mismatch, credential-not-recognized | Check the canonical username, first-factor identity, RP ID, and selected passkey against the authorized management view. Use another registered passkey or sign-in method. Check identity alignment before replacing credentials. |
authenticator-not-allowed | Review the authenticator’s authentication rule and default authentication rule. Use an approved authenticator; inspect the IdP diagnostic for missing AAGUID metadata or policy lookup failures. |
mfa-required, factor-not-allowed | Complete an allowed first factor and review the passkey’s MFA Only rule, the permitted preceding factors, and the IdP MFA flow. Use another permitted method if the step is disallowed. |
backup-eligible-required, single-device-required | Review the effective backup eligibility policy and choose a compatible approved passkey. Eligibility describes backup capability, not whether a backup exists. |
user-verification-required, user-presence-required | Repeat the prompt and approve it. When verification is required, complete the PIN or biometric step and configure a security key’s FIDO2 PIN if necessary; a touch alone is not verification. |
verification-failed | Start a fresh sign-in or use another method. Use the validation diagnostic and IdP log to investigate; do not infer cloning or delete a passkey from this generic code. |
service-unavailable | Inspect the initialization or storage exception in the IdP process log. Check plugin configuration, the shared database connection, TLS, credentials, schema and permissions, and policy reads. Confirm the IdP and registration service use the intended database; restore service and verify a complete sign-in. |
Validation and service diagnostics
Use the server diagnostic and traceback to identify the failed check. Protect diagnostic data when sharing it.
| Failed check or symptom | Diagnosis and recovery |
|---|---|
| Challenge does not match, or request state is unavailable | Start a fresh ceremony in one tab; do not replay a response. Check cookies, session continuity and routing between IdP nodes for sign-in, or shared registration state and clocks for registration. Look for stale pages or concurrent attempts. |
Origin does not match, or registration-origin-not-allowed | Compare the browser origin, including scheme and port, with idp.authn.passkey.relyingPartyOrigin and its optional port/subdomain settings for sign-in, and the effective registration origin list for registration. Review proxy host/scheme handling and the origin checks. These are separate checks. |
| RP ID does not match | Compare the RP ID used to create the passkey and the configured registration and IdP RP IDs with the actual hostname. Repair configuration and test with a new ceremony; changing the RP ID can make existing passkeys inaccessible, so plan any migration. |
| Signature or signature counter is invalid | Preserve the reference and compare the server diagnostic and available counter values. Check for stale or restored credential data, concurrent use, and authenticator/provider behavior. Use another sign-in method and investigate repeated failures; a signature or counter failure alone does not prove cloning. Avoid resetting counters or deleting a credential merely to bypass verification. |
| Malformed response | Start a fresh ceremony, update or try another supported browser, and confirm the browser helper, frontend, plugin, and backend are from the intended release. Inspect the logged exception and proxy behavior; do not share raw WebAuthn responses. |
user-presence-required, user-verification-required | Complete the requested approval or PIN/biometric verification. Compare the recorded flags with the effective policy; missing verification does not establish whether a PIN is configured. |
registration-verification-failed, attestation-verification-failed, or registration policy rejection | Inspect the validation check, attestation format and policy, then follow the registration problem reference. Check verified metadata and device policy when indicated. |
Initialization or credential storage fails, internal-error, or service-unavailable | Inspect the matching IdP or Apache traceback for database connection, TLS, credentials, permissions, missing schema or runtime configuration. If completion failed or its response was lost, check My Passkeys and System Logs before retrying. |
| Factor, account, authenticator, or backup policy rejection | Use the corresponding IdP policy or account code, the effective rules, and the prior-factor context to identify the denied check. Restore the intended policy instead of bypassing it. |
Browser exception names
Names can appear in client error text. Browser and provider behavior varies, so treat these as starting points, not definitive diagnoses. Apply the registration or sign-in procedure for the affected operation.
| Exception | What to check |
|---|---|
NotAllowedError, AbortError, TimeoutError | Finish or cancel pending prompts and retry; check provider availability and site certificate trust if no prompt appeared. Cancellation, timeout, interruption, and unmet requirements can look alike. |
InvalidStateError | During registration, check whether that authenticator is already registered; for sign-in try another available credential or sign-in method. Refresh the authorized passkey list. |
NotFoundError, NotReadableError | Check the account and selected passkey; connect and unlock the authenticator and try another compatible device. A browser finding no credential does not prove the server has none. |
ConstraintError, NotSupportedError | Compare requested discoverability, attachment, algorithms, and verification with browser and authenticator capabilities. Try an approved compatible authenticator and complete required PIN or biometric verification. |
SecurityError | Check trusted HTTPS, hostname and RP ID, browser permissions, and whether a cross-origin frame or proxy interferes with the ceremony. |
TypeError, DataError | Update or try another browser and OS; check the returned options and release compatibility if the error persists. Capture sanitized diagnostics for support. |
OperationError, Error, or an unknown exception | If a prompt is already pending, finish or cancel it first. Otherwise retry with another browser or authenticator and inspect the original browser diagnostic and matching server logs. The generic name does not identify a cause. |
Management, settings, and helpdesk messages
| Message or action | Diagnosis and recovery |
|---|---|
| Something went wrong fetching history, logs, users, authentication counts, or other dashboard data | Follow the API response checks for the failing request. Verify the account’s authorization for the requested admin/helpdesk path, date/filter values, and database permissions. A failed request is not a zero result. Investigate aggregation only when requests succeed but dashboard data remains stale. |
Some settings could not be loaded., The setting could not be saved. Your previous selection has been restored., or passkey rules could not load/save | Inspect the settings/rules request for authorization, CSRF, validation, or database-write failures. For invalid-setting or invalid-setting-value (400), read the detail and check supported names/values and frontend/backend release compatibility. Correct the cause, reload the page, and verify the persisted value before relying on the policy. |
| Registration Allowed Origins could not load/save, or an origin is rejected as invalid | Inspect the response and account permissions. Enter exact HTTPS origins, one per line, with required ports and no paths, credentials, wildcards, queries, or fragments. Each host must equal the RP ID or be its subdomain. Check the effective origin list and setting precedence after saving. |
Something went wrong updating the passkey name., or invalid-passkey-nickname (400) | Use a nonblank name within the form’s length limit. Inspect the PATCH response for validation, a stale registration, authentication, or CSRF failures. Refresh the passkey list to determine whether an uncertain update persisted before submitting it again. |
Something went wrong deleting passkeys., or registration-not-found (404) | Inspect each DELETE response and refresh the list. Bulk deletion issues individual requests, so earlier deletions may have succeeded before a later failure. A registration can be absent or unavailable to that account; check the selected account and current list without bypassing access controls. Verify each deletion in System Logs. Removing a server registration and removing a device’s saved passkey are separate actions. |
Something went wrong. We are looking into this.internal-error (500) | This is a generic server response and does not create a support case automatically. Match the route and time to the application traceback in the Apache error log. Diagnose the reported dependency, database, schema, or runtime failure, and keep DJANGO_DEBUG=false on the customer-facing service. |
Common issues and fixes
To change customer-facing wording, use message customization: IdP message-bundle overrides for login and inline-setup browser messages, and the registration server’s messages.json for management browser messages and Python responses. If an override does not appear, check its key and file syntax, refresh the page, and restart the IdP for IdP message changes. Built-in wording remains the fallback.
| Symptom | What to check |
|---|---|
| The UI loads but passkey API calls fail | Follow Troubleshoot passkey API requests to inspect the HTTP response, env.js, Apache routing, and backend logs. For HTTP 400 with DisallowedHost, add the management hostname to Django’s allowed hosts. |
The UI reports Something went wrong while fetching passkeys. even after a fresh sign-in |
Start with the HTTP response checks. HTTP 302 redirects to sign-in indicate a missing SP session. If page, asset, and API requests alternate between HTTP 200 and 302 immediately after sign-in, use pgrep -a -x shibd to check for duplicate daemons serving the same SP socket. Their separate in-memory session caches can cause inconsistent authentication. Stop the duplicates, start one daemon through the host's service manager, validate the Apache configuration, and gracefully reload Apache. This clears existing SP sessions, so sign in again and confirm the registrations request returns HTTP 200 with JSON. Use the service manager for future restarts; shibd -F start launches an additional foreground daemon. |
Registration reports Unable to initialize a secure request. Please try again. |
Inspect /registration-server/webauthn/csrf/ and the Apache error log. This request runs before browser passkey creation. If HTTP 500 errors show a cryptography import failure after a Python dependency update, verify imports in a fresh virtualenv Python process, validate the Apache configuration, and gracefully reload Apache to replace workers holding old libraries. Confirm the endpoint returns HTTP 200 with JSON, then refresh the management page and retry. Investigate the current traceback if errors persist. |
| Registration starts but cannot complete | Confirm the relying-party ID, the exact Registration Allowed Origins list, and hostnames are correct; then review backup eligibility, resident-key, authenticator-attachment, and attestation policy. |
| iPhone or Safari reports cancellation even though the user approved registration | A client: NotAllowedError registration log means the browser or passkey provider stopped before returning a credential for server verification. It can mean cancellation, timeout, or an unsupported request; it does not prove that the user canceled or that server attestation verification failed. The generic registration message has also been observed when the browser did not trust the site’s TLS certificate; follow the certificate-trust checks, especially if no prompt appears. The management page mentions attestation only when Allow Untrusted Registrations is set to Do not allow devices with untrusted attestation to register. Attestation Conveyance Preference set to direct, indirect, or enterprise alone does not trigger that guidance. Standard iCloud Keychain synced passkeys do not provide attestation statements (Apple documentation). When trusted attestation is required, use an approved authenticator that supplies verifiable attestation. A returned credential without attestation receives a specific server rejection instead. The application does not automatically weaken attestation settings or retry without attestation. |
| Registration reports that required PIN or biometric verification was not confirmed | With Registration User Verification set to required, the server rejects a returned credential whose User Verified (UV) flag is absent and gives specific guidance in management and inline registration. For a security key such as a YubiKey, set up its FIDO2 PIN if needed, then retry and complete the verification prompt. Touching the key alone is not enough. If no prompt appears, try another browser or authenticator. The server can detect missing verification but cannot determine whether the key has a PIN configured. When the browser returns only NotAllowedError or ConstraintError, management and inline registration add PIN/biometric guidance when required; these errors can also mean cancellation, timeout, or other unmet requirements. If the browser saved a passkey that the server rejected, follow any manual-removal guidance before retrying. Keep verification set to required when your policy depends on it. |
| Registration cannot confirm whether the passkey was saved, or asks the user to sign in again | Restore the connection or sign in again, then check My Passkeys before retrying. A failed response does not establish whether the server saved the credential. Management and inline registration require a successful JSON response containing status: "OK"; a sign-in redirect, HTML page, empty body, or unexpected JSON cannot report success. These uncertain outcomes do not trigger credential removal. If failures persist, inspect the registration completion request and service logs. |
| Registration requires a passkey that stays on one device or supports syncing | The message identifies the configured backup policy. For a single-device requirement, use a compatible security key or another authenticator whose passkeys cannot sync to other devices. For a syncing requirement, use a compatible password manager or another authenticator that supports passkey syncing. The server checks backup eligibility, not whether a backup has already occurred. |
| The authenticator did not confirm approval to create the passkey | Retry and approve the browser or device prompt; touch a security key when prompted. This message identifies a missing User Present flag during ordinary interactive registration. Conditional Create can legitimately omit this flag and continues to use its separate verification rules. |
| Passkey registration is unavailable in the browser, or the authenticator cannot meet the requirements | Open the management or IdP site using its HTTPS address and use a supported browser. Update the browser and operating system if necessary. When discoverable passkeys are required, try a compatible FIDO2 security key or password manager that can store them. Browser constraint errors can also indicate unavailable PIN or biometric verification; the messages describe the requested requirements without claiming which one failed. Inline registration provides the same recovery guidance and lets users skip setup to continue signing in. |
| The browser says the authenticator is already registered | Use a different authenticator or manage the existing passkeys for this service. The registration page also translates common browser errors such as cancellation, unsupported devices, blocked origins, and unmet authenticator requirements into actionable guidance. |
| Users can register but cannot sign in with passkeys | Verify the IdP plugin is pointed at the same shared database and uses the same relying-party ID expected by the management interface. |
Shibboleth reports Blocked unacceptable redirect location after sign-in |
Compare the return URL's scheme, hostname, and port with the SP handler. With redirectLimit="exact", an HTTPS handler rejects an HTTP return URL. Redirect HTTP application requests to the public HTTPS origin before authentication starts; the shipping container includes this redirect, whose placeholder hostname must be updated during installation. Keep the redirect restriction enabled and start a fresh sign-in from HTTPS to discard the old return URL. Inline registration may already have saved the passkey, so check My Passkeys before registering again. |
Passkey sign-in fails with clientExtensionResults is marked non-null but is null |
Reload the login page and confirm the installed plugin and /idp/js/passkey.js belong to the same release. If the error persists, capture the time and request reference and contact support. Existing passkeys do not need to be registered again. |
| Safari or a security key repeatedly asks users to select Login with Passkey, or reports that required verification did not complete | This can occur when the browser returns a passkey response without the required PIN or biometric verification. A key touch alone does not establish user verification. A blocked or dismissed verification prompt allows one direct button retry, while an unverified response, an unsupported request, or a failed button retry ends recovery with the relevant failure message. Try the same key in another browser, check that its FIDO2 PIN is configured, or use password sign-in. Record the exact Safari and macOS versions, the page debug log’s requestedUserVerification and userVerified values, and the error following Selected passkey verification did not complete. Keep idp.authn.passkey.userVerificationRequirement=required when your deployment depends on PIN or biometric verification; preferred permits sign-in without that verification. |
| Passkey sign-in reports that the request is no longer valid | Start sign-in again from the service you want to access. The request may have expired, already been used, or lost its browser session. A rejected session-validation check also gives this recovery guidance. |
| The selected passkey does not match the account, or is not registered for this sign-in | Check the entered username and choose a passkey for that account. For second-factor sign-in, use a passkey belonging to the account used in the first step. If the saved passkey is no longer registered, choose another passkey or use another sign-in method to reach passkey management. The message does not reveal another account’s name. |
| A passkey type is blocked or cannot be used at this sign-in step | Use another approved passkey or sign-in method. A passkey marked MFA Only requires a first sign-in step before it can be used. Other restrictions may prevent passkeys from being used as a second factor or require a particular preceding factor. Support should review authentication rules and IdP MFA configuration using the support reference when shown. |
| Passkey sign-in requires a passkey that supports backup, or one that stays on a single device | Choose an approved passkey matching the organization’s backup eligibility policy. A passkey that supports syncing or backup and a passkey that cannot be synced meet different policies; the message states which is required. Backup eligibility describes capability, not whether a backup has actually been made. Contact support if no suitable sign-in method is available. |
| Passkey sign-in cannot contact the service, or cannot access the selected device | For a connection error, check the network and retry. For a service error, retry later or use another sign-in method. For a device-access error, connect and unlock the device or security key. Open the IdP using HTTPS and update or change browsers when the message indicates missing browser support. Cancellation and timeout errors remain ambiguous; any PIN or biometric guidance describes the configured requirement rather than proving the reason for failure. |
| The passkey response could not be safely verified, or a support reference is shown | Start sign-in again or use another sign-in method. If the problem persists, give support the reference and the time of the attempt. The reference matches the request ID in IdP logs and, when available, the authentication audit record. Support can inspect the recorded failure code and technical diagnostic. Signature or counter failures do not by themselves prove that a passkey was cloned. Do not delete or re-register a passkey based on this message alone. |
| Passkey sign-in succeeds but the service provider still wants more authentication | Confirm idp.authn.passkey.supportedPrincipals and idp.authn.MFA.supportedPrincipals match the assurance classes your MFA map can really satisfy. |
| Passkey sign-in completes, but My Passkeys is empty or the protected API reports a missing user | Compare the IdP canonical username, the registration’s stored username, and the SP’s REMOTE_USER. Check attribute release and SP filtering for a missing value or a scope appended twice. Align the identity configuration and confirm that both Password and Passkey return the same account before registering replacement credentials. |
| Admins or helpdesk staff receive access denied | Update the Apache and Shibboleth authorization rules for the privileged paths. |
| The passkey button or automatic browser prompt never appears on the IdP login page | First confirm that views/login.vm.passkey has been merged into the active views/login.vm; installing the plugin does not replace the login page. Then check whether idp.authn.passkey.usernameless and idp.authn.passkey.conditionalMediation are configured as intended, confirm the browser supports the feature, and verify the user already has a discoverable passkey if you expect an immediate prompt. |
| Selecting Passkey or returning to Password produces Invalid Event | Declare both switch events in conf/authn/authn-events-flow.xml as well as in the MFA map. Place their explicit global transitions before the stock catch-all, then restart the IdP. |
| Inline registration never appears | Confirm the feature is enabled in the IdP, the backend URL is correct, the prompt interval and target-passkey values are set as intended, and the backend alias is reachable from the IdP only. |
| Conditional registration does not create a passkey automatically | Conditional Create is opt-in; confirm Inline Registration Experience is Automatic Conditional Create. Verify that the user selected a recently saved password through the active default password manager and that its saved username exactly matches the full canonical WebAuthn username. A manually typed password, a short-name entry, or a passwordless or federated login is not eligible. Check browser conditionalCreate capability and password-manager support, but remember that capability support does not guarantee acceptance: provider privacy, account, existing-passkey, or eligibility rules can still reject the request. Registration User Verification set to Required and an Allow Untrusted Registrations policy that blocks untrusted devices intentionally select standard setup without attempting Conditional Create. Use the visible setup button to verify the fallback. |
| A passkey shows Discoverable as Not reported | The browser did not report whether the passkey is discoverable during registration. Some clients do not provide this information, and its absence does not invalidate the passkey. Register a test passkey on the affected client when diagnosing usernameless sign-in. |
| A device is blocked during registration | Review the device in Manage Rules, then check Default Registration Rule and Allow Untrusted Registrations in Manage Settings. |
| Device names or icons look generic or disappear unexpectedly | First run /var/www/registration-server/env/bin/python /var/www/registration-server/manage.py download_metadata and check whether the device name and icon return. For advanced diagnostics, inspect the command’s error output, confirm metadata_latest.jwt points to a recently verified file, confirm aaguid_mapping_latest.json points to a valid mapping, and verify that ICONDATA_DIR is persistent and writable by the scheduled-task user. If metadata succeeds but icon refresh fails, attestation data is current and the UI continues using its last known good device mapping. |
Operational guardrails
Keep /registration-server-backend denied unless inline registration is enabled, and even then allow access only from the IdP host or network.
- Replace placeholder secrets and hostnames before production use.
- Keep separate authorization policies for end-user, helpdesk, and admin functions.
- Review failed-authentication trends regularly rather than waiting for end-user reports.
- Encourage users to maintain at least one backup passkey.