Set up Audit Logs

Table of contents

• What are audit logs?
• Audit log delivery
• Event details
• Events captured by the audit log
• Audit log file naming convention
• Data retention period
• Requirements
• Audit logs set up
  • Audit logs AWS Configuration
  • Audit logs Azure Configuration

What are audit logs?

Audit logs allow customers to track and view all the changes made in their organization. They provide visibility and are useful for investigating an incident or getting a detailed report on relevant events (such as changes to roles and permissions, users invited, spaces deleted, etc.).

The audit logs feature securely transfers this information to your own storage (an AWS S3 bucket or Azure Blob Store), ensuring that you have a clear and accessible history of actions for monitoring and analysis purposes.

Audit log delivery

Audit logs are shipped to your AWS S3 Bucket or Azure Blob Store. Storing the audit logs in storage that you own helps you to have control and will allow you to ensure that audit logs are kept for as long as necessary. By storing the data in your own storage you have the following benefits:

• Consistency: This way you can apply the same rules and policies to this as you do for other similar data. You can control who has access to it.
• Data retention: This enables you to store it for as long as you need to maintain compliance for your company.
• Data analysis: And it allows you to serve this data to the tools you already use for analysis.

Events captured by the audit log

Audit logs capture all changes made through the Content Management API, focusing on actions and modifications across the entire Contentful organization. This includes any content that has been recently created, updates, deletions, and configuration adjustments performed by users or apps interacting with the CMA.

Audit log file naming convention

Each audit log file received by customers follows a standardized naming format to provide essential details at a glance. The file name structure is as follows:

audit-log-{organization_id}-{date}-{timestamp}.json

Components of the file name

1. audit-log: Prefix indicating the file type as an audit log.
2. {organization_id}: Unique identifier for the organization. This ensures the file is specific to your Contentful organization.
3. {date}: The date on which the file was generated, in YYYY-MM-DD format. This helps identify the log period.
4. {timestamp}: A timestamp representing the exact time the file was created, in HHMMSS format (24-hour format). This is useful for distinguishing multiple log files created on the same day.
5. .json: File extension, indicating the file format as JSON.

Example file name

audit-log-7BLDDu2FYCNoN4QIWys1BR-2024-10-31-143500.json

In this example:

• 7BLDDu2FYCNoN4QIWys1BR is the organization ID.
• 2024-10-31 is the date the log was created.
• 143500 is the timestamp in hours, minutes, and seconds (14:35:00).

Data retention period

Contentful sends daily audit log files to the customer’s configured storage location (e.g., S3 bucket or Azure Blob storage). This ensures that customers always have access to a daily record of audit logs in their own storage environment. In their own storage, customers have full control over how long they want to retain the data.

If a customer needs to recover logs due to an issue, Contentful can re-send audit log files for actions that occurred within the past 30 days.

Event details

Audit event logs adhere to the OCSF standard. Currently all logs are logged under the Application Activity category and more specifically the Web Resource Activity sub-category. This enables seamless integrations and will be the stable schema from now on, meaning these logs are safe to use in integrations. An example of an audit log when an entry is updated can be found below.

  {
    "activity_name": "Update",
    "activity_id": 3,
    "category_uid": "6",
    "class_uid": "6001",
    "type_uid": "600101",
    "time": "yyyy-MM-dd hh:mm:ss.SSS",
    "actor": { "type": "user", "id": "<user_id>" },
    "enrichments": [
      {
        "name": "http_request.url.path",
        "type": "Space",
        "value": "/spaces/<space_id>/environments/<environment_id>/entries/<entry_id>/published",
        "data": { "id": "<space_id>" }
      }
    ],
    "severity_id": 0,
    "http_request": {
      "http_method": "PUT",
      "referrer": "https://app.contentful.com/",
      "url": {
        "path": "/spaces/<space_id>/environments/<environment_id>/entries/<entry_id>/published"
      }
    },
    "http_response": { "code": 200 },
    "web_resources": [{ "type": "Entry", "uid": "entry_id" }],
    "metadata": {
      "version": "1.3.0",
      "uid": "<request-id>"
    }
  },

How to read an audit log

Since audit logs abide by the OCSF standards some common parameters will always be the same. However, some properties have specific nuances due to being generated from the Contentful platform. The following guide will explain what each piece of the audit logs means and how to read it.

Activity

The properties prefixed with activity describe the type of event that occurred, and whether a resource (e.g. a space, environment, or locales) was updated, created, or deleted. Below is a table mapping the IDs to their names as well as their descriptions.

Category

