docs(audit): Dev Portal Audit Logging

app/_data/docs_nav_konnect.yml

@@ -183,6 +183,14 @@
 
     - text: Portal Management API Automation Guide
       url: /dev-portal/konnect-portal-management-automation/
+    - text: Audit Logging
+      items:
+        - text: Overview
+          url: /dev-portal/audit-logging/
+        - text: Set up an Audit Log Webhook
+          url: /dev-portal/audit-logging/webhook/
+        - text: Set up an Audit Log Replay Job
+          url: /dev-portal/audit-logging/replay-job/
     - text: Portal Customization
       items:
         - text: Overview
@@ -253,10 +261,6 @@
           url: /org-management/audit-logging/webhook/
         - text: Set up an Audit Log Replay Job
           url: /org-management/audit-logging/replay-job/
-        - text: Verify Audit Log Signatures
-          url: /org-management/audit-logging/verify-signatures/
-        - text: Log Reference
-          url: /org-management/audit-logging/reference/
     - text: Account and Org Deactivation
       url: /org-management/deactivation/
 
@@ -392,3 +396,7 @@
       url: /reference/search/
     - text: Terraform Provider
       url: /reference/terraform/
+    - text: Audit Logs
+      url: /reference/audit-logs/
+    - text: Verify audit log signatures
+      url: /reference/verify-signatures/

app/_includes/md/konnect/audit-logging/audit-log-overview.md

@@ -0,0 +1,10 @@
+<!-- used in Org Audit Logging Overview and Dev Portal Audit Logging Overview-->
+Audit logging enables administrators to better spot security risks and maintain compliance of their core infrastructure. 
+
+Audit logs can help you detect and respond to potential security incidents when they occur. Monitoring audit logs proactively can reduce the risk of outages and ensure continuous service for your users. No system can ever be completely secure, but audit logs can be a key part of your incident prevention infrastructure.
+
+By tracking {{site.konnect_short_name}} audit logs, you gain the following benefits:
+* **Security**: System events can be used to show abnormalities to be investigated, forensic information related to breaches, or provide evidence for compliance and regulatory purposes.
+* **Compliance**: Regulators and auditors may require audit logs to confirm whether certain certification standards are met.
+* **Debugging**: Audit logs can help determine the root causes of efficiency or performance issues.
+* **Risk management**: Prevent issues or catch them early.

app/_includes/md/konnect/audit-logging/webhook-overview-prereq-siem-config.md

