System Settings and Configuration API

Overview

The Settings API provides a collection of administrative endpoints for managing the platform's system-wide configuration. It is the primary interface for operators to view and modify settings related to installation profiles, authentication modes, F5 integration, Identity-Aware Proxy (IAP) access, permission bindings, and software update channels.

This API is designed for programmatic and UI-driven administration. It centralizes configuration management, provides tools for integrating with external systems like F5 BIG-IP, and reports on system status. All write operations are audited, recording the actor, their role, and the changes made.

Key capabilities include:

• Reading and updating a map of key-value system settings.
• Managing role-based access control (RBAC) through permission bindings.
• Interacting with an F5 BIG-IP device to test connections, scan policies, and configure log forwarding.
• Viewing the status of the installation profile, authentication mode, and F5 traffic ingestion.
• Retrieving historical alert data.

How it Works

The Settings API is implemented as a set of REST endpoints within the administration service. Different endpoints handle specific domains of configuration, but the core logic for general settings resides in the PATCH /admin/v1/settings endpoint.

General Settings Updates

When an API consumer sends a PATCH /admin/v1/settings request, the system performs the following sequence of operations:

1. Fetch Current State: The system retrieves the current effective settings map.
2. Credential Guard: It checks if the update attempts to change the target (e.g., hostname, username) for a configured secret (e.g., F5, SMTP password) without re-supplying the secret. This security measure prevents sending a stored password to a new, unverified endpoint.
3. Normalize Payload: The incoming update payload is normalized. For example, if any f5_* settings are modified, related fields like f5_discovery_mode and f5_ingest_enabled are automatically populated to ensure a consistent state.
4. Persist Changes: The normalized updates are persisted to the system settings repository.
5. Trigger Side Effects: Based on the keys included in the update, the system triggers specific side effects:
   • install_profile: The installation profile cache is invalidated immediately, ensuring UI elements and feature gates reflect the change without delay.
   • update_channel: If the update channel is explicitly changed by an operator, a marker is set to prevent a future license-based backfill from overwriting the operator's choice.
   • update_* keys: Any change to a key starting with update_ invalidates the update channel status cache. This ensures the UI reflects the new update settings immediately after saving.
   • request_validation_* or response_validation_* keys: A log entry is generated to inform operators that global validation defaults have changed. Downstream services that cache this configuration will pick up the new settings after their cache TTL expires (typically 15 seconds).
   • iap_access_members: The list of members is persisted to the Identity Provider (IdP) configuration and synchronized with the underlying IAP access policy.
6. Audit: A success event is recorded in the audit log, capturing the "before" and "after" state of the settings.
7. Respond: The final, updated map of all effective settings is returned in the response body.

F5 Integration and Settings Resolution

