Overview

Every YaaS service potentially deals with personal data. Therefore, the Audit Ingestion service and the Audit Retrieval service enable YaaS services to create appropriate audit logs. These audit logs are easily accessible and unified by the data subjects.

The Audit Ingestion service supports three categories of audit logs:

  • security event logs - logged security events, such as attempts to change address information without sufficient permissions
  • personal data change logs - logged events of any personal data amendments, such as an email address change
  • configuration change logs - logged events of configuration changes, such as assigning a new user to a project

The Audit Ingestion service allows you to create logs in a structured and repeatable manner.


API Reference

/personal-data-changes

Publish logs for personal data changes.

/personal-data-changes

post

Publish a list of changes in personal data as defined in the data protection agreements. The service will make the best effort to publish as much elements in the batch as possible. A partial acceptance of only some elements in the batch can occur, and the response body content must be checked in that case to see which of the elements failed. Note that hybris-user and hybris-user-id headers must not be present in the call.

/configuration-changes

Publish logs for configuration changes. The service will make the best effort to publish as much elements in the batch as possible. A partial acceptance of only some elements in the batch can occur, and the response body content must be checked in that case to see which of the elements failed. Note that hybris-user and hybris-user-id headers must not be present in the call.

/configuration-changes

post

Publish a list of configuration changes that can have business impact.

/security-events

Publish logs for security events. The service will make the best effort to publish as much elements in the batch as possible. A partial acceptance of only some elements in the batch can occur, and the response body content must be checked in that case to see which of the elements failed. Note that hybris-user and hybris-user-id headers must not be present in the call.

/security-events

post

Publish a list of security event.


Security

As a data owner, you are responsible for logging events related to personal data. Those logs must be accessible to the data subject or data controller, for auditing purposes. The Audit Ingestion service enables YaaS services to easily create appropriate audit logs for all considered event categories.

The Audit Ingestion service cannot handle sensitive personal data.


Tutorials

The Audit Ingestion service allows you to create audit log events in the system. The logging pipeline processes audit log events, adding metadata attributes. The system then pushes the logs into the retrieval flow, where they are stored. For more information regarding log retrieval, see the Audit Retrieval service documentation.

Create log events for personal data changes

To create a log for a personal data change event, perform a POST request on the personal-data-changes endpoint. In the body of the request you must provide:

  • source - The identifier of the owner of the object containing the personal data being changed.
  • sourceType - The type of a change source. Supported values are tenant, organization, and account.
  • userId - Optional. Identifies a user that has modified personal data of the dataSubjectId.
  • userType - Optional. Identifies the type of user given in the userId field.
  • objectId - The identifier of the object containing the personal data being changed.
  • objectType - The object type containing the personal data, as defined by the service.
  • dataSubjectId - Identifies a personal data owner.
  • dataSubjectType - The type of a data subject.
  • attributes - All attributes changed by the data change event.
    • name - The name of an attribute for which the value changed. For nested values, use dots to separate the path.
    • oldValue - The previous value of the attribute. Required in case of data change or creation. Must not contain passwords.
    • value - The new value of the attribute. Required in case of data change or creation. Must not contain passwords.
    • operation - The operation performed on the attribute. Supported values are create, change, and delete.
  • serviceBasePath - The base path to the service that contains the personal data to change. Include the organization, service name, and version in the base path. For example: /hybris/account/v1.
  • serviceRegion - The region where the service undergoing the personal data change runs. For example: us.
  • time - The timestamp value. Time of an occurence of the event.
  • reason - Optional. A human readable justification for this personal data change.
Make sure the tuple of serviceRegion, serviceBasePath, objectType, and objectId uniquely identifies an object within the client owner (tenant) scope.

Your log should contain a list of changes in personal data as defined in the data protection agreements.

You can only make the request with a token granted through the Client Credentials Grant. For audit logs with the values organization or account for the sourceType field, a token must be granted for the personalData tenant, which must be subscribed to your service.

Example

[
  {
    "source": "myexampleshop",
    "sourceType": "tenant",
    "userId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
    "objectId": "c34497a9-bc13-4c7b-b80e-af1dfc2ceb0f",
    "objectType": "order",
    "dataSubjectId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
    "dataSubjectType": "yaas-account",
    "attributes": [
      {
        "name": "name",
        "value": "James",
        "operation": "change"
      },
      {
        "name": "address",
        "oldValue": "Other Street 1",
        "value": "Some Street 1",
        "operation": "change"
      }
    ],
    "serviceBasePath": "hybris/account/v1",
    "serviceRegion": "us",
    "time": "2017-05-13T17:30:00.52Z"
  }
]

