Identity integration overview
This page answers one question: when a user's identity comes from a third party (Google, Apple, WeChat, carrier number verification, and so on), which part of Wicket should you use?
Wicket offers two independent capabilities here. They solve different problems, have different dependencies, and are integrated differently:
| (a) External login on the authorization server | (b) Stateless token verification packages | |
|---|---|---|
| Examples | auth/google, auth/facebook, auth/jwt, dynamicscheme | oidcverify, wechatverify, phoneverify |
| Where it runs | In the Wicket middleware pipeline, as the handler of an authentication scheme | Plain Go packages that your application code calls directly |
| Interaction | Browser redirects, callback paths, cookies | A single function call: credential string in, identity or error out |
| Dependencies | di.Root, ServerConfig, a cookie handler provided by the host | No store and no DI container; you can import them on their own |
| Where the result goes | Signed into a Wicket session; the authorization endpoint then issues Wicket's own tokens | Handed to your application code, which decides what to do: look up the database, create an account, issue its own session |
(a) External login when acting as an authorization server
When Wicket runs as an OpenID Connect / OAuth 2.0 authorization server, /connect/authorize needs a "signed-in user". That user can come from your own login page or from an external identity provider:
- Google / Facebook: a standard OAuth 2.0 authorization code round trip. Wicket ships two handlers that build the redirect URL, exchange the code for tokens on the callback path (
/signin-google,/signin-facebook), fetch user info, and map it to claims. See External login. - JWT Bearer: not a login flow; it lets the host's API accept JWT access tokens issued elsewhere. See JWT Bearer authentication.
- Dynamic authentication schemes: add and remove authentication scheme records at runtime. In v0.1.4 this subsystem provides only the storage and resolution layer, and it can't be enabled through the container. See the status notes in Dynamic authentication schemes.
External login requires the host to supply a cookie handler
v0.1.4 has no usable built-in cookie authentication handler: for the default scheme wicket and the external scheme wicket.external, the container registers an "unsupported" placeholder handler. After a successful external login callback, the user must be signed into some cookie scheme, and the host must provide that implementation through ServerConfig.SetAuthenticationHandlerProvider. See External login.
(b) Stateless token verification packages
These three packages target the scenario where "the mobile app or frontend has already obtained a credential from the vendor, and the backend only needs to confirm it's genuine and extract the identity". They don't take part in the authorization code flow: no handlers, no cookies, no redirects, and they don't read or write any store:
oidcverify: verifies ID tokens issued by Apple, Google, or any standard OIDC provider locally, using JWKS public keys (RS256 only).wechatverify: sends the authorization code obtained from WeChat mobile app login to the WeChat server and exchanges it for a unionid / openid.phoneverify: sends the token obtained from the Alibaba Cloud number verification (one-tap login) SDK to the Alibaba Cloud server and exchanges it for a phone number.
The first is local signature validation; the other two are server-side exchanges. They differ a lot in outbound network access, latency, secret custody, and failure semantics, so read Local signature validation vs. server-side exchange before choosing.
The container registers an empty configuration pointer for each of the three packages (*oidcverify.ProviderConfig, *wechatverify.Config, *phoneverify.PhoneAuthConfig), but doesn't register the verifiers themselves—constructing one from an empty configuration always fails. The simplest approach is to bypass the container entirely and call each package's NewVerifier directly in your own initialization code.
Which one should I use?
| What you have / what you want | Use |
|---|---|
| Browser users "sign in with Google" to your authorization server, and Wicket then issues tokens to downstream applications | auth/google (External login) |
| Same as above, but the identity source is Facebook | auth/facebook (External login) |
| Your HTTP API must accept JWT access tokens issued by another issuer (possibly Wicket itself) | auth/jwt (JWT Bearer authentication) |
The app completed "Sign in with Apple" and sends the identityToken to the backend | oidcverify.AppleConfig (oidcverify) |
| An Android / iOS app gets an ID token from the Google Sign-In SDK and sends it to the backend | oidcverify.GoogleConfig (oidcverify) |
| An ID token issued by any standard OIDC provider (RS256 + JWKS) | oidcverify.ProviderConfig (oidcverify) |
The app completed WeChat login and got an authorization code | wechatverify (wechatverify) |
| The app completed carrier one-tap login and got a number verification token | phoneverify (phoneverify) |
| You want an admin console to add and remove login methods at runtime | No usable end-to-end solution yet; see Dynamic authentication schemes |
The two capabilities can be combined
A common combination: the app uses oidcverify / wechatverify / phoneverify to confirm the identity on the backend, and your code maps that identity to a local user; later, if you need to issue standard tokens to third-party applications, you go through a Wicket authorization flow (for example CIBA or authorization code). The verification packages only "confirm identity"; they don't "issue tokens".