SAML

Overview

The Maverics Orchestrator can be configured to act as an SAML Provider, exposing standard endpoints for token issuance and user authentication. This allows modern applications to delegate authentication to Maverics, which in turn orchestrates identity across one or more upstream IDPs. Applications authenticate using standard SAML protocols, while Maverics handles policy enforcement, claim generation, and IDP abstraction.

This guide is structured to provide both overview and detailed instructions, making it suitable for IT professionals and administrators who are tasked with setting up and managing digital identities. Whether you are new to SAML applications or looking to enhance your existing setup with Maverics, this tutorial is your gateway to a seamless integration process.

Prerequisites

Completed the Maverics Storage Configuration Guide

Define services to include in your Identity Fabric

You can choose identity or attribute providers to include in your Identity Fabric. Leveraging services from cloud based IDPs such as Microsoft Entra ID, Okta, Auth0, and Ping, open source providers such as Keycloak or WS02, and on prem services like LDAP, ensures that your application has what it needs for a secure authentication and authorization user flow. For providers not on the list, Maverics supports generic SAML and OIDC connections.

From your IDP, you will need to register a new application. From Maverics, you will create a new identity fabric configuration. You can then use it in a user flow for authentication.

If you need to use another identity service like an LDAP directory, you can string them together with a username mapping, allowing you to use extended attributes for claims or authorization rules.

You can also use these providers in Service Extensions when building custom Authentication flows or dynamically loading or transforming attributes.

The following steps use the Strata provided Keycloak IDP:

Go to Identity Fabric
On the right, scroll and select Keycloak (OIDC)
Click to enlarge

For the SAML configuration, enter the following:

Name	Description	Field
Name	A unique identifier for the connector configuration. This cannot be changed once it is set.	mavericsOIDC
OIDC Well Known URL	The URL that returns OpenID Connect metadata about the OIDC authorization server.	https://keycloak.strata-eval.io/realms/maverics/.well-known/openid-configuration
OAuth Client ID	The OAuth client ID registered with the OIDC provider.	mavericsclient
OAuth Client Secret	The OAuth client secret associated with the client ID.	mavericsclientsecret
Redirect URL(s)	A list of allowed redirect URIs for the login flow.	https://localhost:8443/oidc
Logout Callback URL(s)	A list of allowed redirect URIs for the logout flow.	https://localhost:8443/oidc/logout
Allowed Audiences	Optional configuration that represents a list of audiences that are allowed to consume access tokens. When a client makes a request to the authorization endpoint, an optional resource parameter can be included that indicates the target audience of the token. The value provided in the resource parameter must be on the list of allowed audiences. This configuration is used when resource servers, such as APIs, authorize via the access token. For more information, please reference RFC 9068.	https://example.com client api://resource-server
Scopes	A space-delimited string specifying the scopes to request during authentication.	openid profile email
Proof Key for Code Exchange (PKCE)	Enable or disable Proof Key for Code Exchange (PKCE).	Enabled

Deploy a SAML provider

From the Deployments Manager go the Orchestrator Settings section to define the endpoints, user info service extension and JWKs signing options for your SAML provider.

SAML Provider Options

Field / Endpoint	Description
Issuer	A unique identifier for the SAML Identity Provider (IdP), typically formatted as a URL but used purely as a string identifier—not as a resolvable web address. The Issuer appears in the Issuer element of SAML assertions and metadata, and must match the expected value configured in the relying service provider to establish trust. Enter the issuer URL, and click Generate to automatically fill out the standard endpoints. You can override with custom values at any point.
Metadata Optional	The endpoint where the SAML Provider publishes its metadata, including certificates, supported bindings, and endpoints. SAML applications or Service Providers (SPs) Service providers use this URL to retrieve configuration details and establish trust. Note: if unset, connecting SAML apps will need ot be manually configured.
Single Sign-On	The location of where SAML apps will send SAML authentication requests.
Single Logout	The single logout URL for the SAML provider.
Signing Option	The location of where SAML apps will send SAML logout requests. You can select Response and Assertion, Response Only (to disable Signed Assertion), or Assertion Only (to disable Signed Response).
Signature	Defines the x509 certificate and the RSA256 private key to be used for validation and signing of SAML responses and assertions. Note: The signature properties can be overridden on a per-app basis. Click Edit, then click the plus (+) sign to add a key. The options to generate a key, upload a key, or use a secret store will appear.
Redis Cache Optional	Specifies an external Redis cache to be used for token/session storage. If unset, the default in-memory cache is used.

Configure a SAML application

From the Applications page, create a SAML app by selecting SAML-based under Application Types.

