Skip to content

Latest commit

 

History

History
365 lines (240 loc) · 13.2 KB

audit-log-retrieval-api-usage-for-the-neo-environment-e4d818d.md

File metadata and controls

365 lines (240 loc) · 13.2 KB

Audit Log Retrieval API Usage for the Neo Environment

The audit log retrieval API allows you to retrieve the audit logs for your SAP BTP Neo environment account. It follows the OData 4.0 standard, providing the audit log results as OData with collection of JSON entities.

Remember:

SAP Business Technology Platform, Neo environment will sunset on December 31, 2028, subject to terms of customer or partner contracts.

For more information, see SAP Note 3351844.

Tip:

This documentation refers to SAP Business Technology Platform, Neo environment. If you are looking for documentation about other environments, see SAP Business Technology Platform ↗️.

Prerequisites

Create an OAuth client for platform API and get an access token as described in Using Platform APIs.

Use the following scopes:

  • Read Audit Logs – allow usage of the Audit Log Retrieval API to retrieve audit logs;

  • Manage Audit Logs – allow usage of the Audit Log Retention API to read retention and set custom retention.

Example: Get audit logs for the last 30 days

To achieve this you need to execute a similar GET request:

https://api.<region host>/auditlog/v1/accounts/<account>/AuditLogRecords?$count=true

Note:

The account provided as part of the URL should be the randomly generated technical name of the subaccount not the Display Name.

To authenticate, in the header provide the taken OAuth token similar to: "Authorization: Bearer <JWT>"

The returned results are split on pages with size – the server page size, which by default is set to 1000 records per server page. If the number of results is higher than the default server page size, in the response @odata.nextLink would be provided with the URL, to retrieve the next results' chunk.

Example: Get audit log filtering by time (UTC+0), user, category and application

To do this you need to execute a similar GET request:

https://api.<region host>/auditlog/v1/accounts/<account>/AuditLogRecords?$filter=(Time le '2017-12-30T17.13.22' or Time eq '2017-12-30T17.13.22') and User eq '<user>' and Category eq '<category>' and Application eq '<application_name>'

Note:

In the above example you can use all of the OData v4.0 supported logical operators for filtering described in the following documentation, see Query Options.

Note:

You can only filter by time (UTC+0), user, category and application. You can combine multiple filters in one request.

Note:

When filtering by time the format should be: yyyy-mm-ddThh.MM.ss

To authenticate, in the header provide the taken OAuth token similar to: "Authorization: Bearer <JWT>"

The returned results are split on pages with size – the default server page size. If the number of results is higher than the default server page size, in the response @odata.nextLink would be provided with the URL, to retrieve the next results' chunk.

The predefined audit log message categories are:

  • Data protection and privacy related

    • audit.data-access read-access logging records for access to sensitive personal data;

    • audit.data-modification data modification logging records for sensitive personal data.

    Security related

    • audit.security-events logging of general security events like login, logout, and other.;

    • audit.configuration logging of security critical configuration changes.

For more infromation, see Change Logging and Read-Access Logging.

Example: Get audit logs using client-side pagination

To get results based on pages with size 50, first check the total results number, execute a similar GET request:

https://api.<region host>/auditlog/v1/accounts/<account>/AuditLogRecords?$count=true

To split the pages on a desired size, 50 results per page in this example, execute a similar GET request:

https://api.<region host>/auditlog/v1/accounts/<account>/AuditLogRecords?$top=50&$skip=0

To get a second page, execute a similar GET request:

https://api.<region host>/auditlog/v1/accounts/<account>/AuditLogRecords?$top=50&$skip=50

To get a third page, execute a similar GET request:

https://api.<region host>/auditlog/v1/accounts/<account>/AuditLogRecords?$top=50&$skip=100

Continue the same requesting pattern, until the number of the results returned by count, in the first example of this section, is reached.

To authenticate, in the header provide the taken OAuth token similar to: "Authorization: Bearer <JWT>"

Note:

If you use client-side pagination and request a client-side page bigger that the server-side default page, the audit log retrieval API will split the requested page in several chunks that would be returned. As a result you will receive a response containing an @odata.nextLink field, where the next data chunk could be retrieved (for more information, see the Resultssection below). Go to the next client-side page value only after you have iterated all the chunks the server breaks the result to, which means that there is no @odata.nextLink field as part of the response provided.

Results

Executing a GET request towards the audit log retrieval API, results in response similar to the one below. The information for the AuditLogRecords can be checked in the metadata OData part. In the “value” part you receive the audit log messages in the format shown in the response example. The results returned on page are limited to the server page size. To get the next result page, navigate to the URL provided in @odata.nextLink.