The category properties refer to the OCSF categories and subcategories under which a specific log falls. As stated earlier at this moment all audit logs fall under the Application Activity category and more specifically the Web Resource Activity sub-category this may expand in the future but for now integrations can be built around this type of log specifically. Below is a description for each property that is relevant to the category in this log.

Actor

The actor property describes the user or app that acted on the resource by providing their user_id.

Severity

As quoted in the OCSF documentation the severity_id is “The normalized severity is a measurement of the effort and expense required to manage and resolve an event or incident. Smaller numerical values represent lower impact events, and larger numerical values represent higher impact events.” Below is a table mapping each ID to its description.

HTTP Request

The http_request object describes the original HTTP request that resulted in the log, the below table provides further details on what each property means.

HTTP Response

This http_response object contains the code referring to the HTTP Response code that the query resulted allowing for it to be established if the request was successful or not.

Enrichments

The enrichments property provides an array of objects that enrich other properties in the logs. More details can be found in the OCSF docs. Given the example log above each property would mean the following:

Web Resources

The web_resources property contains an array of entities that were affected by this request these can be environments, locales, content types or entries, etc. The properties of the objects contained in the array are as described below:

Metadata

The metadata property contains miscellaneous data that doesn’t fit well in the rest of the log but may still be useful. At this moment only two properties can be found in this object and the below table describes them.

Requirements

AWS or Azure account: An active AWS or Azure account is necessary.

Stopping the audit logs delivery

To stop the delivery of the audit logs, please contact our support

Audit logs set up

To set up your infrastructure to receive Audit Logs, you will need to make some configuration changes and share some information with Contentful.

The exact process is dependant on your storage provider. Please follow the appropriate guide from the list:

Audit logs AWS Configuration

As part of enabling audit log shipping to your AWS S3 bucket, you need to create an AWS IAM role that Contentful can assume. This will allow Contentful to securely transfer audit logs to your AWS S3 bucket without the need to store any credentials.

Security of IAM role assumption

Contentful uses AWS IAM role assumption to securely deliver audit logs to your specified S3 bucket. This approach follows AWS’s recommended best practices for granting third-party access to your resources. With IAM role assumption:

• No credentials are shared: Contentful does not require or store your AWS credentials. Instead, a secure trust relationship is established through the IAM role.
• Explicit permissions: You maintain full control by explicitly defining which actions Contentful can perform (e.g., s3:PutObject) and on which resources (e.g., specific S3 buckets).
• Control over the trust policy: The trust policy for the IAM role allows access only to Contentful’s AWS account and requires an external ID for added security.
• Industry standard: Role assumption is widely adopted by leading SaaS platforms, ensuring a secure, scalable, and traceable approach.

For more details, refer to the AWS IAM documentation.

Prerequisites

• An AWS account with permissions to create IAM roles and edit S3 bucket policies.
• Contentful's AWS account IDs:
  • For US customers: 606137763417
  • For EU data residency customers: 101997328120

Step 1: Create an S3 Bucket

1. Log in to your AWS Management Console.
2. Navigate to S3, click Create bucket.
3. Enter a unique bucket name and select the region where you want the bucket to reside. Note: you will need to enter this name later.
4. Configure options as required (e.g., versioning, logging, tags).
5. Review and create the bucket.

Step 2: Create a New IAM Policy