The F5 integration endpoints (/admin/v1/settings/f5/*) allow interaction with an F5 BIG-IP device. When calling these endpoints, you can either rely on the F5 credentials already saved in the system settings or provide them directly in the request body.

The system uses a specific resolution logic (resolveF5Settings):

• For each connection parameter (managementUrl, partition, policyName, username), the value from the request body is preferred.
• If a parameter is absent in the request, the system falls back to the corresponding value from the saved system settings (e.g., f5_management_url).
• The password is read from the system's encrypted storage. A password supplied in the request body takes precedence.

F5 Log Forwarding

The platform can ingest traffic logs from an F5 device to learn about API activity. This typically involves a log relay.

flowchart TD
    A[F5 Device] -- Syslog --> B[Log Relay Target]
    B -- HTTPS --> C[Platform Ingest Endpoint]

1. The F5 Device is configured to forward logs for a specific policy to a syslog server.
2. This server is the Log Relay Target, whose address is configured in the platform via the f5_log_receiver_address setting or the S2R_DISCOVERY_INGEST_LOG_RELAY_TARGET environment variable.
3. The relay converts the syslog messages to HTTPS and forwards them to the Platform Ingest Endpoint (/ingest/v1/f5/traffic), which is derived from the f5_ingest_public_url setting or the request's origin.

The POST /admin/v1/settings/f5/log-forwarding/apply endpoint automates the F5 configuration for this process.

API Endpoints

General Settings

Get All System Settings

Retrieves a map of all effective system settings.

• Endpoint: GET /admin/v1/settings
• Response Body: A JSON object containing key-value pairs of all system settings.

Update System Settings

Applies a partial update to the system settings. Only the keys provided in the request body are modified.

• Endpoint: PATCH /admin/v1/settings
• Request Body: A JSON object where keys are setting names and values are the new setting values.
• Response Body: On success, returns the complete, updated map of all effective system settings.
• Special Behavior:
  • If the update to iap_access_members succeeds but the subsequent persistence or sync fails, the response body will contain a _iapPersistWarning or _iapSyncWarning field with an error message.
• Error Responses:
  • 400 Bad Request (S2R-VAL-0401): If the request is invalid (e.g., invalid value for a setting, or changing a credentialed target without re-supplying the secret).
  • 502 Bad Gateway (S2R-ADM-0502): If an internal error occurs during processing.

Get Installation Profile

Returns the current installation profile and related feature flags. This is used by the UI to show or hide components, such as those specific to F5 integration.

• Endpoint: GET /admin/v1/settings/install-profile

• Response Body:

  {
    "profile": "f5_modernization",
    "f5Enabled": true,
    "isF5Modernization": true,
    "isGenericSoapToRest": false,
    "isBoth": false,
    "f5Configured": true,
    "deploymentMode": "byoc",
    "isSaas": false
  }
  

  Response Fields

Get Authentication Mode

Returns the current authentication mode of the platform.

• Endpoint: GET /admin/v1/settings/auth-mode
• Response Body:

Get IAP Status

Returns the synchronization status of the Identity-Aware Proxy (IAP) access list.

• Endpoint: GET /admin/v1/settings/iap-status
• Response Body:

Get Alert Mail History

Retrieves a list of recently sent alert emails.

• Endpoint: GET /admin/v1/settings/alert-mail-history
• Query Parameters:

• Response Body: An array of alert mail history objects. The source does not specify the exact structure of these objects.

F5 Integration

The following endpoints interact with an F5 BIG-IP device. For each endpoint, the request body is optional. If provided, its values override the saved system settings for the duration of the call.

Request Body (F5Request)

Test F5 Connection

Tests the connection and authentication to the F5 BIG-IP management interface.

• Endpoint: POST /admin/v1/settings/f5/test-connection
• Response Body: A map containing connection status details, including an overallStatus field.

Scan F5 Policy

Scans a specified F5 policy to discover its configuration.

• Endpoint: POST /admin/v1/settings/f5/scan
• Response Body: A map containing scan results, including an overallStatus field.

Probe F5 WSDL Candidates

Probes an F5 policy's virtual servers to identify potential WSDL endpoints.

• Endpoint: POST /admin/v1/settings/f5/wsdl-probe
• Query Parameters:

• Response Body: A map containing probe results, including an overallStatus field.

Preview F5 Log Forwarding Configuration

Generates a preview of the configuration changes required to set up log forwarding on the F5 device.

• Endpoint: POST /admin/v1/settings/f5/log-forwarding/preview
• Request Body: F5LogForwardingRequest (see table below).
• Response Body: A map containing the preview details, including an overallStatus field.

Apply F5 Log Forwarding Configuration

Applies the configuration to the F5 device to enable log forwarding to the platform's ingest endpoint.

• Endpoint: POST /admin/v1/settings/f5/log-forwarding/apply
• Request Body: F5LogForwardingRequest (see table below).
• Response Body: A map containing the result of the operation, including an overallStatus field.

Request Body (F5LogForwardingRequest)

This request body includes all fields from F5Request plus the following:

F5 Status and Learning

Get F5 Learning Summary

Retrieves a summary of API traffic learned from F5 logs.

• Endpoint: GET /admin/v1/settings/f5/learning-summary
• Query Parameters:

Get F5 Ingest Status

Provides a detailed status of the F5 log ingestion configuration and state.

• Endpoint: GET /admin/v1/settings/f5/ingest-status
• Response Body: A JSON object with fields like enabled, ingestEnabled, receiverAddress, publicIngestUrl, lastLearnedAt, and lastTrafficAt.

Get F5 Defaults

Returns default and dynamically-derived values for F5 configuration, such as the public ingest URL.

• Endpoint: GET /admin/v1/settings/f5/defaults
• Response Body: A JSON object with fields like publicIngestUrl, receiverAddress, and transportProtocol.

Permission Bindings

Get Permission Bindings

Retrieves all active principal-to-role bindings.

• Endpoint: GET /admin/v1/permission-bindings
• Response Body: An array of permission binding objects. The source does not specify the exact structure.

Add or Update a Permission Binding

Creates a new permission binding or updates an existing one for a given principal (email) and role.

• Endpoint: POST /admin/v1/permission-bindings
• Request Body:

• Response Body: The created or updated permission binding object.
• Error Responses:
  • 400 Bad Request (S2R-VAL-0401): If the request is invalid (e.g., missing fields, invalid role).

Delete a Permission Binding

Removes a permission binding by its unique ID.

• Endpoint: DELETE /admin/v1/permission-bindings/{bindingId}
• Path Parameters:

• Response Body:

  {
    "deleted": true,
    "bindingId": "..."
  }
  

• Error Responses:

  • 400 Bad Request (S2R-VAL-0401): If the bindingId does not correspond to an existing binding.

System Settings Reference

The following system setting keys are referenced in the controller and can be managed via the PATCH /admin/v1/settings endpoint.

| Setting Key | Description | install_profile | The installation profile (f5_modernization, generic_soap_to_rest, both). Changing this invalidates a cache to immediately reflect the change. | update_channel | The software update channel (internal, beta, early-access, release). An operator can set any valid channel. Changing this value prevents it from being overwritten by a license-based default. | update_* | Any setting prefixed with update_ (e.g., update_mode, update_window). Changing any of these invalidates the update status cache. | request_validation_* | Global defaults for request validation. Changing these logs a message about a 15-second cache propagation delay for runtime routes. | response_validation_* | Global defaults for response validation. Changing these logs a message about a 15-second cache propagation delay for runtime routes. | iap_access_members | A string containing a list of member emails for IAP access. The system parses this list and persists it to the IdP configuration. | f5_management_url | The URL of the F5 BIG-IP management interface. | f5_password | The password for the F5 management user. This is a write-only secret. | f5_username | The username for the F5 management interface. | alert_smtp_* | Settings for the SMTP server used to send email alerts, including alert_smtp_host, alert_smtp_port, alert_smtp_username, and alert_smtp_password. Subject to the same credential guard as F5 settings.

Troubleshooting

Error Responses

• 400 Bad Request with error code S2R-VAL-0401:

  • Cause: The request payload is invalid. This can happen if required fields are missing, if a value has an incorrect format, or if a security check fails.
  • Trigger: A common trigger is changing a credential's target (e.g., f5_management_url, alert_smtp_host) without re-supplying the corresponding password in the PATCH /admin/v1/settings request.
  • Meaning: The requested change was rejected and not persisted. The response body contains a specific error message.

• 502 Bad Gateway with error code S2R-ADM-0502:

  • Cause: An unexpected internal error occurred while processing the request.
  • Meaning: The operation may have partially or completely failed. Check the admin service logs for more details.

Partial Success Warnings

When updating settings via PATCH /admin/v1/settings, the core settings may be saved successfully, but a subsequent side effect might fail. In these cases, the API returns a 200 OK response with a warning field in the body.

• _iapPersistWarning: The iap_access_members setting was saved, but writing the member list to the IdP configuration table failed.
• _iapSyncWarning: The iap_access_members setting was saved, but synchronizing the new list with the IAP policy failed.

In both cases, the system state may be inconsistent. The saved setting and the active policy may not match.

Cache Propagation Delays

When you modify global API validation defaults (settings prefixed with request_validation_ or response_validation_), the changes are not instantaneous across all runtime instances. These settings are cached by downstream services.

• Symptom: After changing a validation setting, API traffic may continue to use the old rule for a short period.
• Cause: The runtime route cache has a default TTL of 15 seconds.
• Resolution: The new settings will be picked up automatically after the cache expires. An informational log message (S2R-ADM-cache-invalidation) is generated when these settings are changed to help operators correlate the change with this settling period.

See Also

• Identity-Aware Proxy (IAP) Management
• Software Update Channel Configuration
• F5 BIG-IP Integration Guide

All SOAP-to-REST docs