What is Wicket
Wicket (module path github.com/gonewx/wicket) is an OpenID Connect / OAuth 2.0 authorization server library. It is not a standalone authentication service; it is a set of http.Handler middleware. You mount it in your own Go service, and that service then exposes standard protocol endpoints such as /connect/token, /connect/authorize, and /.well-known/openid-configuration.
go
// The host app's handler chain: wicket handles the protocol endpoints and passes every other request to app unchanged
handler := hosting.ScopeMiddleware(root)(srv.UseWicket()(app))
http.ListenAndServe(":5000", handler)For a complete, runnable setup, see Quick start.
Positioning: embedded middleware
Wicket runs inside your process and shares the same HTTP listener and the same deployment pipeline as your application code:
- Wicket owns the protocol: request parsing and validation, client authentication, token issuance and validation, the discovery document, and JWKS publishing.
- The host owns users and pages: the user store, password checks, and the login, consent, and error pages are all implemented by your application. Wicket only redirects the browser to URLs you configure when user interaction is needed.
- The host injects the infrastructure: the database, signing keys, logging, and cleanup scheduling are all provided by the host. The main Wicket module depends on no database driver and starts no background goroutines.
What it does
| Capability | Details |
|---|---|
| Protocol endpoints | Authorize, authorize callback, token, discovery document, JWKS, UserInfo, introspection, end session (including its callback), check session iframe, CIBA backchannel authentication |
| Grant types | authorization_code (PKCE required by default), client_credentials, refresh_token, urn:openid:params:grant-type:ciba, urn:ietf:params:oauth:grant-type:device_code (token endpoint only; see below), password (rejected by default; requires an injected validator) |
| Token formats | JWT access tokens (typ is at+jwt), ID tokens, refresh tokens; the model and storage port for reference tokens are defined, but the v0.1.4 issuance path does not use them yet |
| External login | Built-in Google and Facebook authentication handlers; JWT Bearer authentication; dynamic authentication schemes at runtime |
| Stateless verification | Three standalone packages that need no storage: oidcverify (local validation of ID tokens issued by external OIDC providers), wechatverify (WeChat server-side exchange), and phoneverify (Alibaba Cloud number verification) |
| Storage | Three families of storage ports (storage / session / keymgmt) plus conformance suites; in-memory implementations for development only; the official PostgreSQL adapter github.com/gonewx/wicket-pg |
| Signing keys | The host supplies signing credentials manually, or uses the automatic rotation manager in the keymgmt package |
What it doesn't do
- No user management or login UI. There is no user table, registration, password recovery, or login page template. Those belong to the host application.
- No built-in cookie authentication handler for interactive login. After a user logs in, the host writes an authentication cookie (scheme name
wicket); the host must provide its handler throughServerConfig.SetAuthenticationHandlerProvider. See Core concepts. - The following endpoints are not implemented (v0.1.4): token revocation
/connect/revocation, device authorization/connect/deviceauthorization, and the mTLS endpoints. They exist only as path constants with no registered handler, so requests fall through to the host handler. Note that with the default configuration the discovery document still advertisesrevocation_endpointanddevice_authorization_endpoint; see the endpoint switches section of Configuration. - No CORS response headers or reverse-proxy header handling. See CORS and the Production checklist.
- No background tasks of its own. The host drives cleanup of expired data on its own schedule.
When to use it
A good fit when:
- You already have a Go backend and want that backend itself to issue OAuth 2.0 / OIDC tokens to mobile apps, single-page apps, third-party clients, or internal services, instead of operating a separate authentication service.
- You have machine-to-machine calls (
client_credentials) that need standard access tokens and an introspection endpoint. - You need to exchange external credentials such as Apple, Google, WeChat, or a phone number for your own local identity. For this you can use only the stateless verification packages, without setting up the authorization server at all.
Not a good fit when:
- You need an out-of-the-box admin console, user self-service portal, or multi-tenant console.
- You need mature support for other protocols such as SAML or WS-Federation.
- Your bar for "production ready" is higher than an early v0.1.x release can promise (see below).
Compared with a standalone authentication service
| Aspect | Embedded Wicket | Standalone authentication service |
|---|---|---|
| Deployment and operations | Ships with the host process; no extra service | Separate service, database, and upgrade cadence |
| Access to user data | Calls the host's user store and business logic directly | Integrates through APIs, sync, or federation |
| Login page customization | Implemented entirely by the host, no limits | Constrained by the product's theming/template mechanism |
| Out-of-the-box features | Protocol core only; everything around it is yours to build | Usually ships with an admin UI, user management, and auditing |
| Fault isolation | Same process as the host; a host failure is an authentication failure | The authentication service scales independently and has its own failure domain |
| Security responsibility | Keys, storage, HTTPS, and logging are the host's responsibility | Mostly carried by the service provider |
In short, Wicket trades "less operational surface" for "more is in your hands". If your team is willing to own the setup and operations, it keeps authentication as close to your application code as possible.
Current status
- The latest version is v0.1.4, an early release. During v0.x the API may change incompatibly, so pin an exact version in
go.mod. - Requires the Go 1.27 toolchain.
- The Go package name of the root package is
gois(different from the directory name). The examples always import it with an alias:wicket "github.com/gonewx/wicket". - Some capabilities still have known gaps, and this documentation flags them on the relevant pages, for example:
- Automatic key management cannot be turned on by changing an option; the host has to build the manager itself (see Signing keys);
- Setting a client to reference tokens still issues JWTs (see Core concepts);
- The container's internal logger is fixed, and
ServerConfig.SetLoggerdoes not affect services already constructed (see Embedding in a host application); - Refresh token expiration and rotation policies are not implemented yet (see Refresh token);
- The built-in default data protection implementation is not suitable for production (see the Production checklist);
- Integration testing of WeChat and number verification against real credentials has not been done yet.