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.

• Methods - The orchestrator.go library is a blueprint and provides methods for any orchestrator used in your service architecture.

• Additional third party packages - The orchestrator supports a number of third-party packages that could be imported in service extensions.

Assets

Assets in service extensions refer to files. These can be HTML templates, static images, configuration files, or other runtime resources. These will be bundled into the deployment 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

Service Extension Settings

Claims

If your service extension requires claims:

1. Define the claims in the Service Extension Editor, and 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.

Dependencies

In your service extension you can use Identity Fabric connectors to IDPs, attribute providers and Continuity Strategies. In order for the proper configuration to be deployed, add them as a dependency.

1. In the Provider section of the Service Extension editor, click Add. Use the providers 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.

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.

Metadata changes made in this section only apply to the user flow and do not apply to the parent service extension.

1. In the Metadata section from the Service Extension editor, 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

1. In a user flow, navigate to the service extension point (such as Authentication or Attribute Providers) and select your service extension.

2. If the service extension has editable metadata values, a pencil icon will appear. Click it to open the metadata editor.

Workflow Notes

• Name changes propagate globally: When you update the name in the service extension editor, the change applies everywhere that service extension is used.

• Value overrides are independent: Updating default values in the service extension editor does not affect any values that have already been overridden in individual user flows. Overridden values remain unchanged.

• Key pair changes propagate globally: Adding or deleting metadata key pairs in the service extension editor affects all instances where the service extension is used.

• Shared metadata across references: If you reference the same service extension multiple times within a single user flow, any metadata edits you make will apply to all of those references simultaneously.

Enable Libraries

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.