Skip to main content
OIDC service extensions let you customize how the Orchestrator issues and manages OpenID Connect tokens. Use these hooks to control authentication, enforce authorization, load user attributes from external sources, and tailor the claims included in ID tokens, access tokens, and UserInfo responses.

​
Request Lifecycle

The OIDC provider exposes multiple endpoints, each with its own hook points. The diagrams below show where service extension hooks execute in each flow.

​
Authorization Endpoint

The authorization endpoint is where users log in and grant consent in their browser. This is the browser-based flow (front-channel) where most hooks execute.
The authorization step evaluates isAuthorizedSE if configured, along with any declarative authorization rules. Hybrid response types (e.g., code id_token) invoke multiple token-building paths from the response type branch.

​
Token Endpoint

The token endpoint exchanges credentials or authorization codes for tokens. Your claims-building hooks run during token creation for all grant types.
The client_credentials, token_exchange, and refresh_token grants only return access tokens — buildIDTokenClaimsSE is not called for these grant types.

​
UserInfo Endpoint

The UserInfo endpoint returns profile information about the authenticated user. Applications call this endpoint with an access token to retrieve user attributes.
buildUserInfoClaimsSE is configured at the OIDC provider level (oidcProvider.buildUserInfoClaimsSE), not on individual OIDC apps. When configured, it replaces the default scope-based claims building entirely.

​
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:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
rwhttp.ResponseWriterThe HTTP response writer for the current request
req*http.RequestThe incoming HTTP request
Returns: bool — true if the user is authenticated, false otherwise.

​
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:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
rwhttp.ResponseWriterThe HTTP response writer — use to redirect or return an error response
req*http.RequestThe incoming HTTP request

​
authenticateSE (backchannel)

Handle direct credential-based authentication, such as the Resource Owner Password Credentials (ROPC) grant. Unlike the browser-based authenticateSE, this variant processes credentials server-to-server (backchannel) without user interaction and returns an error if authentication fails. Signature: 
func AuthenticateBackchannel(api orchestrator.Orchestrator, req *http.Request) error
Config location: apps[].authentication.backchannel.authenticateSE Parameters:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
req*http.RequestThe incoming HTTP request containing credentials
Returns: error — return nil on success, or an error if authentication fails.

​
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:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
rwhttp.ResponseWriterThe HTTP response writer for the current request
req*http.RequestThe incoming HTTP request
Returns: bool — true if the user is authorized, false otherwise.

​
loadAttrsSE

Enrich the user’s session with additional attributes before tokens are issued. 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:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
rwhttp.ResponseWriterThe HTTP response writer for the current request
req*http.RequestThe incoming HTTP request
Returns: error — return nil on success, or an error to indicate attribute loading failed.

​
buildIDTokenClaimsSE

Add custom claims to ID tokens issued by the OIDC provider. The claims you return are merged into the token alongside the standard claims. Use this to include user attributes from external sources, add computed values, or conditionally include claims based on the requested scopes. Signature: 
func BuildIDTokenClaims(api orchestrator.Orchestrator, req *http.Request) (map[string]interface{}, error)
Config location: apps[].buildIDTokenClaimsSE Parameters:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
req*http.RequestThe incoming HTTP request (token endpoint request)
Returns:
  • map[string]interface{} — claims to include in the ID token
  • error — return nil on success, or an error if claim building fails

​
buildAccessTokenClaimsSE

Add custom claims to access tokens issued by the OIDC provider. The claims you return are merged into the token alongside the standard claims. Use this to include roles, group memberships, entitlements, or application-specific data. Signature: 
func BuildAccessTokenClaims(api orchestrator.Orchestrator, req *http.Request) (map[string]interface{}, error)
Config location: apps[].buildAccessTokenClaimsSE Parameters:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
req*http.RequestThe incoming HTTP request (token endpoint request)
Returns:
  • map[string]interface{} — claims to include in the access token
  • error — return nil on success, or an error if claim building fails

​
buildUserInfoClaimsSE

Control what user profile information the UserInfo endpoint returns. The attributes you return become the full response body, replacing the default scope-based claims. Use this to limit which attributes are exposed, add computed values, or pull in attributes from external sources. Signature: 
func BuildUserInfoClaims(api orchestrator.Orchestrator, req *http.Request) (map[string]any, error)
Config location: oidcProvider.buildUserInfoClaimsSE Parameters:
ParameterTypeDescription
apiorchestrator.OrchestratorAccess to sessions, caches, secrets, logging, and other Orchestrator services
req*http.RequestThe incoming UserInfo endpoint request
Returns:
  • map[string]any — claims to include in the UserInfo response
  • error — return nil on success, or an error if claim building fails
This hook is configured at the OIDC provider level (oidcProvider), not on individual OIDC apps.

Service Extensions Overview

Configuration, SDK reference, and best practices

OIDC Applications

OIDC application configuration and token settings