Configuration

Wicket's protocol behavior is controlled by a single *options.WicketOptions object (package github.com/gonewx/wicket/config/options). This page lists the commonly used fields with their actual defaults from the v0.1.4 source, and flags which fields are currently not read.

How to change options

WicketOptions is created as a singleton in di.NewRoot(). The host retrieves that same pointer from the container and changes its fields directly:

// Illustrative: app is the host's own http.Handler
root, err := di.NewRoot()
if err != nil {
	log.Fatal(err)
}
defer root.Close()

opts := godi.GetRequired[*options.WicketOptions](root)
opts.IssuerUri = "https://id.example.com"
opts.UserInteraction.LoginUrl = "/account/login"
opts.UserInteraction.LoginReturnUrlParameter = "returnUrl"
cacheSeconds := 3600
opts.Discovery.ResponseCacheInterval = &cacheSeconds

cfg := root.ServerConfig()
// ... injection ...
cfg.Freeze()

srv, _ := server.DefaultServer(root)
handler := hosting.ScopeMiddleware(root)(srv.UseWicket()(app))

Rules:

• Make all changes after NewRoot() and before UseWicket(). UseWicket() validates some fields immediately (see Embedding in a host application).
• Don't change options while the service is running. The options object has no concurrency protection, and fields are read during request handling.
• Most fields are read at request time, so changes take effect right away. The exception is fields that are copied into singletons inside NewRoot(); changing them afterward has no effect:

Options read at NewRoot time

• KeyManagement.*: the key manager is constructed in NewRoot() and copies its configuration. Tested on v0.1.4: setting opts.KeyManagement.Enabled = true afterward leaves the manager disabled. For a working way to turn on automatic key management, see Signing keys.
• DynamicProviders.Enabled / StorageProvider / CacheTTL / Clock: the dynamic scheme resolver is also constructed in NewRoot().

Top-level fields

Field	Default	Notes
IssuerUri	""	The issuer. When empty, it is derived from the request's Host and whether TLS is used; must be set in production
AccessTokenJwtType	"at+jwt"	The typ in the JWT access token header
EmitScopesAsSpaceDelimitedStringInJwt	false	When false, scope in the JWT is an array; when true, a space-delimited string
EmitIssuerIdentificationResponseParameter	true	Whether authorization responses carry the iss parameter. Note that authorization_response_iss_parameter_supported in the discovery document is always true regardless of this switch
EmitStateHash	false	Adds s_hash to the ID token
StrictJarValidation	false	Strict typ validation of JWT request objects (JAR)
LowerCaseIssuerUri, EmitStaticAudienceClaim, ValidateTenantOnAuthorization	—	Not read in v0.1.4; setting them has no effect

Endpoints: endpoint switches

The switches under opts.Endpoints all default to true (except EnableJwtRequestUri, which defaults to false). In v0.1.4, however, they don't all behave the same way. They fall into these groups:

The handler checks the switch and returns 404 when it is off:

Field	Affects
EnableDiscoveryEndpoint	Both the discovery document and JWKS endpoints
EnableUserInfoEndpoint	UserInfo
EnableEndSessionEndpoint	End session and its callback
EnableCheckSessionEndpoint	Check session iframe

Only affects whether the discovery document advertises the endpoint; the endpoint itself keeps working:

EnableAuthorizeEndpoint, EnableTokenEndpoint, EnableIntrospectionEndpoint, EnableBackchannelAuthenticationEndpoint. For example, in testing, after setting EnableTokenEndpoint to false, the discovery document no longer contains token_endpoint, but /connect/token still handles requests normally. To actually block an endpoint, intercept its path with host middleware outside Wicket.

The endpoint is not implemented; only the discovery document is affected:

EnableTokenRevocationEndpoint, EnableDeviceAuthorizationEndpoint. v0.1.4 registers no revocation or device authorization handlers, but these switches default to true, so the discovery document advertises revocation_endpoint and device_authorization_endpoint, and requests actually land in the host handler. If you don't plan to implement these two endpoints yourself, turn them off to keep clients from using them by mistake:

opts.Endpoints.EnableTokenRevocationEndpoint = false
opts.Endpoints.EnableDeviceAuthorizationEndpoint = false

EnableJwtRequestUri controls whether authorization requests may use request_uri to fetch a request object remotely.

Discovery: discovery document

