Service extensions

Overview

Maverics can be extended using service extensions, which are custom, Golang code that support arbitrary functionality such as retrieving and constructing complex attributes or defining and evaluating policies with logic not pre-built into an Orchestrator. Service extensions give administr/ators the ability to customize the behavior of the Maverics Orchestrator to suit the particular needs of their integration.

Service Extension Points (A-Z)

Service Extension Workflow

Creating a New Service Extension

1. From the main navigation select Service Extensions.

2. To start with a scaffolded function signature, select the appropriate Extension Point, see Service Extension Points (A-Z) above.

3. Provide a Name and Description for the extension.

4. The Function Name is a unique identifier for the service extension function name. Function names in Go must not contain spaces, and the first letter should be capitalized so that it can be exported (see idioms).

5. Click Create.

Service Extension Editor

Maverics Console’s built-in Go code editor supports basic linting, auto-complete, and validation. If you prefer to use a local development environment refer to the instructions in the service extension library repository.

Go Library Documentation

The Orchestrator exposes a library to aid in the development of extensions and to hook into underlying functionality in the Orchestrator. For example, you may want to log in to an IDP, query an attribute provider, or pull secrets from a secret store. To understand what functionality is available and how to use it, please see the library documentation.

Allow Protected Packages

Go packages not exposed by default that require explicit permission. For example, packages that provide on host file system access or sensitive I/O operations.

1. From the Service Extension Editor click Edit.

2. Under Enable libraries you can choose:

   • os - enables your service extension to interact directly with the host operating system. The os package provides functionality such as reading and writing environment variables, managing file paths, and accessing the filesystem. While powerful, this access introduces security risks, particularly in orchestrated environments where unmanaged file or system interactions could unintentionally expose sensitive data or create side effects across deployments.

   • os/exec The os/exec package goes a step further by allowing the execution of system-level commands and binaries. Granting access to this package means a service extension can spawn new processes, run shell commands, or interface with external tools on the host. This level of control is extremely potent and must be used with caution, as it can introduce significant security vulnerabilities if misused or exploited. For that reason, access to os/exec is restricted and must be explicitly enabled with full awareness of the risks.

Assets

Assets in service extensions refer to files—such as HTML templates, static images, configuration files, or other runtime resources—that are bundled and made accessible to the extension logic at runtime. For example, you might use assets to render a custom HTML error page or include a static JSON configuration used during processing. These assets are included into the deployment bundle, allowing seamless and secure access without relying on external file paths.

Implementation Components

The provided code snippet demonstrates three essential components when working with Service Extension Assets:

1. Upload your files (HTML, images, css files up to 2 mb in size) by clicking Upload.

2. Accessing the Assets API

   seAssets := api.ServiceExtensionAssets()

   This component:

   • Retrieves the Service Extension Assets interface from the orchestrator API

   • Provides access to all embedded files within the service extension bundle

   • Serves as the entry point for any file operations within the extension

   • Must be called before attempting to read any embedded files

3. Reading Files from the Assets Bundle

   idpForm, err := seAssets.ReadFile("idpForm.html")
   if err != nil {
       http.Error(
           rw,
           http.StatusText(http.StatusInternalServerError),
           http.StatusInternalServerError,
       )
       logger.Error("failed to open idpForm.html", err)
       return
   }
   
   _, _ = rw.Write([]byte(fmt.Sprintf(string(idpForm), req.FormValue("SAMLRequest"))))

   This component:

   • Uses the ReadFile() method to retrieve file contents as a byte array

   • Implements proper error handling if the file isn't found or can't be read

   • Processes the file contents (in this case, inserting a dynamic value into an HTML template)

   • Writes the processed content to the HTTP response writer

   • Demonstrates a practical use case (serving an authentication form from an embedded HTML template)

Together, these components enable service extensions to bundle and serve assets without external filesystem dependencies, improving portability and security.

You can view a sample implementation in the assets.go source file

Providers

You can use a providers defined in your Identity Fabric as part of your service extension.

1. From service extension editor, in the Provider section click Add. Use them in your code as you see fit.  See developer documentation for examples.

2. Select your provider defined in the Identity Fabric.

3. Select your service extension in the user flow or from Orchestrator Settings in Deployments.

4. When Published, the provider configuration your service extension needs will be deployed.

Claims

If your service extension requires claims:

1. Define the claims in the Service Extension Editor, use them in your code as you see fit.  See developer documentation for examples.

2. Select your service extension in the user flow.

3. Choose the attributes from defined list.

4. When Published, the claims configuration your service extension needs will be deployed.

Metadata

Metadata is an arbitrary set of key-value pairs that can be made available to a given extension. The values can be referenced from within the Go code, making service extensions more flexible and the configuration more obvious.

1. From the service extension editor, in the Metadata section, click Edit to define the metadata names and default values.

2. Reference them as variables in your go code. See developer documentation for examples.

3. Select your service extension in the user flow or from Orchestrator Settings in Deployments.

4. When Published, the metadata your service extension needs will be deployed.

Overriding the metadata values in a user flow

Requires Deployments Feature

On May 5th, we launched the updated Deployments experience (see release notes). To apply the metadata value overrides established on user flows, you must have this feature activated for your account. If the Deployments functionality is not enabled, any metadata value modifications on user flows will be disregarded, and the values defined in the service extension will be deployed.

If you notice “Environments” in your left navigation, please reach out to support@strata.io to request Deployments to be activated for your account.

• In a user flow, from the service extension point (e.g. Authentication, Attribute Providers), choose your service extension.

Current Service Extension Points Supported

• Authentication OIDC and SAML app user flows

• Load Attributes in OIDC, SAML, and Proxy apps

• More to come!

• Click the pencil icon to show the metadata editor.

• Choose the Type (see Data types supported), edit the value, and click Save.

  • If you add a new metadata field in the service extension editor, it will append it to all referenced user flows.

  • If you delete an existing metadata field in the service extension editor, it will delete it and any overrides from all referenced user flows.

Publish your changes

• From the app editor, user flow editor, or the Deployment Manager, click Publish Preview

Data types supported

{
  "employee": {
    "id": 101,
    "name": "Alice Johnson",
    "isActive": true,
    "roles": ["Developer", "Team Lead"],
    "contact": {
      "email": "alice.johnson@example.com",
      "phone": "555-1234"
    }
  }
}

Known Limitations

• This is currently limited to a few service extension points. More service extension points are forthcoming.

• The metadata editing experience in the service extension editor differs from the user flow editor. We will be improving the layout to unify this experience and show more data.

• When editing metadata values, there is a lack of interactive validation. If you insert incompatible data to the type you’ve selected, it will revert it to a string. Improved validation is coming soon with the updated editor.

For detailed examples and further guidance, refer to the Service Extensions documentation and the Strata GitHub repository.

For more information on configuring a custom service extension and code examples, see the service extension repository. Additionally, the on-premises Orchestrator documentation on service extensions can serve as a helpful reference.