Ctrl+K
Ctrl+K

Release Notes#

ESS 2.2.0 Released 2024-03-19

Audit Event Information Enhancements#

Starting in version 2.2, various Pod related messages now include the associated Pod/actor/client information. That is, Pod related audit events can provide insight into:

  • the agent who performed the action,

  • the client used, and

  • the affected Pod and its data subject.

In previous versions, only a subset of Pod related events provided the agent, client, and Pod root information (in varying combination).

In addition, OpenTelemetry information is now included for all but the service start/shutdown events.

instrument Field#

Pod Information#

Starting in version 2.2, the instrument field for the following events include an element with the Pod information (Pod root url and Pod data subject):

The Pod information element has the following form:

{
   "hasDataSubject" : {
      "id" : "<Pod data subject's WebID>",
      "type" : [
         "https://w3id.org/dpv#DataSubject"
      ],
   },
   "hasStorage" : "<PodURL>",
   "type" : [
      "http://www.w3.org/2004/02/skos/core#Concept"
   ]
}

The Pod data subject refers to the agent who created the Pod.

See also:

Client Identifier Information#

Starting in version 2.2, the instrument field for the following events include an element with the client information:

The client information element has the following form:

{
   "summary" : "Client identifier",
   "id" : "<Client ID>"
}

In earlier versions, the pod provisioned event, the resource lifecycle events, and the access request/grant/denial lifecycle events did not include client identifier information. Although, for the access requests/grant/denial lifecycle events, the associated request-authorized events included the client information.

OpenTelemetry Information in Events#

Starting in version 2.2, the instrument field includes OpenTelemetry element for most events [1]; the service-start and service-shutdown events do not include the OpenTelemetry element.

The OpenTelemetry element has the following form:

{
   "name" : "OpenTelemetry Span Context",
   "type" : [
      "SpanContext"
   ],
   "isSampled" : false,
   "spanId" : "<spanId>",
   "traceId" : "<traceId>"
}

OpenTelemetry information can be used to correlate messages associated with a request.

In version 2.1.5+, OpenTelemetry information was only included in Access Grant service events.

Application-Defined Metadata in Events#

Starting in version 2.2, the instrument field can include application-defined properties element.

The element for application-defined properties has the following form:

{
   "type": [
      "urn:uuid:1a05e301-4013-40c9-bae7-5d719b7151c8"
   ],
   "items": [
      {
         "content": "<value>",
         "name": "<property name>",
         "mediaType": "text/plain"
      },
      // ...
   ],
   "name": "Application Defined Request Metadata"
}

See also Application-Defined Metadata Propagation.

object Field#

Pod Information#

Starting in version 2.2, the object field includes Pod information for query events.

The Pod information object has the following form:

{
   "type" : [
      "Storage"
   ],
   "id" : "https://storage.example.com/<Pod root container>/"
}

In earlier versions, the object field for query events did not include Pod information.

Resource Information#

Starting in version 2.2, the object field for access requests/grants/denial lifecycle events include an element that identifies the affected Pod resource.

The resource information element has the following form:

{
   "type" : [
      "Resource"
   ],
   "id" : "https://storage.example.com/ad3b.../some/resource"
}

actor field#

Starting in version 2.2, the actor field for the access control resource (ACR) events is populated:

  • acr_created

  • acr_updated

  • acr_deleted

  • provisioned-pod-access-control

  • deprovisioned-pod-access-control.

In earlier versions, the actor field for these events are empty actor: [].

Audit Event Field Changes#

actor Field: type#

To provide clarification information, the type field has been added to the actor objects. The newly added type has the value "Agent":

"actor" : [
   {
      "name" : "owliverowner",
      "type" : [
         "Agent"
      ]
   }
]

"actor" : [
   {
      "id" : "https://id.example.com/owliverowner",
      "type" : [
         "Agent"
      ]
   }
],

In earlier versions, the id field and name field may appear without a clarifying type.

instrument Field: summary#

To provide clarification information, the summary field has been added to instruments objects that contain the id of the application associated with the event. The newly added summary has the value "Client identifier":

