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

From the main navigation select Service Extensions.
To start with a scaffolded function signature, select the appropriate Extension Point, see Service Extension Points (A-Z) above.
Provide a Name and Description for the extension.
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).
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

From the Service Extension Editor click Edit.
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:

Upload your files (HTML, images, css files up to 2 mb in size) by clicking Upload.
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
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.

From service extension editor, in the Provider section click Add. Use them in your code as you see fit. See developer documentation for examples.
Select your provider defined in the Identity Fabric.
Select your service extension in the user flow or from Orchestrator Settings in Deployments.
When Published, the provider configuration your service extension needs will be deployed.

Claims

If your service extension requires claims:

Define the claims in the Service Extension Editor, use them in your code as you see fit. See developer documentation for examples.
Select your service extension in the user flow.
Choose the attributes from defined list.
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.

From the service extension editor, in the Metadata section, click Edit to define the metadata names and default values.
Reference them as variables in your go code. See developer documentation for examples.
Select your service extension in the user flow or from Orchestrator Settings in Deployments.
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.

ℹ️ Limitations:
Currently you cannot edit metadata on following service extension points found within Deployments:
Post Single logout
Evaluation Max Session Lifetime
Evaluate Idle Session Timeout
Build User Info Claims

When a service extension has metadata values to edit, the pencil icon is shown to open 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

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 Strata’s public Service Extensions 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.

2024-02-21: Attribute provider SE bug fix