diff --git a/content/en/docs/apidocs-mxsdk/apidocs/audit-logs-api.md b/content/en/docs/apidocs-mxsdk/apidocs/audit-logs-api.md new file mode 100755 index 00000000000..a647dc9940a --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/audit-logs-api.md @@ -0,0 +1,37 @@ +--- +title: "API for Audit Logging" +url: /apidocs-mxsdk/apidocs/apis-for-audit-logs/ +type: swagger +restapi: true +no_list: false +description_list: true +description: "Provides the documentation of Audit Logging API." +linktitle: "Audit Logs" +beta: true +--- + +{{% alert color="warning" %}} +This feature is in Public Beta. For more information, refer to [Release Status](/releasenotes/release-status/). +{{% /alert %}} + +## Introduction + +You can use the Audit Logging API to manage and download audit logs. This API is particularly useful in scenarios where you want to download audit logs that are over 90 days old, but no more than one year old. + +## Authentication + +Two types of Authorization headers are supported: `Bearer` (Client credentials or Mendix SSO) and `MXToken` (Personal Access Tokens). + +* **Client Credentials**: bearer JWT token obtained for a clientId and secret pair. + Scope required: `mx:audit-logging:write` + Authorization header example: `Authorization: Bearer ` +* **Mendix SSO Tokens**: bearer token obtained via Mendix SSO login flow. + Scope required: `mx:audit-logging:read` + Authorization header example: `Authorization: Bearer ` +* **Personal Access Tokens (PATs)**: PAT created by you. For details on how to generate a PAT, refer to the [Personal Access Tokens](/portal/user-settings/#pat) section in *User Settings*. + Scope required: `mx:audit-logging:read` + Authorization header example: `Authorization: MxToken ` + +The following API reference includes information on which scope and token type is required for each endpoint. + +{{< swaggerui src="/openapi-spec/audit-logging-v1.yaml" >}} \ No newline at end of file diff --git a/content/en/docs/control-center/security/audit-logs.md b/content/en/docs/control-center/security/audit-logs.md new file mode 100644 index 00000000000..55085137a5c --- /dev/null +++ b/content/en/docs/control-center/security/audit-logs.md @@ -0,0 +1,75 @@ +--- +title: "Audit Logs" +url: /control-center/audit-logs/ +description: "Describes the Audit Logs page in the Mendix Control Center." +weight: 30 +beta: true +--- + +{{% alert color="warning" %}} +This feature is in Public Beta. For more information, refer to [Release Status](/releasenotes/release-status/). +{{% /alert %}} + +## Introduction + +## Audit Logs + +The **Audit Logs** tab displays a list of all activities over the past 90 days. It includes the following details: + +* **Date** – The date when the activity was logged. +* **Email** – The email of the user who performed the activity. +* **Action** – The activity that was performed. +* **Service** – +* **Description** – +* **Outcome** – +* **Resource Name** – +* **Resource Type** – +* **Details** – The following information is displayed and can be downloaded for each audit log item: + + * **Log ID** – The unique identifier of the log. + * **Date** – The date when the log was generated. + * **Owner ID** – + * **Owner ID Type** – + * **User Email** – The email address of the user who performed the action that generated the log. + * **User Name** – The name of the user who performed the action that generated the log. + * **User ID** – The unique identifier of the user who performed the action that generated the log. + * **IP Address** – The IP address corresponding to the user who performed the action that generated the log. + * **Action** – The action that generated the log. + * **Description** – + * **Outcome** – + * **Error Message** – + * **Old Value** – The state of the entity prior to the change that generated the log. + * **New Value** – The state of the entity after the change that generated the log. + * **Resource Name** – The name of the resource that was changed. + * **Resource Type** – The type of resource that was changed. + +You can use the **Filters** option to only display the audit logs that meet the criteria you are interested in, or you can use the search field to search for a specific log. + +### Exporting Audit Logs + +You can export audit logs in a CSV format. This is available for logs that are no older than 90 days old. +You can choose between these options: + +* Export all logs. To do that, click **Export All**. +* Export a selection of logs. To do that, select the log items you are interested in, then click **Export Selection**. +* Export logs from a specific timeframe. To do that, click **Export from Selected Date Range**, then select the start and end dates and times. +* Export filtered logs. To do that, filter by the criteria you are interested in, then click **Export All**. +* Export from archive. + +Once the logs are ready for export, a download link is displayed on the [Downloads](#downloads) tab. + +## Downloads {#downloads} + +When you export audit logs, a download link is displayed on this tab once the export CSV is ready for download. +These are details available on the this tab: + +* **Submitted on** – +* **Requester** – The user who requested the export. +* **Expires in** – The number of days that the exported CSV is available for download. +* **Status** – The status of the CSV generation. Once the CSV export is fully generated, the status becomes **Completed**. +* **Time Frame of Export** – +* **Download** – This link is displayed if the export CSV is ready for download. + +## Retrieving Audit Logs via API + +You can use the [Audit Logging API](/apidocs-mxsdk/apidocs/apis-for-audit-logs/) to manage and download audit logs. This API is particularly useful in scenarios where you want to download audit logs that are over 90 days old, but no more than one year old. diff --git a/content/en/docs/control-center/security/private-connectivity/_index.md b/content/en/docs/control-center/security/private-connectivity/_index.md index 92e57388db5..27f777371b7 100755 --- a/content/en/docs/control-center/security/private-connectivity/_index.md +++ b/content/en/docs/control-center/security/private-connectivity/_index.md @@ -3,7 +3,7 @@ title: "Private Connectivity" linktitle: "Private Connectivity" url: /control-center/private-connectivity/ description: "Describes the Private Connectivity section in the Mendix Control Center." -weight: 30 +weight: 40 beta: true --- diff --git a/content/en/docs/control-center/security/set-up-sso-byoidp.md b/content/en/docs/control-center/security/set-up-sso-byoidp.md index 64a803f078f..fcfe7d115b6 100644 --- a/content/en/docs/control-center/security/set-up-sso-byoidp.md +++ b/content/en/docs/control-center/security/set-up-sso-byoidp.md @@ -1,7 +1,7 @@ --- title: "Setting Up an SSO (BYOIDP)" url: /control-center/security/set-up-sso-byoidp/ -weight: 40 +weight: 50 description: "Describes how you can use your company IdP to authenticate to Mendix." aliases: - /developerportal/control-center/set-up-sso-byoidp/ diff --git a/static/openapi-spec/audit-logging-v1.yaml b/static/openapi-spec/audit-logging-v1.yaml new file mode 100755 index 00000000000..800251cec11 --- /dev/null +++ b/static/openapi-spec/audit-logging-v1.yaml @@ -0,0 +1,519 @@ +openapi: 3.1.1 +info: + title: Audit Logging API V1 + version: 1.0.0 +# Multiple docs +servers: + - url: https://audit-api-prod.datalab.mendix.com/v1 +x-logo: + url: https://mendix.com/logo.png + altText: Audit Logging API Logo +x-termsOfService: https://mendix.com/terms +x-contact: + name: Support Team + url: https://mendix.com/support +paths: + "/logs": + get: + tags: + - Audit Logs + summary: Retrieve audit logs + operationId: getAuditLogs + security: + - SSOToken: [] + - PAT: [] + description: | +

