Ctrl+K
Archived docs. ESS 2.0 has reached end of life.

Auditing#

Changed in version 2.0.

ESS services support the auditing of their activities.

Audit Events#

The following events are audited:

Services

Event Name

Notes

All Audited Services [1]

  • service-started

  • service-shutdown

Service Startup/Shutdown.

Authorization Service

  • acr-created

  • acr-updated

  • acr-deleted

  • provisioned-pod-access-control

  • deprovisioned-pod-access-control

ACR Lifecycle events.

Pod Storage Service

  • resource-created

  • resource-updated

  • resource-deleted

Resource Lifecycle events.

Pod Provision Service

  • pod-provisioned

Pod Provisioning.

Solid OIDC Broker Service

  • openid-backend-idp-login

  • openid-token-requested

  • openid-authorization-initialized

Authentication/Authorization flow.

UMA Service

  • uma-token-created

UMA Grant Flow.

WebID Service

  • webid-created

  • webid-updated

  • webid-deleted

WebID Profile events.

Audit Event Message Internal Format#

Internally, ESS’ audit event messages are in RDF and serialized as ActivityStreams 2.0 JSON-LD documents:

Note

Although the following document shows all possible fields for an event message, the specific events determine which fields appear.

{
   "@context":[
      "https://www.w3.org/ns/activitystreams",
      "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id":"<UUID of the event>",
   "type": [ "Activity", <type2>,... ],
   "name":"<event name>",
   "summary": "<event description>",
   "generator": <JSON document identifying the software producing the event>,
   "actor": [ <JSON document identifying the actor associated with the event>, ... ],
   "object": [ <JSON document identifying the object associated with the event>, ... ],
   "instrument": [ <JSON document identifying the client/application associated with the event>, ... ],
   "published": "<datetime>",
   "identifier":"<identifier to use for correlated events>"
}

@context

Specifies the JSON-LD contexts.

id

Universally Unique IDentifier (UUID) for the event.

type

An array of event types; e.g., [ "Activity", "Create" ]

name

Name that denotes the event; e.g., service-started, openid-backend-idp-login, resource-created, etc.

See Audit Events for a list of audited events names.

summary

Short description associated with the message name.

generator

JSON document identifying the software (e.g., service) producing the event. For example, the generator for a Pod provision event:

"generator": {
   "id": "urn:ess:<service hostname>#<processId>"
   "type": ["SoftwareApplication"],
   "name": "<application name>",
   "qualifiedAssociation": "<processId>",
   "wasAssociatedWith": "<service hostname>"
}

actor

An array of JSON documents that identify the agents associated with the event. For example, for a Pod provision event:

"actor": [
   { "id": "https://id.example.com/someusername" }
]

object

An array of JSON documents that identify the objects associated with the event. For example, for a Pod provision event:

"object": [
   { "type": "Storage", "id": "<PodURL>" }
]

instrument

An array of JSON documents that identify the clients associated with the event, such as the client identifier for a token request event.

"instrument": [ {
   "id": "<Client Identifier>"
} ]

published

The timestamp of the event.

identifier

Identifier to use for correlated events.

Audit Event Examples#

Example: service-started#

{
   "@context":[
     "https://www.w3.org/ns/activitystreams",
     "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id":"urn:uuid:1633a5bb-1126-4acc-ae3f-e0b60e93f2bc",
   "type":["Activity", "Start"],
   "name":"service-started",
   "summary":"Service inrupt-storage-postgres-s3 has started up",
   "generator": [{
      "type":["SoftwareApplication"],
      "name":"inrupt-storage-postgres-s3",
      "qualifiedAssociation":"process-id:197",
      "wasAssociatedWith":"ess-pod-storage-84648cfc95-qs865",
   }],
   "published":"2022-01-26T10:25:28.105396Z",
   "identifier":"e9bd486d68b9dba599563bf899bbff0"
}

Example: openid-authorization-initialized#

{
   "@context":[
     "https://www.w3.org/ns/activitystreams",
     "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id": "urn:uuid:1cd351a8-b725-4c61-aa50-0000000001",
   "type": ["Activity", "Delegation", "AuthorizationCodeFlow"],
   "name": "openid-authorization-initialized",
   "summary": "Initialized an authorization code flow",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-openid-postgres",
      "qualifiedAssociation":"process-id:197",
      "wasAssociatedWith":"ess-openid-postgres-84648cfc95-qs865",
   },
   "object": [{
      "name": "redirect_uri",
      "id": "https://someapp.example.com/callback"
   }],
   "instrument": [{
      "id": "1UqavEk9vYmx7BXq-rXFrJ6JfetldosysS9gJMTaecE"
   }],
   "published": "2022-01-27T09:40:40.206960Z",
   "identifier": "7ecf97606eca1cea4743ce87cd17f20b"
}

Example: openid-backend-idp-login#

{
   "@context":[
     "https://www.w3.org/ns/activitystreams",
     "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id": "urn:uuid:f1041b05-c5cc-41ab-9565-0000000002",
   "type": ["Activity", "Delegation", "AuthorizationCodeFlow"],
   "name": "openid-backend-idp-login",
   "summary": "Agent has successfully logged in through backend IdP",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-openid-postgres",
      "qualifiedAssociation":"process-id:197",
      "wasAssociatedWith":"ess-openid-postgres-84648cfc95-qs865"
   },
   "actor": [{
      "id": "https://id.example.com/someusername"
   }],
   "object": [{
       "name": "redirect_uri",
       "id": "https://someapp.example.com/callback"
   }],
   "instrument": [{
      "id": "1UqavEk9vYmx7BXq-rXFrJ6JfetldosysS9gJMTaecE"
   }],
   "published":"2022-01-27T09:40:40.226187Z",
   "identifier":"facfabbe802c568f302a81e99f27632d"
}

Example: openid-token-requested#

Tip

The openid-token-requested occurs for both new and refresh token requests. The summary field specifies whether the event is for a new or a refresh token.

{
   "@context":[
     "https://www.w3.org/ns/activitystreams",
     "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id":"urn:uuid:f8a16c67-4229-4295-9b81-0000000003",
   "type":["Activity", "Delegation", "AuthorizationCodeFlow"],
   "name":"openid-token-requested",
   "summary":"A new token was requested via the authorization code flow",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-openid-postgres",
      "qualifiedAssociation":"process-id:45",
      "wasAssociatedWith":"ess-openid-postgres-84648cfc95-qs865"
   },
   "actor": [{
      "id": "https://id.example.com/someuser"
   }],
   "object": [{
      "name": "authorization_code",
      "scope": "openid webid"
   }],
   "instrument": [{
      "id": "1UqavEk9vYmx7BXq-rXFrJ6JfetldosysS9gJMTaecE"
   }],
   "published":"2022-01-27T09:40:40.466021Z",
   "identifier":"108bc9cdf0c2781ed143f2de22020d83"
}

Example: pod-provisioned#

{
   "@context": [
      "https://www.w3.org/ns/activitystreams",
      "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id": "urn:uuid:579668c1-4e14-4fad-aea3-0000000004",
   "type": ["Activity", "Create"],
   "name": "pod-provisioned",
   "summary": "Pod provisioned",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-pod-provision-postgres-s3",
      "qualifiedAssociation":"process-id:74",
      "wasAssociatedWith":"ess-pod-provision-84648cfc95-qs865"
   },
   "actor": [{
      "id": "https://id.example.com/someuser"
   }]
   "object": [{
      "type": "Storage",
      "id": "https://storage.example.com/51defe94/"
   }],
   "published": "2022-01-26T08:37:05.863044Z",
   "identifier": "2f40b052fea8f3bdbc84edefa58cf080"
}

Example: resource-created#

{
   "@context": [
      "https://www.w3.org/ns/activitystreams",
      "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id": "urn:uuid:579668c1-4e14-4fad-aea3-0000000005",
   "type": ["Activity", "Create"],
   "name": "resource-created",
   "summary": "Resource has been created",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-storage-postgres-s3",
      "qualifiedAssociation":"process-id:22",
      "wasAssociatedWith":"ess-pod-storage-84648cfc95-qs865"
   },
   "actor": [{
      "id": "https://id.example.com/someuser"
   }],
   "object": [{
      "type": "Resource",
      "id": "https://storage.example.com/51defe94/foo",
      "generated": "93b242492865407sa4d30247b2d64d00",
      "accessControl": "https://authorization.example.com/83b242392"
   }],
   "published": "2022-01-26T08:37:05.863044Z",
   "identifier": "14bce501481a67fbf0383f3f4359085a"
}

Example: resource-updated#

{
   "@context": [
      "https://www.w3.org/ns/activitystreams",
      "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id": "urn:uuid:579668c1-4e14-4fad-aea3-0000000006",
   "name": "resource-updated",
   "type": ["Activity", "Update"],
   "summary": "Resource has been updated",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-storage-postgres-s3",
      "qualifiedAssociation":"process-id:77",
      "wasAssociatedWith":"ess-pod-storage-84648cfc95-qs865"
   },
   "actor": [{
      "id": "https://id.example.com/someuser"
   }],
   "object": [{
      "type": "Resource",
      "id": "https://storage.example.com/51defe94/foo",
      "generated": "93b242492865407sa4d30247b2d64d11",
      "invalidated": "93b242492865407sa4d30247b2d64d00",
      "accessControl": "https://authorization.example.com/83b242392b"
   }],
   "identifier": "2c5fc3e4bdfe866e2864059c427d96de",
   "published": "2022-01-26T08:37:05.863044Z"
}

Example: resource-deleted#

{
   "@context": [
      "https://www.w3.org/ns/activitystreams",
      "https://schema.inrupt.com/audit/v1.jsonld"
   ],
   "id": "urn:uuid:579668c1-4e14-4fad-aea3-0000000007",
   "type": ["Activity", "Delete"],
   "name": "resource-deleted",
   "summary": "Resource has been deleted",
   "published": "2022-01-26T08:37:05.863044Z",
   "generator": {
      "type":["SoftwareApplication"],
      "name":"inrupt-storage-postgres-s3",
      "qualifiedAssociation":"process-id:101",
      "wasAssociatedWith":"ess-pod-storage-84648cfc95-qs865"
   },
   "actor": [{
      "id": "https://id.example.com/someuser",
   }],
   "object": [{
      "type": "Resource",
      "id": "https://storage.example.com/51defe94/foo",
      "invalidated": "93b242492865407sa4d30247b2d64d11",
      "accessControl": "https://authorization.example.com/83b242392b"
   }],
   "identifier": "2c5fc3e4bdfe866e2864059c427d96de"
}

Integration with External Logging Systems#

The ESS Auditing service can log to:

Syslog#

When integrating with Syslog, ESS audit events are converted to Syslog message format:

<priority>version timestamp hostname service processId messageId message

Where:

  • hostname, service, processId and messageId values are taken extracted from the audit event agent field.

  • message is the full ESS audit event in JSON.

For more information, see Integration with Syslog and

Microsoft Sentinel#

When integrating with Microsoft Sentinel, the ESS audit events are converted into a Sentinel-specific format and POST’ed to the Sentinel service.

For more information, see Integration with Sentinel.

On this page