SAML

SAML service extensions let you customize how the Orchestrator builds and delivers SAML assertions to your service providers. Use these hooks to control authentication, enforce authorization, load user attributes, customize assertion claims, and configure IdP-initiated single sign-on.

Request Lifecycle

The SAML provider handles both service provider-initiated (SP-initiated) SSO and identity provider-initiated (IdP-initiated) SSO. Both flows use the same processing pipeline once the authentication request is established. For IdP-initiated login, the Orchestrator creates a synthetic AuthnRequest and processes it through the same pipeline as SP-initiated requests. The buildRelayStateSE hook is only called during IdP-initiated flows. The authorization step evaluates isAuthorizedSE if configured, along with any declarative authorization rules.

Hooks

`isAuthenticatedSE`

Determine whether the current user is already authenticated. Return true to skip the login flow, or false to send the user through authentication. Use this when you need custom logic to check authentication status — for example, validating an external session token or checking a cookie from another system. Signature:

func IsAuthenticated(api orchestrator.Orchestrator, rw http.ResponseWriter, req *http.Request) bool

Config location: apps[].authentication.isAuthenticatedSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`rw`	`http.ResponseWriter`	The HTTP response writer for the current request
`req`	`*http.Request`	The incoming HTTP request

Returns: bool — true if the user is authenticated, false otherwise.

isAuthenticatedSE cannot be used together with the idps field on SAML apps.

`authenticateSE`

Handle authentication when the user has not yet logged in. Use this to redirect to an external login page, validate credentials directly, or start a custom authentication flow. Signature:

func Authenticate(api orchestrator.Orchestrator, rw http.ResponseWriter, req *http.Request)

Config location: apps[].authentication.authenticateSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`rw`	`http.ResponseWriter`	The HTTP response writer — use to redirect or return an error response
`req`	`*http.Request`	The incoming HTTP request

authenticateSE cannot be used together with the idps field on SAML apps.

`isAuthorizedSE`

Decide whether an authenticated user is allowed to proceed. Return true to allow the request or false to deny it. Use this to call an external policy engine, enforce attribute-based access control (ABAC), or apply custom business rules beyond what declarative authorization rules support. Signature:

func IsAuthorized(api orchestrator.Orchestrator, rw http.ResponseWriter, req *http.Request) bool

Config location: apps[].authorization.isAuthorizedSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`rw`	`http.ResponseWriter`	The HTTP response writer for the current request
`req`	`*http.Request`	The incoming HTTP request

Returns: bool — true if the user is authorized, false otherwise.

`loadAttrsSE`

Enrich the user’s session with additional attributes before the SAML assertion is built. Use this to pull in user details from external sources — such as an LDAP directory, a database, or a REST API — transform attribute values, or merge attributes from multiple identity providers. Signature:

func LoadAttrs(api orchestrator.Orchestrator, rw http.ResponseWriter, req *http.Request) error

Config location: apps[].loadAttrsSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`rw`	`http.ResponseWriter`	The HTTP response writer for the current request
`req`	`*http.Request`	The incoming HTTP request

Returns: error — return nil on success, or an error to indicate attribute loading failed.

`buildClaimsSE`

Add custom attributes to SAML assertions sent to service providers. The attributes you return are included in the assertion’s attribute statement alongside any standard attributes. Use this to include additional user data, transform values, or vary the attributes based on which service provider is requesting them. Signature:

func BuildClaims(api orchestrator.Orchestrator, rw http.ResponseWriter, req *http.Request) (map[string]any, error)

Config location: apps[].buildClaimsSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`rw`	`http.ResponseWriter`	The HTTP response writer for the current request
`req`	`*http.Request`	The incoming HTTP request

Returns:

map[string]any — claims to include in the SAML assertion
error — return nil on success, or an error if claim building fails

`buildRelayStateSE`

Set the RelayState value for IdP-initiated login flows. RelayState tells the service provider where to send the user after login — for example, a specific landing page or deep link. Use this to dynamically determine the destination based on user attributes or request context. Signature:

func BuildRelayState(api orchestrator.Orchestrator, rw http.ResponseWriter, req *http.Request) string

Config location: apps[].idpInitiatedLogin.buildRelayStateSE Parameters:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`rw`	`http.ResponseWriter`	The HTTP response writer for the current request
`req`	`*http.Request`	The incoming HTTP request

Returns: string — the RelayState value to include in the SAML response.

Service Extensions Overview

Configuration, SDK reference, and best practices

SAML Applications

SAML application configuration and assertion settings

Console Administration

Orchestration

Request Lifecycle

Hooks

`isAuthenticatedSE`

`authenticateSE`

`isAuthorizedSE`

`loadAttrsSE`

`buildClaimsSE`

`buildRelayStateSE`

Service Extensions Overview

SAML Applications

​Request Lifecycle

​Hooks

​isAuthenticatedSE

​authenticateSE

​isAuthorizedSE

​loadAttrsSE

​buildClaimsSE

​buildRelayStateSE

​Related Pages

Service Extensions Overview

SAML Applications

Request Lifecycle

Hooks

`isAuthenticatedSE`

`authenticateSE`

`isAuthorizedSE`

`loadAttrsSE`

`buildClaimsSE`

`buildRelayStateSE`

Related Pages