OIDC

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:

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.

`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` (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:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`req`	`*http.Request`	The 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:

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 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:

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.

`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:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`req`	`*http.Request`	The 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:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`req`	`*http.Request`	The 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:

Parameter	Type	Description
`api`	`orchestrator.Orchestrator`	Access to sessions, caches, secrets, logging, and other Orchestrator services
`req`	`*http.Request`	The 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

Console Administration

Orchestration

Request Lifecycle

Authorization Endpoint

Token Endpoint

UserInfo Endpoint

Hooks

`isAuthenticatedSE`

`authenticateSE`

`authenticateSE` (backchannel)

`isAuthorizedSE`

`loadAttrsSE`

`buildIDTokenClaimsSE`

`buildAccessTokenClaimsSE`

`buildUserInfoClaimsSE`

Service Extensions Overview

OIDC Applications

​Request Lifecycle

​Authorization Endpoint

​Token Endpoint

​UserInfo Endpoint

​Hooks

​isAuthenticatedSE

​authenticateSE

​authenticateSE (backchannel)

​isAuthorizedSE

​loadAttrsSE

​buildIDTokenClaimsSE

​buildAccessTokenClaimsSE

​buildUserInfoClaimsSE

​Related Pages

Service Extensions Overview

OIDC Applications

Request Lifecycle

Authorization Endpoint

Token Endpoint

UserInfo Endpoint

Hooks

`isAuthenticatedSE`

`authenticateSE`

`authenticateSE` (backchannel)

`isAuthorizedSE`

`loadAttrsSE`

`buildIDTokenClaimsSE`

`buildAccessTokenClaimsSE`

`buildUserInfoClaimsSE`

Related Pages