1. Log in to your AWS Management Console.
2. Navigate to IAM -> Policies -> Create policy.
3. Select the JSON tab and paste the following policy, replacing with the name of your S3 bucket (from Step 1). Make sure to keep the /* at the end:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::<Your-S3-Bucket-Name>/*"
    }
  ]
}

4. Click Next, give it a meaningful name and description, and then click Create.

Step 3: Create a New IAM Role for Cross-Account Access

1. In the IAM dashboard, go to Roles -> Create role.
2. Select AWS Account under the "Trusted entity type" section, then in the section below select Another AWS account and enter Contentful's AWS account ID:
   • For US customers: 606137763417
   • For EU data residency customers: 101997328120
3. Enable the option Require external ID and insert your Contentful organization ID. The primary function of the external ID is to address and prevent the confused deputy problem. You can find the organization ID in the Contentful web app.
4. Click Next, skip attaching permissions policies now (we will attach the policy created in Step 2).
5. Review, name the role, and then create it.

Step 4: Attach the Policy to the IAM Role

1. Go to the newly created role in IAM -> Roles.
2. Under "Permissions" in the Add permissions dropdown, click Attach policies.
3. Find the policy you created in Step 2, select it, and then click Add permission.

Step 5: Configure Your S3 Bucket Policy

1. Go to S3, find your bucket from Step 1, and then click Permissions.
2. Edit the Bucket policy and add the following statement, replacing with the ARN of the IAM role you created in Step 3 and <Your-S3-Bucket-Name> with the name of your S3 bucket. Make sure to keep the /* at the end of the bucket ARN:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<Your-IAM-Role-ARN>"
      },
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::<Your-S3-Bucket-Name>/*"
    }
  ]
}

3. Save the changes.

Step 6: Configure AWS S3 storage in the Contentful web application

Note: Only organization owners and organization admins can add and edit the storage details in Contentful.

1. In Contentful, navigate to Organization settings -> Audit logs.
2. Select Amazon AWS as a Storage provider option and fill in the form with the following details:
   • S3 Bucket Name: The name of the S3 bucket you’ve created for storing audit logs.
   • ARN of IAM Role: The Amazon Resource Name (ARN) of the IAM role that Contentful will assume to send logs to your bucket.
   • AWS Region: The AWS region where your S3 bucket is located.
3. Click Test connection to verify that the connection to your AWS S3 bucket is working correctly. During this test, Contentful sends a file to ensure the configuration is valid. If the test succeeds, you’ll see a confirmation message.
4. If the connection test is successful, click Save to finalize the configuration.

Note: If the test fails, double-check that your bucket permissions, IAM Role, and policy configurations match the requirements outlined earlier in this guide.

By following these steps, you've securely enabled Contentful to ship logs to your AWS S3 bucket. Contentful will use AWS STS to assume the role you've created, ensuring a secure and efficient transfer of audit log data.

Audit Logs Azure Configuration

As part of enabling audit log shipping to your Azure Blob Storage container, you need to create a Shared Access Signature (SAS) user that Contentful can use. This will allow Contentful to securely transfer audit logs directly to your Azure Storage Account container. This guide will help you create a Shared Access Signature (SAS) user specifically for Contentful.

A shared access signature (SAS) provides secure delegated access to resources in your storage account. With a SAS, you have granular control over how a client can access your data. For example:

• What resources the client may access

• What permissions they have to those resources

• How long the SAS is valid

We will use RSA 4096 encryption to secure your SAS Token in-transit and at rest. Access to decrypt is provided only to the Audit Logging system and a small number of people who manage the Audit Logging service. For more information please contact us via support.

Prerequisites

An Azure account with access to create a Blob Store and a SAS Token.

Step 1: Create an Azure Storage Account

1. Log in to your Azure Portal.

2. Navigate to Storage Accounts -> Create

3. Select the Subscription under which to create the Storage Account.

4. Select or Create the Resource Group for the Storage Account.

5. Enter a unique storage account name and select the region where you want the account to reside. Note this name, you will need it later.

6. Configure options as required (e.g., performance, redundancy, etc).

7. Click Review + create

8. On the Review + create page check that everything correct and if you’re satisfied click Create to create the storage account.

Step 2: Create a Container

1. Log in to your Azure Portal.

2. Navigate to Storage Accounts and click the one you created in Step 1 to open it.

3. On the left sidebar, under Data storage, click Containers.

4. In the top toolbar click the + Container button to create a new container.

5. Enter a unique container name.

6. Configure options as required (e.g., encryption scope, versioning, etc).

7. Review and click Create to create the container.

Step 3: Create the SAS Token

1. Log in to your Azure Portal.

2. Navigate to Storage Accounts and click the one you created in Step 1 to open it.

3. On the left sidebar, under Data storage, click Containers.

4. Click the name of the container you create in the steps above.

5. On the left sidebar, under Settings, click Shared access tokens

6. Select the Permissions dropdown, deselect Read, then select Create and Write.

7. Set an expiry date that complies with your secret rotation policy.

8. Click Generate SAS token and URL

9. Copy the value of the Blob SAS URL field that's displayed. You will use this URL in the next steps.

Step 4: Configure Microsoft Azure storage in the Contentful web application

Note: Only organization owners and organization admins can add and edit the storage details in Contentful.

1. In Contentful, navigate to Organization settings -> Audit logs.
2. Select Microsoft Azure as a Storage provider option.
3. Paste the Blob SAS URL from the previous step into Blob SAS URL field.
4. Click Test the connection to verify that the connection to your Microsoft Azure storage is working correctly. During this test, Contentful sends a file to ensure the configuration is valid. If the test succeeds, you’ll see a confirmation message.
5. If the connection test is successful, click Save to finalize the configuration.