Sample Code:

{
                    "@odata.context": "$metadata#AuditLogRecords",
                    "value": [
                    {
                    "Uuid": "3b8a8b-16247c70836-8",
                    "Category": "audit.data-access",
                    "User": "<user>",
                    "Tenant": "<tenant>",
                    "Account": "<account>",
                    "Application": "<application>",
                    "Time": "2018-03-21T09.00.40.572+0000",
                    "Message": "Read data access message. \"%void\"The accessed data belongs to {\"type\":\"account\",\"role\":\"account\",\"id\":{\"id :\":\"auditlog\"}} and  read  from object with name \"Auditlog Retrieval API\" and identifier {\"type\":\"Legacy.Object\",\"id\":{\"key\":\"Auditlog Retrieval API\"}} by user null",
                    "InstanceId": null,
                    "FormatVersion": "2.2"
                    }, 
                    …
                    {
                    "Uuid": "33a87d-1621e7debb2-1be",
                    "Category": "audit.security-events",
                    "User": "<user>",
                    "Tenant": "<tenant>",
                    "Account": "<account>",
                    "Application": "<application>",
                    "Time": "2018-03-21T09.00.40.782+0000",
                    "Message": "Security event message. Security event: "This is my message with custom parameters: &param1, &param2\",\"param1\":\"value of param1\",\"param2\":\"value of param2\"",
                    "InstanceId": null,
                    "FormatVersion": "2.2"
                    },    ],
                    "@odata.nextLink": "http://localhost:8001/auditlog/v1/accounts/auditlog/AuditLogRecords?$top=5000&$skip=0&$skiptoken=1000"
                    }
                    
                    
                    //Second Page:
                    {
                    "@odata.context": "$metadata#AuditLogRecords",
                    "value": [
                    {
                    "Uuid": "2a70bd-1621a471259-3653",
                    "Category": "audit.configuration",
                    "User": "<user>",
                    "Tenant": "<tenant>",
                    "Account": "<account>",
                    "Application": "<application>",
                    "Time": "2018-03-20T15.59.14.878+0000",
                    "Message": "Configuration change message. Attribute attributes update from value \"[old value]\" to value \"[new value]\". ",
                    "InstanceId": null,
                    "FormatVersion": "2.2"
                    },
                    …
                    {
                    "Uuid": "33a87d-1621e7debb2-1bf",
                    "Category": "audit.data-modification",
                    "User": "<user>",
                    "Tenant": "<tenant>",
                    "Account": "<account>",
                    "Application": "<application>",
                    "Time": "2018-03-20T15.59.14.898+0000",
                    "Message": "Data modification message. Attribute attribute1 update from value \"some old value\" to value \"some new value\". Attribute attribute3 update from value \"old Value\" to value \"new Value\". The data  update  from object with name \"object1 display name\" and identifier {\"type\":\"Legacy.Object\",\"id\":{\"key\":\"object1_ID\"}} by user null",
                    "InstanceId": null,
                    "FormatVersion": "2.2"
                    },
                    ],
                    "@odata.nextLink": "http://localhost:8001/auditlog/v1/accounts/auditlog/AuditLogRecords?$top=5000&$skip=0&$skiptoken=2000"
                    }

The retrieved audit logs are in JSON format. The semantics of the JSON fields are as follows:

JSON field

Semantic description

UUID

Unique identifier of the audit log message

Category

Category of the audit log message. It could be one of the predefined audit log types (audit.security-events , audit.configuration , audit.data-access or audit.data-modification) or a subcategory provided when invoking the “log” method with “subcategory” parameter ( e.g. audit.data-modification.test , audit.data-access.my-sub-category etc.)

User

The user that has executed the auditable event. The result of the user field could be:

  • “<userA>” - the user is determined implicitly by audit logging;

  • “<userA> on behalf of <userB>” – the user A is implicitly determined by audit logging and the user B is set by the component writing audit logs and verified by audit logging;

  • “on behalf of <userB>” - the user B is set by the component writing audit logs and verified by audit logging;

  • “” (empty string) – no user is determined or verified by audit logging.

Note:

Users that are set by the component writing audit logs and not further verified as a validity by audit logging are visible only in the “Message” field in the “Custom defined attributes” part in field “caller_user”.

Tenant

Tenant ID owner of the auditable event.

Account

Account ID owner of the auditable event.

Application

Application that has generated the audit log event.

Time

Timestamp (UTC+0) when the auditable event is generated.

Message

Audit log message text.

InstanceId

Instance ID where the event has occurred if applicable.

FormatVersion

Audit log message format.

Related Information

Audit Log Retrieval API for the Neo Environment

API Documentation