Create log events for configuration changes

To create a log in the event of a configuration change, perform a POST request on the configuration-changes endpoint. In the body of the request you must provide:

  • source - The identifier of the owner of the object being changed.
  • sourceType - The owner type of the changed object. Supported values are tenant, organization, and account. Example: A change in the shipment provider of an order flow belonging to a project uses tenant, a change of permissions for a member of an organization uses organization.
  • userId - Optional. Identifies a user that has modified the configuration, the hybris-user-id header.
  • userType - Optional. Identifies the type of user given in the userId field.
  • objectId - Identifies the object being changed.
  • objectType - The type of object as defined by the service.
  • attributes - The list of all attributes changed by the data change event, and the associated old and new values.
    • name - The name of the changed attribute. For nested values, use dots to separate the path.
    • value - The new value of the attribute. Should never contain passwords.
    • oldValue - The previous value of the attribute. Should never contain passwords.
    • operation - The operation performed on the attribute. Supported values are create, change, and delete.
  • serviceBasePath - The base path to the service the configuration change concerns. Include the organization, service name, and version in the base path. For example: /hybris/order/v1.
  • serviceRegion - The region where the service undergoing the configuration change runs. For example: us.
  • time - The timestamp value in ISO 8601 format. Example: 2017-05-13T17:30:00.52Z. Time of an occurence of the event.
  • reason - Optional. A human readable justification for this configuration change.
Make sure the tuple of serviceRegion, serviceBasePath, objectType, and objectId uniquely identifies an object within the client owner (tenant) scope.
You can only make the request with a token granted through the Client Credentials Grant. For audit logs with the values organization or account for the sourceType field, a token must be granted for the personalData tenant, which must be subscribed to your service.

Example

[
  {
    "source": "myexampleshop",
    "sourceType": "tenant",
    "userId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
    "objectId": "c34497a9-bc13-4c7b-b80e-af1dfc2ceb0f",
    "objectType": "order",
    "attributes": [
      {
        "name": "amount",
        "oldValue": "120",
        "value": "123",
        "operation": "change"
      },
      {
        "name": "paid",
        "oldValue": "false",
        "value": "true",
        "operation": "change"
      }
    ],
    "serviceBasePath": "hybris/order/v1",
    "serviceRegion": "us",
    "time": "2017-05-13T17:30:00.52Z"
  }
]

Security-relevant events comprise all those events which may impact the confidentiality, the integrity, or the availability of the system. For example, failed logins or failed authorization checks. Log security events at the tenant, organization, and account level. To create a log for a security event, perform a POST request on the security-events endpoint.

In the body of the request you must provide:

  • source - Identifies the owner of the object the security event refers to.
  • sourceType - The owner type of the system the security event refers to. Supported values are tenant, organization, and account.
  • userId - Optional. The user that created the security event. For example, the value of the hybris-user-id header.
  • userType - Optional. Identifies the type of user given in the userId field.
  • clientIp - The IP address of the original client trying to access or amend personal data.
  • data - The event data.
    • message - The string value describing the security event. The minimal required value is an empty string: "".
  • serviceBasePath - The base path to the service for which you create the security event. Include the organization, service name, and version in the base path. For example: /hybris/order/v1.
  • serviceRegion - The region where the service for which you create the security event runs. For example: us.
  • time - The timestamp value in ISO 8601 format. Example: 2017-05-13T17:30:00.52Z. Time of an occurence of the event.
  • reason - Optional. A human readable justification for this security event change.
You can only make the request with a token granted through the Client Credentials Grant. For audit logs with the values organization or account for the sourceType field, a token must be granted for the personalData tenant, which must be subscribed to your service.

Example

[
  {
    "source": "hybris",
    "sourceType": "organization",
    "userId": "00453A0A-19ED-1ED6-A1DF-054B3B9A5F4F",
    "clientIp": "10.32.2.2",
    "data": {
      "message": "Unauthorized access to database"
    },
    "serviceBasePath": "hybris/order/v1",
    "serviceRegion": "us",
    "time": "2017-05-13T17:30:00.52Z"
  }
]


Security

As a data owner, you are responsible for logging events related to personal data. Those logs must be accessible to the data subject or data controller, for auditing purposes. The Audit Ingestion service enables YaaS services to easily create appropriate audit logs for all considered event categories.

The Audit Ingestion service cannot handle sensitive personal data.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.