.. audit-logs.rst ============== Audit Logs ============== The audit logging for the FIDO Connector follows the 4Ws (Who, Where, What, When) auditing pattern, which provides full traceability of all actions in your FIDO Connector implementation. The FIDO Connector writes all output to stdout (standard output). Available output formats and field descriptions are described below. Log formats =============== The following describes the available audit log output formats and how to enable them. Text Format -------------- This is the default audit log format setting using plain text. With LOG_FORMAT unset, the output will use the text format. Data includes the corrected timestamp, the service name, service version, service environment, and schema version. Audit data is rendered as ``key="value"`` pairs at the end of the message. .. code-block:: 2026-08-27T09:12:24.138-03:00 [main] [traceId=test-trace-id, jobName=test-job, operatorEmail=operator@email.com, operatorSource=enrollment_suite, opOrigin=cron_job, credentialRequestId=test-credential-request-id, scope=processing, authenticatorId=test-yubikey-ref, operatorIp=203.0.113.7, operatorId=test-operator-id] INFO c.y.c.l.AuditContextPropagationTest - text-slot-parity-probe Structured JSON Format ------------------------ Using this format, every event becomes a single valid JSON line with Elastic Common Schema (ECS) field names, using the ECS field reference. To enable the structure JSON format, set the ``LOG_FORMAT`` as follows: .. code-block:: logging: structured: format: console: ecs With ``LOG_FORMAT=ecs``, every statement is represented as a single valid JSON line in ECS field names as in the example below. Example ~~~~~~~~~~ The following is an example of the audit log for a single credential request, created through the FIDO Connector integration, and completed by the scheduled job. Each event is one line of JSON, shown expanded here. Every line also carries ``log.logger``, ``process``, ``service``, ``ecs`` and ``schemaVersion`` (shown on the first event only). .. note:: It is recommended to use the “INFO” level for the audit trail. This will reconstruct a full credential request lifecycle end-to-end, without modifying any existing message text. .. code-block:: JSON { "@timestamp": "2026-08-10T09:14:02.331Z", "log": { "level": "INFO", "logger": "com.yubico.credentialservices.services.v2.CreateCredentialRequestV2" }, "process": { "pid": 1, "thread": { "name": "http-nio-8080-exec-1" } }, "service": { "name": "yubico-fido-connector", "version": "2.1.0", "environment": "production" }, "message": "Credential request created", "traceId": "5d0e7a14", "opOrigin": "request", "scope": "creation", "credentialRequestId": "cr-7781", "eventType": "credential_request.created", "initiatorType": "integration", "ecs": { "version": "8.11" }, "schemaVersion": "1" } { "@timestamp": "2026-08-10T10:00:00.008Z", "log": { "level": "INFO" }, "message": "Job started", "traceId": "9b31f0c2", "jobName": "process-credential-requests-v2", "opOrigin": "cron_job", "scope": "processing", "eventType": "job.started" } { "@timestamp": "2026-08-10T10:00:01.442Z", "log": { "level": "INFO" }, "message": "Processing V2 credential request cr-7781", "traceId": "9b31f0c2", "jobName": "process-credential-requests-v2", "opOrigin": "cron_job", "scope": "processing", "credentialRequestId": "cr-7781", "eventType": "credential_request.processing_started" } { "@timestamp": "2026-08-10T10:00:01.907Z", "log": { "level": "INFO" }, "message": "Processing authenticator", "traceId": "9b31f0c2", "jobName": "process-credential-requests-v2", "opOrigin": "cron_job", "scope": "processing", "credentialRequestId": "cr-7781", "authenticatorId": "auth-204", "operatorId": "ta-5521", "operatorEmail": "enrollment-admin@example.com", "operatorIp": "203.0.113.10", "operatorSource": "enrollment_suite", "eventType": "authenticator.processing_started" } { "@timestamp": "2026-08-10T10:00:02.615Z", "log": { "level": "INFO" }, "message": "Credential registered", "traceId": "9b31f0c2", "jobName": "process-credential-requests-v2", "opOrigin": "cron_job", "scope": "processing.activation", "credentialRequestId": "cr-7781", "authenticatorId": "auth-204", "operatorId": "ta-5521", "operatorEmail": "enrollment-admin@example.com", "operatorIp": "203.0.113.10", "operatorSource": "enrollment_suite", "credentialId": "cred-9930", "eventType": "credential.registered", "idpId": "entraid" } { "@timestamp": "2026-08-10T10:00:03.104Z", "log": { "level": "INFO" }, "message": "Credential activated", "traceId": "9b31f0c2", "jobName": "process-credential-requests-v2", "opOrigin": "cron_job", "scope": "processing.activation", "credentialRequestId": "cr-7781", "authenticatorId": "auth-204", "operatorId": "ta-5521", "operatorEmail": "enrollment-admin@example.com", "operatorIp": "203.0.113.10", "operatorSource": "enrollment_suite", "credentialId": "cred-9930", "eventType": "credential.activated", "outcome": "success", "idpId": "entraid" } { "@timestamp": "2026-08-10T10:00:03.550Z", "log": { "level": "INFO" }, "message": "PIN sent for YubiKey auth-204", "traceId": "9b31f0c2", "jobName": "process-credential-requests-v2", "opOrigin": "cron_job", "scope": "processing.delivery", "credentialRequestId": "cr-7781", "authenticatorId": "auth-204", "operatorId": "ta-5521", "operatorEmail": "enrollment-admin@example.com", "operatorIp": "203.0.113.10", "operatorSource": "enrollment_suite", "eventType": "pin.delivered", "outcome": "success" } { "@timestamp": "2026-08-10T10:00:03.998Z", "log": { "level": "INFO" }, "message": "V2 credential request cr-7781 finished as complete", "traceId": "9b31f0c2", "jobName": "process-credential-requests-v2", "opOrigin": "cron_job", "scope": "processing", "credentialRequestId": "cr-7781", "eventType": "credential_request.completed", "state": "complete", "outcome": "success" } Field Dictionary ~~~~~~~~~~~~~~~~~~~~ **Correlation** .. table:: +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ | Field | Type | Present on | +==========================+========================================================+=====================================================================================================================================================+ || ``traceId`` || string || Every event. A unique ID for any interaction or a background job execution. Retrieved from the ``X-Request-Id`` header when the request sends one. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ || ``jobName`` || string || Background job events. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ || ``opOrigin`` || request / cron_job / realtime || Every event. A job triggered through the ``/operations`` endpoints records request. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ || ``scope`` || creation / processing / activation / delivery / purge || Every event. A phase inside a job is prefixed with the job's phase, for example ``processing.activation``, ``processing.delivery``. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ || ``credentialRequestId`` || string || All events relating to a credential request. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ || ``authenticatorId`` || string || Authenticator-level and credential-level events. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ || ``credentialId`` || string || Credential-level events. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ || ``shipmentId`` || string || Shipment events. | +--------------------------+--------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+ **Event** .. table:: +-----------------------------+-----------------------------------------------+---------------------------------------------+ | Field | Type | Description | +=============================+===============================================+=============================================+ || ``eventType`` || string || Stable identifier for the event. | +-----------------------------+-----------------------------------------------+---------------------------------------------+ || ``outcome`` || ``success`` / ``failure`` / ``skipped`` || | +-----------------------------+-----------------------------------------------+---------------------------------------------+ || ``errorKind`` || ``api`` / ``idp`` / ``ye`` / ``general`` || Classification of a failure. | +-----------------------------+-----------------------------------------------+---------------------------------------------+ || ``idpId`` || string || Identity provider instance involved. | +-----------------------------+-----------------------------------------------+---------------------------------------------+ || ``initiatorType`` || ``integration`` / ``realtime`` / ``system`` || Where a credential request was initiated. | +-----------------------------+-----------------------------------------------+---------------------------------------------+ || ``state / previousState`` || string || State of the request or authenticator. | +-----------------------------+-----------------------------------------------+---------------------------------------------+ **Identity** .. table:: +-------------------------+-----------------------------------+-----------------------------------------------------+ | Field | Type | Description | +=========================+===================================+=====================================================+ || ``operatorId`` || string || Processing phase - the Enrollment Admin. | +-------------------------+-----------------------------------+-----------------------------------------------------+ || ``operatorEmail`` || string || Processing phase. | +-------------------------+-----------------------------------+-----------------------------------------------------+ || ``operatorIp`` || string || Processing phase. | +-------------------------+-----------------------------------+-----------------------------------------------------+ || ``operatorSource`` || string || Identity assertion, for example enrollment-suite. | +-------------------------+-----------------------------------+-----------------------------------------------------+ The operator fields are set per authenticator, so that every event inside that authenticator's processing carries them, including credential and PIN events. **W4 coverage** .. table:: +---------+-------------------------------------------------------------------------------------------+ | W4 | Fields | +=========+===========================================================================================+ || Who || ``operatorId`` / ``operatorEmail`` / ``operatorIp`` / ``operatorSource`` at processing. | +---------+-------------------------------------------------------------------------------------------+ || What || ``eventType``, ``outcome``, ``state / previousState``, ``errorKind`` | +---------+-------------------------------------------------------------------------------------------+ || When || ``@timestamp`` | +---------+-------------------------------------------------------------------------------------------+ || Where || ``service.name``, ``service.version``, ``service.environment``, ``idpId``, ``opOrigin`` | +---------+-------------------------------------------------------------------------------------------+ Event Catalogue ~~~~~~~~~~~~~~~~~~~~ **Creation** .. table:: +-----------------------------------+-----------------------------------------------------+---------------------------------------------------------+ | eventType | Recorded when | Identifiers | +===================================+=====================================================+=========================================================+ || ``credential_request.received`` || A credential request is accepted through the API. || ``credentialRequestId``, ``initiatorType`` | +-----------------------------------+-----------------------------------------------------+---------------------------------------------------------+ || ``credential_request.rejected`` || A creation attempt is refused. || ``initiatorType``, ``errorKind``, ``outcome=failure`` | +-----------------------------------+-----------------------------------------------------+---------------------------------------------------------+ **Processing** .. table:: +---------------------------------------------+--------------------------------------------------------------------------+---------------------------------------------------------------+ | eventType | Recorded when | Identifiers | +=============================================+==========================================================================+===============================================================+ || ``credential_request.processing.started`` || The FIDO Connector begins processing a request. || ``credentialRequestId``, ``traceId``, ``jobName`` | +---------------------------------------------+--------------------------------------------------------------------------+---------------------------------------------------------------+ || ``credential_request.skipped`` || The request is in a state that requires no action. || ``credentialRequestId``, ``state``, ``outcome=skipped`` | +---------------------------------------------+--------------------------------------------------------------------------+---------------------------------------------------------------+ || ``credential_request.cancelled`` || The request was cancelled upstream and is marked as cancelled locally. || ``credentialRequestId``, ``previousState`` | +---------------------------------------------+--------------------------------------------------------------------------+---------------------------------------------------------------+ || ``credential_request.completed`` || Credential processing finishes. || ``credentialRequestId``, ``state``, ``outcome`` | +---------------------------------------------+--------------------------------------------------------------------------+---------------------------------------------------------------+ || ``credential_request.failed`` || Credential processing fails. || ``credentialRequestId``, ``errorKind``, ``outcome=failure`` | +---------------------------------------------+--------------------------------------------------------------------------+---------------------------------------------------------------+ **Authenticator and credential** .. table:: +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ | eventType | Recorded when | Identifiers | +========================================+======================================================================+============================================================================================================================+ || ``authenticator.processing.started`` || Processing work begins for an authenticator. || ``credentialRequestId``, ``authenticatorId``, ``operatorId``, ``operatorEmail``, ``operatorIp``, ``operatorSource`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ || ``authenticator.skipped`` || The authenticator is already in a final or in-flight state. || ``credentialRequestId``, ``authenticatorId``, ``state``, ``outcome=skipped`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ || ``authenticator.completed`` || All credentials for the authenticator are resolved. || ``credentialRequestId``, ``authenticatorId``, ``state``, ``outcome`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ || ``authenticator.failed`` || Processing of the authenticator has failed. || ``credentialRequestId``, ``authenticatorId``, ``errorKind``, ``outcome=failure`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ || ``credential.outcomepkcco_fetch`` || Creation options are fetched from the IdP (Real-time Connectivity) || ``credentialRequestId``, ``authenticatorId``, ``credentialId``, ``idpId`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ || ``credential.registered`` || A credential is registered with the identity provider. || ``credentialRequestId``, ``authenticatorId``, ``credentialId``, ``idpId`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ || ``credential.activated`` || A credential becomes active. || ``credentialRequestId``, ``authenticatorId``, ``credentialId``, ``idpId``, ``outcome=success`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ || ``credential.failed`` || Credential activation fails. || ``credentialRequestId``, ``authenticatorId``, ``credentialId``, ``idpId``, ``state``, ``errorKind``, ``outcome=failure`` | +----------------------------------------+----------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+ **PIN delivery** .. table:: +----------------------------+-------------------------------------------------------------------------------+-------------------------------------------------------------+ | eventType | Recorded when | Identifiers | +============================+===============================================================================+=============================================================+ || ``pin.delivered`` || A PIN is sent for an authenticator, or skipped because it was already sent. || ``credentialRequestId``, ``authenticatorId``, ``outcome`` | +----------------------------+-------------------------------------------------------------------------------+-------------------------------------------------------------+ || ``pin.resend_requested`` || A PIN resend is requested. || ``credentialRequestId`` | +----------------------------+-------------------------------------------------------------------------------+-------------------------------------------------------------+ **Background jobs** .. table:: +--------------------+------------------------------------------------------+-----------------------------------------------------------------------------------+ | eventType | Recorded when | Identifiers | +====================+======================================================+===================================================================================+ || ``job.started`` || A scheduled or manually triggered job begins. || ``traceId``, ``jobName`` | +--------------------+------------------------------------------------------+-----------------------------------------------------------------------------------+ || ``job.finished`` || The scheduled or manually triggered job completes. || ``traceId``, ``jobName``, ``outcome``, ``processed``, ``failed`` | +--------------------+------------------------------------------------------+-----------------------------------------------------------------------------------+ || ``data.purged`` || Records are deleted by a retention job. || ``traceId``, ``jobName``, ``recordType``, ``deletedCount``, ``retentionCutoff`` | +--------------------+------------------------------------------------------+-----------------------------------------------------------------------------------+ **Note:** * ``jobName`` is one of ``process-credential-requests-v1``, ``process-credential-requests-v2``, ``-shipments-v1``, ``data-cleanup-v1``, ``purge-credential-requests-v1``. * ``recordType`` is one of ``credential_request``, ``pending_credential_request``, ``shipment``, ``pending_shipment``. **Shipments** .. table:: +-----------------------------------+-------------------------------------------------+------------------------------------------------------+ | eventType | Recorded when | Identifiers | +===================================+=================================================+======================================================+ || ``shipment.processing_started`` || A shipment processing begins. || ``shipmentId``, ``traceId`` | +-----------------------------------+-------------------------------------------------+------------------------------------------------------+ || ``shipment.completed`` || A shipment processing successfully completes. || ``shipmentId``, ``outcome=success`` | +-----------------------------------+-------------------------------------------------+------------------------------------------------------+ || ``shipment.failed`` || A shipment processing fails. || ``shipmentId``, ``errorKind``, ``outcome=failure`` | +-----------------------------------+-------------------------------------------------+------------------------------------------------------+ || ``shipment.deleted`` || A shipment is removed by a retention job. || ``shipmentId``, ``traceId`` | +-----------------------------------+-------------------------------------------------+------------------------------------------------------+