"instrument" : [
   {
      "summary" : "Client identifier",
      "id" : "https://myApp.example.com/appids/app.jsonld"
   },

In earlier versions, instruments objects with the id of the application may include:

  • the id field without any clarifying field or

  • the id field with "name" : "Client Application".

With the change in 2.2, the id field is paired with the summary field.

object Field Changes#

Access Grants: content and mediaType#

Starting in version 2.2, the object for the create access request/grant/denial events contains the created request/grant/denial in a document with:

  • the content field (which contains the access request/grant/denial object as string) and

  • the mediaType field.

For example, for an Access Request creation event:

"object": [
   {
     "content" : "{\"id\":\"https://vc.example.com/vc/79288a3b-7a01-4944-b7e8-c346b2ab49c2\",\"type\":[\"VerifiableCredential\",\"SolidAccessRequest\"], ... }",
     "mediaType": "application/ld+json"
   },
   ...
]

In earlier versions, the object field contained the created access request/grant/denial object directly as an element:

"object": [
   {
      "id": "https://vc.example.com/vc/79288a3b-7a01-4944-b7e8-c346b2ab49c2",
      "type": [
          "VerifiableCredential",
          "SolidAccessRequest"
      ],
      // ...rest of Access Request
   }
]

Pod Resource Lifecycle Events: Remove StorageCreator Object#

Starting in 2.2, Pod resource lifecycle events events (i.e., CRUD events) no longer include a StorageCreator object. Instead, the information is now in the hasDataSubject field in the instrument field. See the Pod Information section in the Audit Event Information Enhancements section.

ACR Provisioned Events: Remove Storage Object#

Starting in 2.2, provisioned-pod-access-control events no longer include a Storage object. Instead, the information is now included in the instrument field. See the Pod Information section in the Audit Event Information Enhancements section.

Audit: Logging to sysout#

When logging audit messages to sysout (the default), Auditing service uses the shared ESS logging components (available starting in 2.2), which use JSON as the default formatting for log messages. As such, starting in 2.2, audit messages logged to sysout are contained in the auditEvent field of the log message. The audit event message itself (i.e., the auditEvent value in v2.2+) is serialized as a JSON-LD documents (as in earlier releases).

See also Logging Enhancements.

Audit Enricher#

Starting in 2.2, ESS includes an Audit Enricher that populates various Pod related audit messages with the associated Pod information.

As part of this change, ESS adds a new Kafka messaging topic. As such, an additional input is required in kafka-credentials.env file. As with all ESS releases/upgrades, review the contents of your inputs/ folder for changes per versions.

Pod System Information Migration#

As part of the rollout of ESS 2.2.0, a new Migration service is used to to migrate existing Pods over to a new structure.

The Migration service runs as a Kubernetes Cron Job. It runs in the background and will not take ESS offline to complete the migration.

While the migration is running, an Operator can observe using logs and metrics and will be able to see when it has been completed.

Once the migration has been completed, the Migration Cron Job will idle and the operator can safely remove it from the deployment.

See also:

Access Requests/Grants#

Access Grant Usage Enabled by Default#

Starting in version 2.2, when ESS creates a new Pod, ESS initializes the Pod with policies that enable the use of Access Grants for that Pod..

Note

A Pod’s initial Policies are set when the Pod is provisioned. For deployments upgrading to 2.2, this change does not affect existing Pods.

See also:

Audit Events#

Starting in version 2.2, access grant services issues audit events for access request/grant/denial lifecycle events.

Note

Access Request/Grant/Denial lifecycle events are also available starting in 2.1.5 (i.e., the feature is backported to 2.1.5). However, the 2.1.5 events do not include the various Pod/agent/client information enhancements that are available starting in 2.2.

See also:

Default Duration#

Starting in version 2.2, the Access Grant service uses P365D (365 days) as the default duration for issued access requests and grants. As such, starting in v2.2, all issued access requests/grants have an expiration date.

To override this value, see INRUPT_VC_MAX_DURATION.

Earlier versions of the service does not use a default duration value. As such, to determine the expiration date, earlier versions require that either the payloads specify an expiration date and/or the INRUPT_VC_MAX_DURATION to be set.

Remove Reactivation of Access Requests/Grants#

Starting in version 2.2, the Access Grant service no longer allows reactivation (“unrevoking”) [2] of revoked access requests and grants. That is, you can no longer specify "credentialStatus.status": 0 in the payload to the /status Endpoint:

{
   "credentialId": <VC id>,
   "credentialStatus": [
      { "type": "RevocationList2020Status", "status": 0 }   // Disallowed
   ]
}

Instead, once an access request/grant is revoked, initiate a new access request/grant flow. For more information on revoking access requests/grants, see /status Endpoint.

Application-Defined Metadata Propagation#

Starting in 2.2, ESS adds support for application-defined metadata/properties associated with a request; specifically, ESS supports the use of the baggage HTTP header by applications. ESS further expands on this support by providing configuration to add non-baggage request headers to the baggage for propagation within its system.

With ESS’ support application-defined metadata/properties, application-defined metadata can be:

For more detail, see Application-Defined Metadata.

See also OpenTelemetry Support.

Solid OIDC Broker Service#

Default Approval Template UI Changes#

The Solid OIDC Broker Service default approval template:

  • clarifies the description of the requested scopes;

  • no longer displays a default Inrupt logo;

  • no longer displays an About section.

Same as in earlier versions, to customize this template, see Use a Custom Approval Template.

Logging Enhancements#

Starting in 2.2, ESS services [3]:

  • Use shared ESS logging components. The use of shared logging components allow for the log messages to have a more consistent pattern across the ESS services.

  • Use JSON as the default formatting for log messages. [4] The use of JSON format allows for:

  • Include startup configuration in JSON log messages.

  • Supports configurable redaction of JSON log messages.

For more information on logging, see Logging.

General Enhancements/Changes#

OpenTelemetry Support#

Starting in version 2.2, ESS has been instrumented to support OpenTelemetry.

As such, when a log or audit message is associated with a OpenTelemetry span:

  • ESS log messages may include an mdc field that contains OpenTelemetry information. The OpenTelemetry information can be used to correlate messages.

  • ESS audit events may include OpenTelemetry information in the instrument field. The OpenTelemetry information can be used to correlate messages.

ESS also uses OpenTelemetry (specifically, OpenTelemetry Baggage ) to propagate application-defined properties. These properties can be included in:

  • ESS log messages in the requestMetadata field.

  • ESS audit events in the instrument field.

  • ESS’ response to the request.

See Application-Defined Metadata Propagation for more information.

Image Versioning#

Starting in version 2.2, ESS uses three-element version descriptors for its Kubernetes images, corresponding to the release versions(i.e., semantic versions of Major.Minor.Patch); for example docker.software.inrupt.com/inrupt-kustomizer:2.2.0.

As such, to get the latest 2.2 patch version, you must specify the specific patch number.

In previous versions, the image descriptor versions consist of two-elements Major.Minor (e.g., 2.1 to get the latest 2.1 patch version).

Deployment Inputs Changes#

Starting in version 2.2, ESS has the following overlays inputs/ file change(s):

  • Updated input file kafka-credentials.env includes a new configuration INRUPT_KAFKA_AUDITV1EVENTSPRODUCERENCRYPTED_CIPHER_PASSWORD that must be set.

Tip

Always review the contents of the inputs/ folder when performing installation/upgrades.

Patch Releases#

2.2.1#

Released 2024-03-19

Access Grant Service Client Allow Lists#

Starting in 2.2.1, the Access Grant Service changes the client allow list that determine which clients can access the /issue and /status endpoints:

The new configurations must be set for the Access Grant Service to start, and ESS 2.2.1 includes a new overlay inputs file for setting these configurations. See 2.2.1 Deployment Inputs Changes.

Application-Defined Request Metadata Audit Event Name Change#

In audit messages for Application-Defined Request Metadata, update the name to include the hyphen -.

{
   "type": [
      "urn:uuid:1a05e301-4013-40c9-bae7-5d719b7151c8"
   ],
   "items": [
      {
         "content": "<value>",
         "name": "<property name>",
         "mediaType": "text/plain"
      },
      // ...
   ],
   "name": "Application-Defined Request Metadata"
}

In 2.2.0, the name did not contain the hyphen “Application Defined Request Metadata”.

2.2.1 Deployment Inputs Changes#

Starting in version 2.2.1, ESS adds a new overly inputs/ file ess-verifiable-credentials-client-type-allow-list.env for setting Access Grant Service Client Allow Lists. If keeping default values for the Access Grant Service Client Allow Lists, you only need to set INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT in the file.

See also Access Grant Service Client Allow Lists.

Auditing#

Starting in version 2.2.1, ESS no longer includes an rsyslog base. Refer to your company’s policies w.r.t. syslog preferences and practices. In addition, INRUPT_AUDIT_SYSLOG_PROTOCOL default value has changed from TCP to SSL_TCP.

Changelogs#

For changelogs, see 2.2 Changelogs.

On this page