Retrieves a list of audit logs filtered by Owner ID with pagination, sorting, and filtering support.

+

The Owner ID is derived from the token used in the request.

+

Logs cannot be retrieved for an Owner ID that is different to the one in the token.

+

Authorization

+

Authorization: Bearer <sso_token> or Authorization: MxToken <token>

+

Requires the mx:audit-logging:read scope.

+ parameters: + - $ref: "#/components/parameters/eventOutcome" + - $ref: "#/components/parameters/resourceId" + - $ref: "#/components/parameters/contextId" + - $ref: "#/components/parameters/contextType" + - $ref: "#/components/parameters/resourceType" + - $ref: "#/components/parameters/searchQuery" + - $ref: "#/components/parameters/fromDate" + - $ref: "#/components/parameters/toDate" + - $ref: "#/components/parameters/page" + - $ref: "#/components/parameters/limit" + - $ref: "#/components/parameters/sortBy" + - $ref: "#/components/parameters/sortOrder" + responses: + '200': + $ref: "#/components/responses/LogsResponse" + '400': + $ref: "#/components/responses/Error400" + '401': + $ref: "#/components/responses/Error401" + '403': + $ref: "#/components/responses/Error403" + '500': + $ref: "#/components/responses/Error500" + "/logs-chain": + get: + tags: + - Audit Logs + summary: Retrieve audit logs chain + description: | +