Field	Default
ShowEndpoints, ShowKeySet, ShowIdentityScopes, ShowApiScopes, ShowClaims, ShowResponseTypes, ShowResponseModes, ShowGrantTypes, ShowExtensionGrantTypes, ShowTokenEndpointAuthenticationMethods	All true
ExpandRelativePathsInCustomEntries	true (values in CustomEntries starting with ~/ are expanded to absolute URLs)
ResponseCacheInterval	nil: no cache headers; when set to a non-negative integer N, discovery document and JWKS responses carry Cache-Control: max-age=N and Vary: Origin
CustomEntries	Empty map; add custom fields here

Note that when ShowKeySet = false, the JWKS endpoint also returns 404.

UserInteraction: interaction pages

The login, consent, and error pages are implemented by the host; Wicket only handles the redirects. LoginUrl and LoginReturnUrlParameter default to empty and must be set by the host. For the full table of defaults, see the "Login, consent, and error pages are implemented by the host" section of Embedding in a host application.

Authentication: authentication and session cookies

Field	Default	Notes
CookieAuthenticationScheme	""	The cookie scheme for interactive users; when empty, the default scheme from the authentication options is used
CookieLifetime	10h	Written into ExpireTimeSpan of the wicket cookie scheme options; Wicket itself doesn't consume it, the host-provided cookie handler reads it
CookieSlidingExpiration	false	Same as above, written into SlidingExpiration
CookieSameSiteMode	Zero value (unset)
CheckSessionCookieName	"wicket.session"	Must not be empty; validated by UseWicket()
CheckSessionCookieSameSiteMode	http.SameSiteNoneMode
RequireAuthenticatedUserForSignOutMessage	false
RequireCspFrameSrcForSignout	true
CoordinateClientLifetimesWithUserSession	false	Not read in v0.1.4

InputLengthRestrictions: input length limits

Request parameters that exceed a limit are rejected. Defaults: most fields are 100; Scope, Nonce, and AcrValues are 300; RedirectUri is 400; CspReport is 2000; IdTokenHint and LoginHintToken are 4000; Jwt is 51200; ResourceGapMaxLength is 512; the PKCE CodeChallenge* / CodeVerifier* length range is 43–128.

If your client IDs or secrets are long (for example, more than 100 characters), raise ClientId / ClientSecret accordingly.

Cors and Csp

• Cors: CorsPolicyName defaults to "wicket" (must not be empty), and CorsPaths defaults to five paths: discovery, JWKS, token, UserInfo, and revocation. No code in v0.1.4 emits Access-Control-* response headers. CorsPaths, PreflightCacheDuration, and the client's AllowedCorsOrigins produce no CORS behavior on their own; they can only serve as decision data for host middleware. If browsers call the token endpoint directly, the host must handle CORS itself; see CORS.
• Csp: Level defaults to CspLevelTwo, and AddDeprecatedHeader defaults to true. These control the CSP headers on the HTML responses Wicket emits itself (the form_post authorization response, the check session iframe, and the front-channel logout page).

Other sub-options

Option	Default and notes
Validation.InvalidRedirectUriPrefixes	javascript:, file:, data:, mailto:, ftp:, blob:, about:, ssh:, tel:, view-source:, ws:, wss: — these prefixes can't be used as custom-scheme redirect URIs
BackchannelAuthentication	AllowedDeliveryModes is ["poll"], DefaultRequestLifetime 300 seconds, DefaultPollingInterval 5 seconds, SlowDownIntervalIncrement 5 seconds, UserCodeParameterSupported is true. Its Enabled field is not read in v0.1.4
DeviceFlow	A value type that is not initialized: Interval is 0 and DefaultUserCodeType is empty. Set them explicitly when you use the device code grant (for example, Interval = 5)
ServerSideSessions	Enabled is false; SessionLifetime 14 days; CookieName "wicket.session"; CookieSecure true; CookieSameSite None
PersistentGrants.DataProtectData	true, but has no effect in v0.1.4: persisted grant data is not protected; see the Production checklist
MutualTls	Enabled is false; v0.1.4 registers no mTLS endpoints
KeyManagement	Enabled is false, AllowedAlgorithms is ["RS256"], DefaultAlgorithm is "RS256"; see Signing keys
DynamicProviders	Enabled is false; see Dynamic authentication schemes

Related reading

• Embedding in a host application
• Signing keys
• Discovery document
• Production checklist