Service extensions

Prev Next

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)

Name

Description

Global

OIDC

SAML

Proxy

API Application Type

serveSE - Found in Applications, this API app pattern enables you define a custom APIs.

Authentication

isAuthenticatedSE - Determines if a user is already authenticated.

authenticateSE - Controls the authentication behavior.

Authorization

isAuthorizedSE - Overrides the default authorization behavior.

Back Channel Authentication

backchannel.authenticateSE - used to take control of how end-user authentication will be done for backchannel OIDC flows such as Resource Owner Password Credentials Grant

Build User Info Claims

buildUserInfoClaimsSE- Found in Deployments in the OIDC Provider Settings, this enables you to customize the claims returned by the userinfo endpoint.

Custom Claims

buildClaimsSE - Customizes attributes added to SAML 2.0 Attribute Statement.

buildIDTokenClaimsSE - Customizes claims in the OIDC ID token.

buildAccessTokenClaimsSE - Customizes claims in the OIDC access token.

Evaluate Idle Session Timeout

evalIdleTimeoutSE - Found in Deployments in the Session and Cookies section, this enables a global control on how session idle timeouts are handled.

Evaluate Max Session Lifetime

evalMaxLifetimeSE - Found in Deployments in the Session and Cookies section, this enables a global control on how session idle timeouts are handled.

Handle Unauthorized

handleUnauthorizedSE - used  in a Proxy Application Pattern  to override the default behavior when a policy evaluation denies access to the app.

HTTP Header Creation

createHeaderSE - used in a Proxy Application Pattern to creates a custom HTTP headers, often for attribute enrichment.

Load Attributes

loadAttrsSE - Customizes how attributes are loaded, often from enterprise APIs.

Modify Request

modifyRequestSE - used in a Proxy Application Pattern Modifies every HTTP request passing through the app.

Modify Response

modifyResponseSE - used in a Proxy Application Pattern to modifies every HTTP response passing through the app.

Post Single Logout

postLogoutSE - found in Deployments in the Single Logout section, this globally controls the behavior after a logout has occurred. This Service Extension is executed before the redirect to the Logout Redirect occurs.

Relay State

buildRelayStateSE - Builds the RelayState parameter in an IDP-initiated login flow.

Upstream Application Login

isLoggedIn - determine if the proxied upstream application has been logged into.

login - used to log in to a proxied upstream application

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.

Authentication settings for service extensions, including function names and library permissions.

Click to enlarge

  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.

Click to enlarge

Click to enlarge

  • 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

Click to enlarge

Data types supported

Data Type

Description

Example

String

Sequence of characters, which may include letters, numbers, symbols, and whitespace

default, red, admin, https://myendpoint.api

Boolean

true or false

true

Struct

A way to group related data together under one name. It’s like a container that holds several values (called fields), each with its own name and type.

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

Integer

A whole number

42

Float

Type of number that can have a decimal point

3.14159

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.