Retrieves a chain of audit logs for a specific owner. If a cursor is not provided, the first page is returned.

+

Output is ordered chronologically, from newest to oldest.

+

Authorization

+

Authorization: Bearer <sso_token> or Authorization: MxToken <token>

+

Requires the mx:audit-logging:read scope.

+ operationId: getAuditLogsChain + security: + - SSOToken: [] + - PAT: [] + parameters: + - $ref: "#/components/parameters/cursor" + - $ref: "#/components/parameters/chainLimit" + responses: + '200': + $ref: "#/components/responses/LogsChainResponse" + '400': + $ref: "#/components/responses/Error400" + '401': + $ref: "#/components/responses/Error401" + '403': + $ref: "#/components/responses/Error403" + '500': + $ref: "#/components/responses/Error500" + +components: + parameters: + eventOutcome: + name: eventOutcome + in: query + required: false + schema: + type: string + description: The outcome of the event + example: "Success" + resourceId: + name: resourceId + in: query + required: false + schema: + type: string + description: The unique identifier for the affected resource + example: "resource-123" + contextId: + name: contextId + in: query + required: false + schema: + type: string + description: The unique identifier for the affected resource context + example: "context-456" + contextType: + name: contextType + in: query + required: false + schema: + type: string + description: The type of Context + example: "Environment" + resourceType: + name: resourceType + in: query + required: false + schema: + type: string + description: The type of resource (e.g., Company, User, Environment) + example: "Company" + searchQuery: + name: q + in: query + required: false + schema: + type: string + description: Search query + example: "Control Center" + fromDate: + name: from + in: query + required: false + schema: + type: string + format: date-time + description: Start date filter, ISO 8601 UTC format + example: "2024-06-01T00:00:00Z" + toDate: + name: to + in: query + required: false + schema: + type: string + format: date-time + description: End date filter, ISO 8601 UTC format + example: "2025-10-01T23:59:59Z" + page: + name: page + in: query + required: false + schema: + type: integer + default: 1 + description: Page number for pagination + limit: + name: limit + in: query + required: false + schema: + type: integer + default: 50 + maximum: 100 + description: Maximum number of items per page. The default is 50, the maximum is 100. + sortBy: + name: sortBy + in: query + required: false + schema: + type: string + enum: + - timestamp + - logId + description: Field to sort by + sortOrder: + name: sortOrder + in: query + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + description: Sort order + cursor: + name: cursor + in: query + required: false + schema: + type: string + description: Base64 encoded cursor for pagination, generated from the last logId and timestamp. If not provided, the first page is returned. + chainLimit: + name: limit + in: query + required: false + schema: + type: integer + default: 25 + maximum: 100 + description: Maximum number of items per page. The default is 25, and the maximum is 100. + responses: + LogsResponse: + description: Audit logs retrieved successfully + content: + application/json: + schema: + type: object + properties: + pagination: + $ref: "#/components/schemas/pagination" + cursors: + $ref: "#/components/schemas/cursors" + items: + type: array + description: List of audit logs for the current page + items: + $ref: "#/components/schemas/AuditLog" + LogsChainResponse: + description: Audit logs chain retrieved successfully + content: + application/json: + schema: + type: object + properties: + cursors: + $ref: "#/components/schemas/cursors" + pagination: + $ref: "#/components/schemas/pagination" + items: + type: array + description: List of audit logs in the chain + items: + $ref: "#/components/schemas/AuditLog" + Error400: + description: Bad request, invalid input + content: + application/json: + schema: + $ref: "#/components/schemas/Error400" + Error401: + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/Error401" + Error403: + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/Error403" + Error500: + description: Internal server error, please try again later + content: + application/json: + schema: + $ref: "#/components/schemas/Error500" + securitySchemes: + SSOToken: + type: http + scheme: bearer + bearerFormat: JWT + # Support both Bearer tokens and MxTokens + description: | + Use Bearer $SSO_TOKEN_HERE for Mendix SSO tokens. Scope required: mx:audit-logging:read. + PAT: + type: apiKey + in: header + name: Authorization + description: | + Use MxToken $PAT_TOKEN_HERE for Personal Access Tokens. Scope required: mx:audit-logging:read. + schemas: + AuditLog: + type: object + required: + - logId + - timestamp + - ownerId + - ownerIdType + - internalService + - externalService + - client + - event + properties: + logId: + type: string + description: Unique identifier of the audit log record + timestamp: + type: string + format: date-time + description: Date time the event occurred, in ISO 8601 UTC format + ownerId: + type: string + description: The unique identifier of the owner + ownerIdType: + type: string + enum: + - CompanyID + - PlatformAccountID + description: The type of ownerId. Only CompanyID and PlatformAccountID are supported. + internalService: + type: string + description: This field identifies the service that produced the audit log, and can be used to retrieve logs for the service. + example: "Backups" + externalService: + type: string + enum: + - Mendix Portal + - Deployment + - Control Center + - Marketplace + - Compass + - Portfolio + - Catalog + description: The external system or service involved in the event + client: + $ref: "#/components/schemas/Client" + event: + $ref: "#/components/schemas/Event" + Client: + type: object + required: + - userName + - userAccountEmail + properties: + userUuid: + type: string + description: UserID of the logged in user + userAccountEmail: + type: string + format: email + description: Email of the user who performed the action + userName: + type: string + description: Name of the logged in user + ipAddress: + type: string + format: ipv4 + description: IP address from where the request originated + originType: + type: string + enum: + - User + - API + - SystemScheduledTask + description: Source of the request + Event: + type: object + required: + - action + - description + - outcome + properties: + action: + type: string + description: Action taken + description: + type: string + description: Description of the event, clarifying what happened + outcome: + type: string + enum: + - SuccessAction + - Error + - Warning + - FailedAudit + - SuccessAudit + description: Result of the event + errorMessage: + type: string + description: Details about the outcome, especially in case of failure + oldValue: + type: string + description: Previous value before the change + newValue: + type: string + description: New value after the change + resource: + $ref: "#/components/schemas/Resource" + context: + $ref: "#/components/schemas/Context" + ContextAndResourceType: + type: string + enum: + - Company + - Project + - Environment + - GenAIResource + - User + - ProjectRole + - Portfolio + - MarketplaceComponent + - Story + - Epic + - FeedbackItem + - Backup + - Page + - AppLog + - AccessLog + - AuditLog + - ApprovalRequest + Resource: + type: object + properties: + resourceId: + type: string + description: Unique identifier for the affected resource + resourceType: + $ref: "#/components/schemas/ContextAndResourceType" + description: Type of resource (e.g., Company, User, Environment) + name: + type: string + description: Name of the resource + description: + type: string + description: Details of the resource + Context: + type: object + properties: + contextId: + type: string + description: Unique identifier for the affected resource context + contextType: + $ref: "#/components/schemas/ContextAndResourceType" + description: Type of Context + name: + type: string + description: Name of the resource context + description: + type: string + description: Details + Error400: + type: object + properties: + error: + type: object + properties: + status: + type: integer + example: 400 + message: + type: string + example: "Bad request, invalid input" + Error401: + type: object + properties: + error: + type: object + properties: + status: + type: integer + example: 401 + message: + type: string + example: "Unauthorized, please provide valid credentials" + Error403: + type: object + properties: + error: + type: object + properties: + status: + type: integer + example: 403 + message: + type: string + example: "Forbidden" + Error500: + type: object + properties: + error: + type: object + properties: + status: + type: integer + example: 500 + message: + type: string + example: "Internal server error, please try again later" + pagination: + type: object + properties: + self: + type: string + description: URL of the current page + page: + type: integer + description: Current page number + pageSize: + type: integer + description: Number of items in the current page + total: + type: integer + description: Total number of items across all pages + cursors: + type: object + properties: + self: + type: string + description: URL of the current page + prev: + type: string + description: URL of the previous page, if available + next: + type: string + description: URL of the next page, if available + first: + type: string + description: URL of the first page + last: + type: string + description: URL of the last page