Field Name	Description	Example
Name	A friendly name for your OIDC application.	ExampleApp
App Icon	Upload an image for your application to display in Maverics.	Maverics supports JPEG, PNG, or SVG, up to 2MB maximum.
Audience	Denotes who the client is. It should match the Issuer field provided by the service provider.
Consumer Service URL	The URL where SAML responses will be sent.
Duration	The duration in seconds for which this server's responses are valid.
NameID Format Optional	Define the NameID Format that will be used in the SAML assertion.	When not defined, a value of urn:oasis:names:tc:SAML:1.0:nameid-format:unspecified will be used.
Unauthorized Page Optional	The URL the Orchestrator will redirect the user if they are not authorized to access the requested resource.
Certificate File	Upload a certificate file to verify the signatures of incoming requests. Supported formats: PEM, KEY.	<MY_KEY_PEM>
IDP Initiated Login: Login URL	The endpoint that the user will visit from their browser to initiate the IDP login flow.	https://maverics.sonarsystems.com/login-sonar
IDP Initiated Login: Relay State URL	The endpoint that gets passed to the service provider and is intended to be the landing page for the user after the authentication flow is complete	https://app.sonarsystems.com/index.html

Click Create to save the configuration.

Create a service extension (optional)

Service Extensions are short Golang programs that hook into extension points within an orchestrator to modify or extend features. They give administrators the ability to customize the behavior of the orchestrator to suit the particular needs of their integration. This step is optional, and you can view documentation on service extensions below. After creating a service extension, you can select it for use when creating your user flow.

Three service extensions are available for use with SAML app flows:

Authentication: isAuthenticatedSE and authenticateSE service extensions are available to determine if a user is already authenticated and to control the authentication behavior.
Custom Claims: buildClaimsSE can customize which attributes will be added to the SAML 2.0 AttributeStatement.
Relay State: buildRelayStateSE can optionally be used to build the RelayState parameter in an IDP-initiated login flow. This extension can be used when the relay state is dynamic and therefore cannot be defined with a static relayStateURL.

After creating these service extensions, you can select them from Authentication and Claims on the user flow page.

Configure a SAML user flow

Next, you’ll create a user flow selecting the SAML app you’ve created.

From the dashboard, click Create user flow. Alternatively, from the sidebar, click User Flows, and click New. Enter a name for the user flow and select an application to use. Click Create.

To edit an existing user flow, click User Flows from the sidebar and click the name of the user flow you want to edit.

The name of the user flow appears at the top of the screen and can be edited. The application appears under the name. You can click the application to edit the app configuration, but you cannot change the application tied to the user flow. However, you can add other configured SAML apps to the user flow.

Field	Description
Name	Name of the user flow
Application	The applications associated with the user flow. Tip: User Flows as Policy Templates SAML can be used for multiple applications and an application can only be associated with one user flow. This is especially useful when you want a group of apps to share the same authentication provider, authorization policy and user experience.
Authentication	You can select a configured identity provider, a continuity strategy, or Authentication service extension.
Access Token Service Extension	Use a Custom Claims service extension that can customize how claims in the access token are built. This service extension should be used when non-standard claims need to be added to the access token.
ID Token Service Extension	Use a Custom Claims service extension to customize how claims in the ID token are built. This service extension should be used when non-standard claims need to be added to the ID token.
Attribute Provider	Define attribute provider to use as a source for claims or within authorization rules. Options Select an attribute provider, choose the identity provider you used in the Authentication setup, and select a claim that will be on the session that you will use to look up the user in the attribute provider. Select a Load Attributes service extension to to customize how the loading of attributes is done. This extension is often used to load attributes from proprietary data sources such as enterprise APIs.
Authorization	Define access control rules for the applications Options Allow all access - the user is allowed access upon a successful token exchange Use Rules - define conditions for allowing access. See more about Using Rules Authorization service extension - if you have defined an authorization service extension you can select it here.
Claims	Map attributes on a user’s session to claims on the ID token. The claims added to the ID token are determined by the value of the scope parameter sent in the authorization request. The scopes supported are email, profile, address and phone.

Using Rules

Rules rules define a list of access control conditions. All rules must evaluate to true in order user to get access to a given app.

Under Authorization select use Rules to define access.
Choose All (and) or Any (or) to set the operator for the matching conditions.
Choose the Provider to source the attribute. You can choose an identity provider, attribute provider, service extension, or HTTP Request header.
Choose the attribute you will use to evaluate access.
Set the condition (contains, does not contain, equals, or does not equal).
Choose the value of the attribute.
Click Add Rule
Optionally you can add more conditions and more rules.

Deploying the application

Deployments Overview

Deployments in Maverics are how you bundle and publish your orchestration configurations — including applications, user flows, identity services, and policy logic — to your orchestrators for enforcement. Before deploying, review the Deployment Overview to understand how environments, services, and storage work together in Maverics.

Prerequisite: Storage Configuration connected to a Orchestrator service

To successfully deploy and test your application’s user flow, you must first configure a storage storage provider and connect it to installed orchestrator services.

Recommended: Use Maverics Storage for the fastest and simplest evaluation experience.
Other storage options (for example, AWS S3, Google Cloud Storage, Github repo, and Microsoft Azure Blob storage) are supported. See the full Storage Configuration Guides for setup instructions.

Add your application to a deployment

Once your storage is configured, you can deploy your application using the Deployment Manager:

Navigate to Deployments in the Maverics UI.
Create a new deployment or select an existing one.
Add your application(s) to the deployment:
Click Publish Preview to review and validate the deployment configuration.
After confirming the preview looks correct, click Publish to push the configuration to your orchestrators.