Service extensions are custom Go functions that you inject at specific hook points in the Orchestrator’s request processing pipeline. They use Go syntax but execute within an embedded Go runtime inside the Orchestrator process — you do not compile or build plugins. Service extension code cannot run independently outside the Orchestrator. Service extensions let you customize authentication, authorization, claims building, routing, session management, and API handling without modifying the Orchestrator itself.The Orchestrator provides 30 hook points across the request lifecycle, organized by concern in the pages below.
When the Orchestrator starts, it loads your Go source code and executes it through an embedded Go runtime. At each configured hook point, the Orchestrator calls your named function, passing an api parameter that provides access to the full Orchestrator interface — sessions, caches, secrets, identity providers, logging, and more.Service extension code can be delivered in two ways:
File reference — point to an external .go source file on disk. Preferred for production use because it supports version control, IDE tooling, and independent testing.
Inline code — embed Go source directly in the YAML configuration. Convenient for short, self-contained extensions.
The basic function signature follows this pattern:
The exact function signature varies by hook point. Some hooks omit the rw or req parameters, some return an error. Refer to the individual hook pages below or the SDK documentation for each hook’s expected signature.
The api parameter passed to your extension function implements the orchestrator.Orchestrator interface, which provides access to all subsystem interfaces:
Interface
Access Via
Purpose
Orchestrator
api parameter
Main entry point — provides access to all other interfaces
The Orchestrator provides 30 service extension hook points organized by lifecycle area. Each hook is a field on the relevant configuration object. Select a hook name to see its full signature, parameters, and usage details.
Custom API endpoints are managed through the Service Extensions area in the Console. In the Console sidebar, select Service Extensions and then API to create, edit, and manage custom API endpoints. APIs are attached to deployments from the deployment’s Settings page alongside applications.
Use file for production deployments — it keeps extension code in version control and enables IDE support. Use inline code for short, self-contained extensions where a separate file adds unnecessary overhead.
Always check and handle errors returned by SDK methods. Log errors with sufficient context to diagnose issues in production. A panicking extension can disrupt the Orchestrator’s request processing for the affected hook point.
Use the SDK logger (api.Logger()) instead of fmt.Println or the standard log package. The SDK logger integrates with the Orchestrator’s structured logging pipeline and supports key-value pairs for searchable log entries.
Use api.SecretProvider() to retrieve secrets at runtime from configured providers (Vault, AWS Secrets Manager, Azure Key Vault, etc.). Never hardcode credentials, API keys, or certificates in extension code.
Copy
apiKey, err := api.SecretProvider().GetString("my-api-key")if err != nil { api.Logger().Error("se", "failed to retrieve API key", "error", err.Error()) return}
Keep extensions lightweight, especially in hot-path hooks like modifyRequestSE and modifyResponseSE that execute on every proxied request. Use api.Cache() for expensive lookups to avoid redundant calls to external systems.
When making outbound HTTP requests from a service extension, always reuse HTTP clients through the api.HTTP() interface rather than creating a new http.Client per request. Creating clients per request prevents connection pooling, repeats TLS handshakes, and can lead to socket exhaustion under load.For most use cases, api.HTTP().DefaultClient() provides a ready-to-use client with sensible defaults:
When you need separate clients with different configurations (e.g., distinct timeouts or transport settings for different upstream services), use api.HTTP().SetClient() and api.HTTP().GetClient() to register and retrieve named clients:
Copy
func CallAPIs(api orchestrator.Orchestrator, rw http.ResponseWriter, req *http.Request) { log := api.Logger() // Register a named client once; subsequent calls to GetClient return the same instance. _, err := api.HTTP().GetClient("payments-api") if err != nil { paymentsClient := &http.Client{Timeout: 5 * time.Second} api.HTTP().SetClient("payments-api", paymentsClient) } client, _ := api.HTTP().GetClient("payments-api") resp, err := client.Get("https://payments.example.com/charge") if err != nil { log.Error("se", "payments request failed", "error", err.Error()) return } defer resp.Body.Close() // Process the response.}
Named clients registered with SetClient persist for the lifetime of the Orchestrator process. Use descriptive names (e.g., "payments-api", "identity-service") to avoid collisions between extensions.
Do not rely on global variables or package-level state between requests. The Orchestrator may run multiple instances, and the runtime does not guarantee state persistence across configuration reloads. Use api.Session() for request-scoped state and api.Cache() for cross-request state.
Follow a staged workflow to minimize risk when deploying service extensions:
Develop locally — write and test your extension code against the SDK interfaces. Use Go tooling (formatting, linting, type checking) during development even though extensions run interpreted.
Deploy to staging — deploy the extension to a non-production Orchestrator instance connected to test identity providers and backend services.
Static analysis limitations: Because service extensions execute inside the Orchestrator’s embedded runtime with injected SDK interfaces, standard static code analysis tools (SAST, linters with security rules) may not produce meaningful results. The most effective way to validate security behavior is to deploy your extension to a test environment and exercise the actual authentication, authorization, and data-handling scenarios your extension participates in.
Verify behavior — use structured logging (api.Logger()) to trace extension execution. Check Orchestrator logs for errors, unexpected behavior, or performance issues.
Promote to production — after verifying correct behavior in staging, deploy the extension to production. Monitor Orchestrator logs after deployment for errors from extension code.
Service extensions execute custom user-authored code within the Orchestrator process. You are responsible for the correctness, security, and performance of your extension code. Strata provides the Service Extension SDK and runtime environment but does not audit, review, or warranty custom extension logic.
