Configure SIEM Delivery and Validate Events

Overview

Use SIEM Settings at /Admin/Siem to configure outbound security and audit event delivery to a SIEM endpoint. The screen is titled SIEM Integration Settings and supports Generic HTTP, Splunk, Microsoft Sentinel, and Elastic provider presets.

The admin UI reads GET api/v1/admin/siem/settings, saves with PUT api/v1/admin/siem/settings, and validates delivery with POST api/v1/admin/siem/settings/test.

Prerequisites

• The user must have tenant settings permission.
• The destination endpoint must be an absolute https:// URL.
• The SIEM destination must be reachable from the SchoolBanks API environment.
• Have the correct header name and secret/token ready before enabling delivery.

Step-by-step procedure

1. Open Admin.
2. In Integrations and Communication, select SIEM Settings (/Admin/Siem).
3. In Enable Delivery, switch on Enable SIEM delivery.
4. In Destination, select the provider and enter the endpoint URL.
5. In Authentication, enter the header name and token/API key. Leave the secret blank to keep an existing saved value.
6. In Event Content, choose whether to include descriptive message fields in the event payload.
7. In Transport Settings, set Request timeout seconds.
8. Select Save SIEM settings.
9. In Validate Delivery, select Send test event.
10. Review Last delivery status and, when failing, Last error.

Provider defaults

• Generic HTTP: header defaults to X-API-Key, authentication method defaults to HeaderToken, source/type defaults to schoolbanks.audit, and max batch size defaults to 100.
• Splunk: header is Authorization, authentication method is HeaderToken, source/type is schoolbanks:audit, and a bare HTTPS host is expanded to /services/collector.
• Microsoft Sentinel: header is x-ms-workspace-shared-key, authentication method is SharedSecretAndSignature, source/type is SchoolBanksAudit, and default max batch size is 50.
• Elastic: header is Authorization, authentication method is AuthorizationBearerToken, source/type is schoolbanks.audit, and default max batch size is 200.

Expected event content

Always included fields include event type, timestamp, actor identifier, tenant or organization identifier, and application identifier. When descriptive message fields are enabled, the payload can also include additional title/message content useful for analyst triage.

The test event uses:

• Source: Admin.Siem.Test
• Category: Configuration
• Severity: Info
• Title: SIEM test event
• Event type: siem.test

Variations / branching flows

• Disable delivery: turn off Enable SIEM delivery and save. Delivery is paused but configuration and historical audit data are retained.
• Keep existing secret: leave the secret/token field blank before saving.
• Change endpoint only: update provider/endpoint/header/timeout and leave the secret blank if credentials are unchanged.
• Validate after save: use Send test event only after the current settings have been saved.

Expected outcomes

• A successful save shows SIEM settings saved successfully. and returns to /Admin/Siem.
• A successful test shows SIEM test event sent successfully. and updates last successful delivery time.
• Last delivery status is Paused when disabled or delivery is paused, Failing when the last failure is newer than the last success, and Healthy otherwise.
• On test failure, the API records LastFailureUtc and LastErrorMessage. If failure handling is PauseDeliveryRequireAdminIntervention, delivery is paused.

Troubleshooting / edge cases

• SIEM requires an absolute HTTPS destination URL: use a full https:// endpoint, not HTTP or a relative path.
• Replacing credentials requires explicit replace secret confirmation: the API rejects a nonblank secret when ReplaceSecret is false.
• Secret value is required when replace secret is selected: provide the token/API key when explicitly rotating credentials.
• SIEM settings are not configured: save settings before selecting Send test event.
• Last delivery status is Failing: review Last error, endpoint reachability, provider-specific path, header name, token, and request timeout.
• Splunk test fails: confirm the endpoint includes /services/collector and the authorization header format matches the Splunk HEC token expectation.
• Delivery pauses after failure: correct the endpoint or credential issue, save settings, and send another test event.

Related processes

• Configure Tenant Settings and Options
• Update Tenant Information

Assumptions and gaps

• The current Razor form exposes a secret/token input but does not show a visible ReplaceSecret checkbox. If credential rotation fails with a replace-secret message, use the API path or update the UI to send ReplaceSecret = true.
• The UI currently shows provider, endpoint, header name, secret/token, descriptive-message toggle, request timeout, save, and test status. Additional request contract fields exist for delivery mode, retry policy, event categories, request context, and environment, but they are not exposed as separate controls on the current screen.