Backend Profile Configuration

Overview

A Backend Profile encapsulates all the configuration required for the platform to connect to a specific upstream API backend. Each profile is associated with a single Service and defines properties such as the backend's endpoint URL, authentication method, connection timeouts, and retry logic.

API publishers create and manage backend profiles to control how incoming requests to a Service are proxied to the appropriate upstream implementation. A single Service can have multiple backend profiles, allowing for different routing strategies (e.g., for different environments or versions) and A/B testing using routing weights.

This component is responsible for the persistence and management of BackendProfileRecord entities. It handles the Create, Read, Update, and Delete (CRUD) operations, including the secure, encrypted storage of credentials. All operations are strictly scoped to the authenticated user's tenant to prevent cross-tenant data access.

How it works

The BackendProfileRepository manages records in the s2r_backend_profile database table. The core logic revolves around validating, normalizing, and securely persisting profile data.

Data Storage and Security

• Tenancy: All database queries include a tenant-scoping clause (AND_TENANT_SCOPE). This ensures that an API publisher in one tenant cannot read, modify, or delete backend profiles belonging to another tenant.
• Credential Encryption: Any credentials provided in a profile, such as passwords, API keys, or OAuth2 client secrets, are serialized into a JSON object and encrypted using the CredentialsCipher before being stored in the database. When a profile is read, the system attempts to decrypt this data. If decryption fails (e.g., due to a key rotation), the credentials field will be empty, and the operator must re-enter them.
• Credential Normalization: Before encryption, the system normalizes the credentials map. It includes only the fields relevant to the specified auth_type and mtls_enabled flag. This ensures that no extraneous or incorrect credential data is stored. For example, if auth_type is basic, only username and password fields are retained in the credentials object.

Credential Target Protection

To prevent stored credentials from being inadvertently sent to an unauthorized destination, the system enforces a "credential target guard". When updating a backend profile that has stored credentials, if you change a target-defining field, you must re-submit the credentials in the same update request.

The following fields define the credential target:

• endpoint_url
• host_header
• oauth2_token_endpoint
• oauth2_client_id

If any of these fields are changed without providing the credentials payload, the update operation will fail with an error.

The following diagram illustrates the update logic, highlighting the credential target check.

flowchart TD
    A[Start Profile Update] --> B{New credentials provided?};
    B -->|Yes| C[Normalize & Encrypt new credentials];
    B -->|No| D{Credential target changed?<br>(URL, Host, OAuth endpoint/ID)};
    D -->|Yes| E[Reject update with error<br>"Re-enter the backend credentials..."];
    D -->|No| F[Keep existing stored credentials];
    C --> G[Prepare UPDATE statement];
    F --> G;
    G --> H[Execute UPDATE in database];
    H --> I[End];
    E --> I;

Default Profile Handling

Each Service can have one default_backend_profile_id.

• When a new profile is created with the setAsDefault flag set to true, it becomes the default for its associated Service.
• If a profile is created for a Service that has no default, it automatically becomes the default, regardless of the setAsDefault flag.
• When the current default profile is deleted, the system automatically pro<customer>es the most recently created, active profile for that Service to be the new default. If no other active profiles exist, the Service will have no default.

Backend Profile Parameters

A backend profile is defined by the following fields.

Authentication Types

The auth_type field determines the authentication mechanism used when connecting to the backend. The following values are supported:

• none: No authentication is performed.
• basic: HTTP Basic Authentication. Requires username and password in the credentials object.
• bearer: Bearer Token Authentication. Requires bearerToken in the credentials object.
• api_key_header: API Key sent in a custom HTTP header. Requires apiKeyHeaderName and apiKeyValue in the credentials object.
• oauth2_client_credentials: OAuth 2.0 Client Credentials Grant Flow. Requires oauth2_token_endpoint, oauth2_client_id, and credentials.oauth2ClientSecret.

Data Structures

Extra Headers

The extra_headers field is a list of name-value pairs. Each item in the list is an object with name and value string properties.

"extra_headers": [
  {
    "name": "X-Custom-Header",
    "value": "static-value"
  }
]

OAuth2 Extra Parameters

The oauth2_extra_params field is a list of name-value pairs to be included in the body of the token request for the oauth2_client_credentials flow. Each item is an object with name and value string properties.

"oauth2_extra_params": [
  {
    "name": "audience",
    "value": "https://api.example.com"
  }
]

Credentials Object

The credentials object is a map containing sensitive data. Its structure depends on the chosen auth_type and whether mtls_enabled is true. The system only stores fields relevant to the selected configuration.

• type: (String) Automatically added by the system to match the auth_type.
• username: (String) For basic auth.
• password: (String) For basic auth.
• bearerToken: (String) For bearer auth.
• apiKeyHeaderName: (String) For api_key_header auth. The name of the header.
• apiKeyValue: (String) For api_key_header auth. The value of the API key.
• oauth2ClientSecret: (String) For oauth2_client_credentials auth.
• extraHeaders: (List) A list of sensitive headers, structured like the main extra_headers field. These headers are stored encrypted. The same restricted header name rules apply.
• mtls: (Map) If mtls_enabled is true, this object contains the mTLS material (e.g., client key, client certificate). The source does not specify the exact structure of this map.

Troubleshooting

When creating or updating a backend profile, you may encounter the following errors.

All SOAP-to-REST docs