@@ -0,0 +1,31 @@
+<!-- used in Org Audit Logging Set Up Webhook and Dev Portal Audit Logging Set Up Webhook-->
+Webhooks are invoked via an HTTPS request using the following retry rules:
+
+- Minimum retry wait time: 1 second
+- Maximum retry wait time: 30 seconds
+- Maximum number of retries: 4
+
+A retry is performed on connection error, server error (`500` HTTP status code), or too many requests (`429` HTTP status code).
+
+{:.note}
+> **Notes:**
+* Only supports HTTPS Webhook endpoints.
+* You can't customize the events that {{site.konnect_short_name}} sends to the logs.
+
+## Prerequisites
+
+A SIEM provider that supports the [ArcSight CEF Format](https://docs.centrify.com/Content/IntegrationContent/SIEM/arcsight-cef/arcsight-cef-format.htm) or raw JSON
+
+## Configure your SIEM provider
+
+Before you can push {{site.konnect_short_name}} audit logs to an external service, you also need to configure the service to receive logs. 
+This configuration is specific to your vendor.
+
+1. Check your SIEM documentation to find out where to send CEF or raw JSON data.
+
+1. In your log collection service, configure a data collection endpoint to push logs to. {{site.konnect_short_name}} supports any HTTP authorization header type. Save the endpoint URL, this will be used later in {{site.konnect_short_name}}.
+
+1. Create and save an access key from your SIEM provider. 
+
+1. Configure your firewall settings to allow traffic through the port that you're going to use. 
+See the [Konnect ports and network requirements](/konnect/network/).

app/_redirects

@@ -109,6 +109,14 @@
 /konnect/dev-portal/access-and-approval/manage-app-reg-requests/    /konnect/dev-portal/access-and-approval/manage-app-connections/
 /konnect/dev-portal/access-and-approval/auto-approve-devs-apps/ /konnect/dev-portal/create-dev-portal/
 
+# Konnect Dev Portal audit logs
+/konnect/dev-portal/audit-logging/reference/    /konnect/reference/audit-logs/
+/konnect/org-management/audit-logging/reference/    /konnect/reference/audit-logs/
+/konnect/dev-portal/audit-logging/verify-signatures/  /reference/verify-signatures/
+/konnect/org-management/audit-logging/verify-signatures/    /reference/verify-signatures/
+/konnect/dev-portal/audit-logging/webhook-status/   /konnect/dev-portal/audit-logging/webhook/#view-audit-log-webhook-status
+
+
 # API markdown doc deprecation
 
 /gateway/latest/admin-api/licenses/reference   /gateway/api/admin-ee/latest/#/licenses/get-licenses/

app/konnect/dev-portal/audit-logging/index.md

@@ -0,0 +1,17 @@
+---
+title: Audit Logging in Dev Portal
+badge: enterprise
+content_type: concept
+---
+
+{% include_cached /md/konnect/audit-logging/audit-log-overview.md %}
+
+{:.note}
+> **Note:** Dev Portal audit logs are set up and managed separately from org-wide {{site.konnect_short_name}} audit logs. For more information about how to configure audit logging for a {{site.konnect_short_name}}, see [Set up an audit log webhook for Dev Portal](/konnect/dev-portal/audit-logging/webhook/).
+
+## More information
+* [Set up an portal audit log webhook](/konnect/dev-portal/audit-logging/webhook/)
+* [Set up an portal audit log replay job](/konnect/dev-portal/audit-logging/replay-job/)
+* [Portal Audit log event reference](/konnect/reference/audit-logs/)
+* [Verify audit log signatures](/konnect/reference/verify-signatures/)
+* [Dev Portal Audit Logs API](/konnect/api/audit-logs/latest/)

app/konnect/dev-portal/audit-logging/replay-job.md

@@ -0,0 +1,126 @@
+---
+title: Set up an audit log replay job
+content_type: how-to
+badge: enterprise
+---
+
+You can use the {{site.dev-portal_short_name}} Audit Logs API to configure replay jobs for [audit logging](/konnect/dev-portal/audit-logging/). 
+
+Replay jobs are useful when you have missed audit log entries due to an error or a misconfigured audit
+log webhook. You may have one replay job at a time per region, and request data from up to one week ago.
+A replay job in a region will resend data for the requested timeframe to the webhook configured for that region.
+
+## Prerequisites
+
+* [**Org Admin** or **Portal Admin** permissions](/konnect/org-management/teams-and-roles/teams-reference/)
+* Your [audit log webhook](/konnect/dev-portal/audit-logging/webhook/) must be enabled and ready to receive data. 
+
+
+## Configure a replay job
+
+{% navtabs %}
+{% navtab Konnect UI %}
+
+1. From the navigation menu, open {% konnect_icon Dev-Portal %} **Settings**, then **Audit Logs Setup**.
+1. Switch to the **Replay** tab.
+1. Choose a timeframe for which you want to replay the logs. 
+
+   You can choose one of the preset relative increments for up to 24 hours, or 
+   set a custom timeframe for up to 7 days.
+
+1. Apply the timeframe, then click **Send Replay**.
+
+{% endnavtab %}
+{% navtab API %}
+The {{site.konnect_short_name}} API uses [Personal Access Token (PAT)](/konnect/api/#authentication) authentication. You can obtain your PAT from the [personal access token page](https://cloud.konghq.com/global/account/tokens). The PAT must be passed in the `Authorization` header of all requests.
+
+Configure the replay job for a region by sending a `PUT` request to the `/audit-log-replay-job` endpoint:
+
+```sh
+curl -i -X PUT https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-replay-job \
+    --header "Content-Type: application/json" \
+    --header "Authorization: Bearer <personal-access-token>" \
+    --data '{
+        "start_at": "2023-03-27T20:00:00Z",
+        "end_at": "2023-03-27T20:00:00Z"
+    }'
+```
+
+Be sure to replace the PAT token and the following placeholder values:
+* `{region}.api.konghq.com`: The region your portal is located in. Can be `us`, `ap`, or `eu`.
+* `{portalId}`: The ID of the Dev Portal with your webhook.
+* `start_at` and `end_at`: Specify the timeframe for which you want to receive audit log events. `start_at` must be no more than seven days ago.
+
+If the request is successful, you will receive a `202` response code and a response body containing the replay job details: 
+
+```json
+{
+    "start_at":"2023-03-27T20:00:00Z",
+    "end_at":"2023-03-27T20:00:00Z",
+    "updated_at":"2023-03-31T11:34:18Z",
+    "status":"accepted"
+}
+```
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## View replay job
+
+{% navtabs %}
+{% navtab Konnect UI %}
+
+1. From the navigation menu, open {% konnect_icon Dev-Portal %} **Settings**, then **Audit Logs Setup**.
+1. Switch to the **Replay** tab.
+1. Check the status table below the configuration field.
+
+![Audit log replay](/assets/images/products/konnect/audit-logs/konnect-audit-log-replay.png)
+
+{% endnavtab %}
+{% navtab API %}
+The {{site.konnect_short_name}} API uses [Personal Access Token (PAT)](/konnect/api/#authentication) authentication. You can obtain your PAT from the [personal access token page](https://cloud.konghq.com/global/account/tokens). The PAT must be passed in the `Authorization` header of all requests.
+
+You can view the audit log replay job in a given region by issuing a GET request to the `audit-log-replay-job` endpoint:
+
+```sh
+curl -i -X GET https://us.api.konghq.com/v2/portals/{portalId}/audit-log-replay-job \
+    --header "Authorization: Bearer TOKEN"
+```
+
+Be sure to replace the PAT token and the following placeholder values:
+* `{region}.api.konghq.com`: The region your portal is located in. Can be `us`, `ap`, or `eu`.
+* `{portalId}`: The ID of the Dev Portal with your webhook.
+
+You will receive a `200` response code and the job details:
+
+```json
+{
+    "start_at":"2023-03-27T20:00:00Z",
+    "end_at":"2023-03-27T20:00:00Z",
+    "updated_at":"2023-03-31T11:34:18Z",
+    "status":"accepted"
+}
+```
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## Replay job status
+
+A replay job can be in one of the following statuses:
+
+* `unconfigured`: Initial state. The job has not been set up.
+* `accepted`: The job has been accepted for scheduling.
+* `pending`: The job has been scheduled.
+* `running`: The job is in progress.
+* `completed`: The job has finished with no errors.
+* `failed`: The job has failed.
+
+When a replay job is `running`, a request to update the job will return a `409` response code until it has completed or failed.
+
+## More information
+* [Audit logging in {{site.konnect_short_name}}](/konnect/dev-portal/audit-logging/)
+* [Set up an audit log webhook](/konnect/dev-portal/audit-logging/webhook/)
+* [Audit log event reference](/konnect/reference/audit-logs/)
+* [Verify audit log signatures](/konnect/reference/verify-signatures/)
+* [Audit Logs API](/konnect/api/audit-logs/latest/)

app/konnect/dev-portal/audit-logging/webhook.md

@@ -0,0 +1,139 @@
+---
+title: Set up an audit log webhook for Dev Portal
+content_type: how-to
+badge: enterprise
+---
+
+You can use the {{site.konnect_short_name}} UI or the Audit Logs API to configure webhooks for [audit logging](/konnect/dev-portal/audit-logging/). 
+
+{:.note}
+> **Note:** Currently, Dev Portal audit logs only support authorization logs, which are triggered when a user logs in to Dev Portal.
+
+{% include_cached /md/konnect/audit-logging/webhook-overview-prereq-siem-config.md %}
+
+
+## Create a webhook
+
+{% navtabs %}
+{% navtab Konnect UI %}
+1. From the navigation menu, open {% konnect_icon organizations %} **Organization**, then **Audit Logs Setup** and **Destinations**
+1. Fill in the fields in the **Destinations** tab. This allows you to set your audit log destination (the endpoint URL for your SIEM provider) and reuse it. 
+   * **Region endpoint**: The external endpoint that will receive audit log messages. 
+   * **Authorization Header**: The authorization type and credential to pass to your log collection endpoint. 
+    {{site.konnect_short_name}} will send this string in the `Authorization` header of requests to that endpoint.
+
+     For example, if you are setting up the webhook for Splunk, you could provide a Splunk access token: 
+     `"authorization":"Splunk example-token12234352535235"`.
+
+    * **Log Format**: The output format of each log message. Can be CEF or JSON.
+    * **Skip SSL Verification**: Skip SSL verification of the host endpoint when delivering payloads.
+
+     {:.note}
+     > We strongly recommend not setting this to `true` as you are subject to man-in-the-middle and other attacks. This option should be considered only when using self-signed SSL certificates in a non-production environment.
+1. From the navigation menu, open {% konnect_icon Dev-portal %} **Settings**, then **Audit Logs Setup**.
+1. Fill in the fields in the **Setup** tab.
+    * **Audit log Destination**: select the destination that you want to use from the drop down list
+    * 
+1. Switch the toggle to `Enabled`, then save your webhook configuration.
+
+{% endnavtab %}
+{% navtab API %}
+
+Now that you have an external endpoint and authorization credentials, you can set up an audit log destination in {{site.konnect_short_name}}. The `/audit_log_destinations` endpoint allows you to set your audit log destination, which includes the endpoint URL and access key for your SIEM provider, and reuse it. 
+
+The {{site.konnect_short_name}} API uses [Personal Access Token (PAT)](/konnect/api/#authentication) authentication. You can obtain your PAT from the [personal access token page](https://cloud.konghq.com/global/account/tokens). The PAT must be passed in the `Authorization` header of all requests.
+
+1. Create an audit log destination by sending a request to the `/audit-log-destinations` endpoint with the connection details for your SIEM provider:
+
+    ```sh
+    curl -i -X POST https://global.api.konghq.com/v2/audit-log-destinations \
+    --header "Content-Type: application/json" \
+    --header "Authorization: Bearer <personal-access-token>" \
+    --data '{
+        "endpoint": "https://example.com/audit-logs",
+        "authorization": "<SIEM-access-token>",
+        "log_format": "cef",
+        "name": "example destinations name"
+    }'
+    ```
+
+    Be sure to replace the PAT token and the following placeholder values:
+    * `endpoint`: The external endpoint that will receive audit log messages. Check your SIEM documentation to find out where to send CEF or JSON data.
+    * `authorization`: The authorization type and credential to pass to your log collection endpoint. 
+    {{site.konnect_short_name}} will send this string in the `Authorization` header of requests to that endpoint. For example, if you are setting up the webhook for Splunk, you could provide a Splunk access token: `"authorization":"Splunk example-token12234352535235"`.
+    * `log_format`: The output format of each log message. Can be `cef` or `json`.
+    * `name`: A unique human-readable name to identify this destination.
+    * `skip_ssl_verification`: (Optional) Set to `true` to skip SSL verification of the host endpoint when delivering payloads. We recommend only using this when using self-signed SSL certificates in a non-production environment as this can subject you to man-in-the-middle and other attacks.
+
+    If the request is successful, you will receive a `200` response code, and a response body containing the webhook's configuration details. Be sure to save the audit log destination `id` for the next step. 
+
+1. Create a webhook by sending a PATCH request to the `/audit-log-webhook` endpoint with your configured audit log destination:
+
+    ```sh
+    curl -i -X PATCH https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-webhook \
+     --header "Content-Type: application/json" \
+     --header "Authorization: Bearer <personal-access-token>" \
+     --data '{
+         "audit_log_destination_id": "05atf3f2-9d07-4e46-8115-c58ca594d00e",
+         "enabled": true
+     }'
+    ```
+
+    Replace the following placeholders with your own data:
+    * `{region}.api.konghq.com`: The region your Dev Portal is located in. Can be `us`, `au`, or `eu`.
+    * `audit_log_destination_id`: The ID of the audit log destination that you want to use.
+
+    If the request is successful, you will receive a `200` response code, and a response body containing the webhook's configuration details.
+
+{% endnavtab %}
+{% endnavtabs %}
+
+Your webhook should now start receiving audit logs.
+
+## View audit log webhook status
+
+{% navtabs %}
+{% navtab Konnect UI %}
+
+You can view the status of your webhook through the **Audit Logs Setup** page under
+{% konnect_icon organizations %} **Organization**.
+
+Notice the status badge next to title of the webhook. For example, the following webhook is active:
+
+![Audit log webhook](/assets/images/products/konnect/audit-logs/konnect-audit-log-webhook.png)
+
+To find the last attempt timestamp and the last response code, use the audit log API.
+
+{% endnavtab %}
+{% navtab API %}
+
+The {{site.konnect_short_name}} API uses [Personal Access Token (PAT)](/konnect/api/#authentication) authentication. You can obtain your PAT from the [personal access token page](https://cloud.konghq.com/global/account/tokens). The PAT must be passed in the `Authorization` header of all requests.
+
+View your audit log webhook status by sending a GET request to the `/audit-log-webhook/status` endpoint:
+
+```sh
+curl -i -X GET https://{region}.api.konghq.com/v2/portals/{portalId}/audit-log-webhook/status \
+    --header "Authorization: Bearer <personal-access-token>"
+```
+
+You will receive a `200` response code and a response body with information about the webhook status:
+
+```json
+{
+    "last_attempt_at": "2023-04-04T18:11:16Z",
+    "last_response_code": 200,
+    "webhook_enabled": true,
+    "webhook_status": "active"
+}
+```
+
+{% endnavtab %}
+{% endnavtabs %}
+
+
+## More information
+* [Audit logging in {{site.konnect_short_name}}](/konnect/dev-portal/audit-logging/)
+* [Audit log event reference](/konnect/reference/audit-logs/)
+* [Set up an audit log replay job](/konnect/dev-portal/audit-logging/replay-job/)
+* [Verify audit log signatures](/konnect/reference/verify-signatures/)
+* [Audit Logs API](/konnect/api/audit-logs/latest/)

app/konnect/dev-portal/create-dev-portal.md

@@ -114,3 +114,6 @@ Your Dev Portal URL may vary. Keep the following in mind:
 ### Publish APIs to Dev Portals
 
 * [Add and publish API product documentation](/konnect/dev-portal/publish-service/)
+
+### Configure audit logs for Dev Portal
+* [Dev Portal audit logs](/konnect/dev-portal/audit-logging/): Keep track of Dev Portal authentication, authorization, and access logs in a SIEM provider

app/konnect/dev-portal/index.md

@@ -16,6 +16,7 @@ You can use the following table to help you determine which Dev Portal configura
 | Determine which users can see which APIs in Dev Portal | [Assign different APIs and permissions with RBAC Teams](/konnect/api/portal-auth/portal-rbac-guide/#main) |
 | Self-host or visually customize your Dev Portal | [Self-hosted Dev Portal](/konnect/dev-portal/customization/self-hosted-portal/) |
 | Publish documentation for your APIs | [Add and publish API product documentation](/konnect/dev-portal/publish-service/) |
+| Keep track of Dev Portal authentication, authorization, and access logs in a SIEM provider | [Dev Portal audit logs](/konnect/dev-portal/audit-logging/) |
 
 To see guidance on all Dev Portal configuration options for your situation, see the [Dev Portal configuration preparation guide](/konnect/dev-portal/configuration-prep/).