Appendix: Audit Event Correlation
Correlation by identifier Field
identifier FieldTo 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 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
traceId FieldAudit 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:
{
//...
"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
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:
{
// ...
"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"
]
}
// ...
],
// ...
}Last updated