Appendix: Audit Event Correlation#

Correlation by `identifier` Field#

To correlate events within a single service for a request, you can use the identifier field; such as, to correlate the request-authorized and the various access request/grant/denial lifecycle events.

Although, starting in 2.2.0, you can also correlate the these events using the OpenTelemetry traceId field, the identifier field may be preferred as as the identifier field is managed by ESS whereas the traceId is subject to how the client specifies the traceId for its requests.

OpenTelemetry `traceId` Field#

Starting in 2.2.0, audit messages include the client-specified OpenTelemetry traceId (along with other OpenTelemetry data) in the instrument field. This field may be used to correlate messages across services.

For example, if a start app specifies a traceId for its start flow (i.e., user registration to get a WebID and a Pod), you can use this client-specified traceId value to correlate the events associated with that start flow:

Note

In the example messages below, various fields have been omitted for clarity/brevity.
Correlation by traceId may not be suitable for audit trail purposes as the traceId is managed by the client.

{
   //...
   "name" : "webid-created",
   "summary" : "WebId was created",
   //...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://id.example.com/owliverowner",
         "name" : "owliverowner"
      }
   ],
   "object" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "PersonalProfileDocument"
         ]
      }
   ],

   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "f59408a78e40f5a8",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "fafb4c391e0d5189",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "5244408d0f56431ba727cbdd4c177d61",
   "published" : "2023-12-06T01:57:27.835491323Z"
}

{
   //...
   "name" : "provisioned-pod-access-control",
   "summary" : "Provisioned Pod access control",
   //...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://provision.example.com/"
      }
   ],
   "object" : [ ],
   "instrument" : [
      {
         "type" : [
            "Storage"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/"
      },
      {
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ],
         "spanId" : "97e22fca05e84103",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "163e168f726abcce"
      }
   ],
   "result" : [ ],
   "identifier" : "6c1ce07ec6b54ee09c21486d4366b277",
   "published" : "2023-12-06T01:57:30.672004Z"
}


{
   // ...
   "name" : "resource-created",
   "summary" : "Resource has been created",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "accessControl" : [
            "https://authorization.example.com/1fb6b127afb9458b9cf7d405d1c47dde"
         ],
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/"
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "5a0fbc0f4aeb0c8f",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "15e8a1b3cd149acf",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:30.736939618Z"
}

{
   // ...
   "name" : "acr-created",
   "summary" : "ACR has been created",
   // ...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://provision.example.com/"
      }
   ],
   "object" : [
      {
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/"
      },
      {
         "type" : [
            "AccessControlResource"
         ],
         "id" : "https://authorization.example.com/1fb6b127afb9458b9cf7d405d1c47dde"
      }
   ],
   "instrument" : [
      {
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ],
         "spanId" : "5637a071550bc999",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "91d7a028b1bdb074"
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "83ceb448725e4e3c8bef7576e941e957",
   "published" : "2023-12-06T01:57:31.444925619Z"
}

{
   // ...
   "name" : "resource-created",
   "summary" : "Resource has been created",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "generated" : "50ece2b2-f46b-4dca-90cb-3a42ee07f6fc",
         "accessControl" : [
            "https://authorization.example.com/0e7c68f9354742a9bbc29da64dcd14c8"
         ],
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/profile"
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "3cdec0dcecd7538d",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "996f99df65b6ebc2",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:31.555962708Z"
}

{
   // ...
   "name" : "acr-created",
   "summary" : "ACR has been created",
   // ...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://provision.example.com/"
      }
   ],
   "object" : [
      {
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/profile"
      },
      {
         "type" : [
            "AccessControlResource"
         ],
         "id" : "https://authorization.example.com/0e7c68f9354742a9bbc29da64dcd14c8"
      }
   ],
   "instrument" : [
      {
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ],
         "spanId" : "5b515094a69aaa03",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "ce6251cc1b12dbda"
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "dccd5eb3957d40dcb9974081d17b82fe",
   "published" : "2023-12-06T01:57:31.663061454Z"
}
{
   // ...
   "name" : "resource-updated",
   "summary" : "Resource timestamp has been updated",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "Resource"
         ]
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "3b5ec01c1bbf7cc2",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "996f99df65b6ebc2",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:31.743024556Z"
}

{
   // ...
   "name" : "pod-provisioned",
   "summary" : "Pod provisioned",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "Storage"
         ]
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "36cbd6bd8488a2d9",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "765195098215788f",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:31.782133926Z"
}

For more information on OpenTelemetry, refer to the OpenTelemetry documentation.

Correlation by Application-Defined Property#

Starting in 2.2, ESS can propagate application-defined metadata/properties sent in client requests to include in associated log messages, associated audit events, and associated response to the request.

Depending upon the configuration, ESS audit events can include the application-defined request metadata in the instrument field:

Note

In the example messages below, various fields have been omitted for clarity/brevity.
Correlation by client defined properties may not be suitable for audit trail purposes as these properties are subject to how the client manages these properties as well as the ESS configuration.

{
   // ...
   "name" : "request-authorized",
   "summary" : "Request has been authorized",
   // ...
   "instrument" : [
      // ...
      {

        "name" : "Application-Defined Request Metadata",
        "items": [
           {
              "mediaType" : "text/plain",
              "name" : "x-correlation-id",
              "content" : "2049875809728750827498245084"
           },
           {
              "mediaType":"text/plain",
              "name":"my-client-version",
              "content":"1.0.3"
           }
        ],
        "type":[
           "urn:uuid:1a05e301-4013-40c9-bae7-5d719b7151c8"
        ]
      }
      // ...
   ],
   // ...
}
{
   // ...
   "name" : "access-request-created",
   "summary" : ""Access Request has been created",

   "instrument" : [
      // ...
      {

        "name" : "Application-Defined Request Metadata",
        "items": [
           {
              "mediaType" : "text/plain",
              "name" : "x-correlation-id",
              "content" : "2049875809728750827498245084"
           },
           {
              "mediaType":"text/plain",
              "name":"my-client-version",
              "content":"1.0.3"
           }
        ],
        "type":[
           "urn:uuid:1a05e301-4013-40c9-bae7-5d719b7151c8"
        ]
      }
      // ...

   ],
   // ...
 }

Appendix: Audit Event Correlation#

Correlation by identifier Field#

OpenTelemetry traceId Field#

Correlation by Application-Defined Property#

Correlation by `identifier` Field#

OpenTelemetry `traceId` Field#