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
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 |
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)
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
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 |
bool — true if the user is authorized, false otherwise.
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
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 |
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)
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 |
map[string]any — claims to include in the SAML assertionerror — 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
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 |
string — the RelayState value to include in the SAML response.
Related Pages
