Wicket is an OpenID Connect issuer that does one flow: Authorization Code with PKCE, for public clients. If you have used an OIDC provider before, the values below are all you need. Before you start, read what Wicket will never do.
Paste this into your coding agent:
Add Wicket sign-in to this app. Install the wicket CLI from
https://wicketauth.com/cli/ and run wicket setup with this app's name and
an http://127.0.0.1 callback URL. Show me the link it prints: I'll open it
and approve (the first time, I sign in with my email). Then follow
https://wicketauth.com/llms.txt to add sign-in, using the WICKET_ISSUER and
WICKET_CLIENT_ID it prints.
The agent does the rest. What it runs:
wicket setup:
wicket setup --name "My app" \
--redirect-uri http://127.0.0.1:3000/callbackclient_id live_...
issuer https://login.wicketauth.com
discovery https://login.wicketauth.com/.well-known/openid-configuration
# .env
WICKET_ISSUER=https://login.wicketauth.com
WICKET_CLIENT_ID=live_...
Sign-in then works on http://127.0.0.1. The app is a live
app from the start, so going to production is adding your real callback
(the list replaces the old one, so repeat the ones to keep):
wicket apps update live_... --redirect-uri http://127.0.0.1:3000/callback \
--redirect-uri https://app.example.com/callback/llms.txt is this guide written for
agents: the values, the flow, ID-token checks in Python, TypeScript, Go and
Rust, and the mistakes to avoid.
For an agent that doesn't install the CLI.
ISSUER=https://login.wicketauth.com
curl -s -X POST $ISSUER/cli/start -H 'Content-Type: application/json' \
-d '{"client_label": "my laptop"}'
# {"grant": "...", "user_code": "BCDF-GHJK", "verification_uri": "https://login.wicketauth.com/cli",
# "verification_uri_complete": "https://login.wicketauth.com/cli?code=BCDF-GHJK", "expires_in": 600, "interval": 5}
Nothing is mailed. Show the person verification_uri_complete
and the user_code: they open the link, sign in with their
email if that browser isn't signed in yet, check the page shows the same
code, and click Approve. Meanwhile, poll every interval
seconds:
curl -s -X POST $ISSUER/cli/poll -H 'Content-Type: application/json' \
-d '{"grant": "..."}'
# 400 {"error": "authorization_pending"} until they approve, then once:
# 200 {"credential": "wkt_live_...", "email": "you@example.com", "expires_after_idle_days": 90}
Other answers end the grant: access_denied (they clicked
Deny), expired_token (10 minutes passed, or the credential
was already handed out); slow_down means poll less often.
Keep the credential like a password. Then register the app:
curl -s -X POST $ISSUER/api/apps -H "Authorization: Bearer wkt_live_..." \
-H 'Content-Type: application/json' \
-d '{"name": "My app", "redirect_uris": ["http://127.0.0.1:3000/callback"]}'
# 201 {"client_id": "live_...", "name": "My app", "redirect_uris": [...]}
| Identifier | the person's email address |
|---|---|
| Sign-in | a one-time link, by email |
| Protocol | OpenID Connect shaped: Authorization Code with PKCE (S256), RS256 ID tokens, a published JWKS |
| Clients | public only, PKCE required. No client secrets exist. |
| Tokens | one ID token per sign-in, valid for 10 minutes |
With the CLI or curl, as above, or sign in to
the dashboard
(login.wicketauth.com/dashboard) with your email address and
create an app. The two are the same apps. Your client_id is
live_ and 20 characters.
An app is a name and a list of redirect URIs. Wicket compares the
redirect_uri of each request with that list exactly,
character for character: no prefixes, no wildcards. There is no client
secret.
| Setting | Value |
|---|---|
| Issuer | https://login.wicketauth.com |
| Discovery | https://login.wicketauth.com/.well-known/openid-configuration |
| Authorization endpoint | https://login.wicketauth.com/authorize |
| Token endpoint | https://login.wicketauth.com/token |
| JWKS | https://login.wicketauth.com/jwks.json |
| Client authentication | none (a public client) |
| Response type | code |
| PKCE | required, S256 only |
| Scopes | openid email |
| ID token signature | RS256 |
ID token type (header typ) | wicket-id+jwt |
The issuer is exactly https:// and the host: no trailing slash.
Pin it byte for byte.
Most OIDC libraries work with just these values: Wicket reads the token
request form-encoded, as they send it, and its ID token carries back the
nonce you sent. Auth.js needs two more settings,
below. And check the ID token's typ,
wicket-id+jwt: most libraries don't check it at all, so check
it yourself, as below. Two reject every Wicket ID token until told to
accept it: Spring Security (Java) and Rust's
openidconnect.
Auth.js needs two settings beyond the issuer. Wicket has no userinfo
endpoint, and Auth.js refuses a discovered server without one unless
token is set. It also sends the client_id in a
Basic header unless the client says none, and Wicket reads
it only from the body. Without both, every sign-in spends the mailed link
and ends on Auth.js's error=Configuration page.
// auth.ts
import NextAuth from "next-auth";
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [
{
id: "wicket",
name: "Wicket",
type: "oidc",
issuer: "https://login.wicketauth.com",
clientId: process.env.WICKET_CLIENT_ID,
token: "https://login.wicketauth.com/token", // required: no userinfo
client: { token_endpoint_auth_method: "none" }, // required: public client
checks: ["pkce", "state"],
},
],
});
Register https://<your host>/api/auth/callback/wicket
as the redirect URI. Auth.js reads the ID token straight from
/token and checks its claims itself;
session.user.email is the person's address.
A browser-only app needs no server.
A single-page app can run the whole flow in the browser, the code exchange
included: discovery, the JWKS and the token endpoint answer requests from
any origin. Wicket keeps no session, so a silent sign-in
(prompt=none) always comes back with
error=login_required: turn silent renew off (in oidc-client-ts,
automaticSilentRenew: false) and, when your session ends, send
the person through the form again.
Make a random PKCE verifier (43 to 128 characters of
A-Z a-z 0-9 - . _ ~) and a random state, and
keep both in the person's session, with a random nonce if
you send one. The challenge is the verifier's SHA-256,
base64url without padding. Then redirect the browser to:
https://login.wicketauth.com/authorize
?client_id=live_...
&redirect_uri=https://app.example.com/callback
&response_type=code
&scope=openid%20email
&code_challenge=<base64url(sha256(verifier))>
&code_challenge_method=S256
&state=<state>
&nonce=<nonce>
Wicket shows the form, the person enters their address, and Wicket mails them a link. The link works once, for 15 minutes.
The link opens a page with one Continue button, so a mail scanner that fetches the link doesn't use it up. Pressing Continue sends the browser to your redirect URI:
https://app.example.com/callback?code=...&state=...
Check that state is the one you stored. The code works once,
for 5 minutes.
A callback with no pending sign-in.
The link works only in the browser that started the sign-in (see
where the link opens). Opened on
another device, or in a mail app's own browser, it reaches your callback
where no pending sign-in matches its state. Most libraries
throw an error there; catch it and show a page instead:
Open the link on the device and in the browser where you asked to sign
in, or ask for a new link here.
, with a button that starts a new
sign-in. The link is used up by then, and the code can't be traded
without the verifier, so a new sign-in is the only way on from here.
POST https://login.wicketauth.com/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=<code>
&client_id=live_...
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&code_verifier=<verifier>
The same fields as a JSON object, with
Content-Type: application/json, work too.
The answer:
{ "access_token": "...", "id_token": "eyJ...", "token_type": "Bearer", "expires_in": 600 }
The ID token is what you sign the person in with. The
access_token is there because OAuth requires one: Wicket has
no API for it to call, and nothing accepts it.
Errors are OAuth's (RFC 6749 §5.2):
{"error": "<code>", "error_description": "<why>"},
400 with invalid_request (a parameter missing or
malformed, a verifier that isn't 43-128 allowed characters),
invalid_grant (the code unknown, used or expired, or a wrong
verifier, redirect_uri or client_id for it) or
unsupported_grant_type, and 401 with
invalid_client for an unknown client_id.
An authorization request without an S256 code_challenge
comes back to your redirect URI with
?error=invalid_request&error_description=...&state=...,
and one with prompt=none with
?error=login_required&....
An unknown client_id or unregistered
redirect_uri never redirects: Wicket shows an error page.
Check all of these, with any JWT library:
RS256, with the key in the issuer's JWKS whose kid matches the token's header;typ is wicket-id+jwt;iss is the issuer, exactly;aud is your client_id;exp hasn't passed;nonce is the one you sent, if you sent one.In Python, with PyJWT:
import jwt # PyJWT
ISSUER = "https://login.wicketauth.com"
CLIENT_ID = "live_..."
jwks = jwt.PyJWKClient(ISSUER + "/jwks.json")
def verify(id_token: str) -> dict:
if jwt.get_unverified_header(id_token).get("typ") != "wicket-id+jwt":
raise ValueError("not a Wicket ID token")
key = jwks.get_signing_key_from_jwt(id_token)
return jwt.decode(id_token, key.key, algorithms=["RS256"],
audience=CLIENT_ID, issuer=ISSUER)
user = verify(id_token)["sub"] # "alice@example.com"
Spring Security's oauth2Login() checks typ
itself and accepts only JWT. Without the bean below, every
sign-in fails after the code exchange with
[invalid_id_token] … typ … not allowed (6.x) or
the given typ value needs to be one of [JWT] (7.x). The bean
replaces Spring's ID token decoder with one that accepts
wicket-id+jwt and nothing else, and keeps Spring's other
checks. It works on 6.4 to 7.1:
import com.nimbusds.jose.JOSEObjectType;
import com.nimbusds.jose.proc.DefaultJOSEObjectTypeVerifier;
import org.springframework.context.annotation.Bean;
import org.springframework.security.oauth2.client.oidc.authentication.OidcIdTokenDecoderFactory;
import org.springframework.security.oauth2.client.oidc.authentication.OidcIdTokenValidator;
import org.springframework.security.oauth2.client.registration.ClientRegistration;
import org.springframework.security.oauth2.core.DelegatingOAuth2TokenValidator;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtDecoderFactory;
import org.springframework.security.oauth2.jwt.JwtTimestampValidator;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
@Bean
JwtDecoderFactory<ClientRegistration> wicketIdTokenDecoderFactory() {
Map<String, JwtDecoder> decoders = new ConcurrentHashMap<>(); // one per app, so the JWKS stays cached
return registration -> decoders.computeIfAbsent(registration.getRegistrationId(), id -> {
NimbusJwtDecoder decoder = NimbusJwtDecoder
.withJwkSetUri(registration.getProviderDetails().getJwkSetUri())
.jwtProcessorCustomizer(p -> p.setJWSTypeVerifier(
new DefaultJOSEObjectTypeVerifier<>(new JOSEObjectType("wicket-id+jwt"))))
.build();
decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
new JwtTimestampValidator(), new OidcIdTokenValidator(registration)));
decoder.setClaimSetConverter(OidcIdTokenDecoderFactory.createDefaultClaimTypeConverter());
return decoder;
});
}
With Spring Boot, register Wicket as a public client, so Spring sends PKCE:
spring.security.oauth2.client.provider.wicket.issuer-uri=https://login.wicketauth.com
spring.security.oauth2.client.registration.wicket.client-id=${WICKET_CLIENT_ID}
spring.security.oauth2.client.registration.wicket.client-authentication-method=none
spring.security.oauth2.client.registration.wicket.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.wicket.scope=openid,email
openidconnectThe openidconnect crate (4.x) accepts only typ
JWT or JOSE by default and rejects Wicket's with
unexpected or unsupported JWT type `wicket-id+jwt`. Allow
Wicket's instead:
use openidconnect::JsonWebTokenType;
let verifier = client.id_token_verifier().set_allowed_jose_types([
JsonWebTokenType::new("wicket-id+jwt".to_string()).normalize()?,
]);
let claims = id_token.claims(&verifier, &nonce)?;
The ID token is proof that the person controls the address, and it expires in 10 minutes. There are no refresh tokens. Start your app's own session from it, as long as you like, and when that session ends, send the person through Wicket again.
| Claim | Value |
|---|---|
sub | the email address, normalised: trimmed and lowercased. +tags and dots are kept. |
email | the same address |
email_verified | always true: the person opened the link |
iss | the issuer |
aud | your client_id |
iat, exp | issued at, and 10 minutes later, in Unix seconds |
nonce | the nonce your request sent; absent if it sent none |
The subject is the same in every app that uses Wicket, and a person who
changes address is a new subject. Key your users by sub
knowing both.
One app covers development and production. Wicket accepts
http://127.0.0.1, http://[::1] and
http://localhost redirect URIs, so the app you register while
building signs people in in production once you add your real callback.
Want staging? Register a second app, with your staging
callback, on the same issuer. It gets its own client_id, and
its tokens are for that client_id only, so neither app
accepts the other's.
kid you don't have. A new key is published
before it signs anything.state (a cookie, a server
session behind one, localStorage or
sessionStorage), another device or another browser, such as
the one inside a phone's mail app, can't see them. sessionStorage
is per tab, and a mailed link opens in a new tab, so keep them in a
cookie or localStorage. Handle the callback that finds none
as in a callback with no pending
sign-in.you+anything@example.com). Anyone else is refused before any
email is sent, with HTTP 402 and a page saying the app only lets its
developer sign in; a client that asks for JSON gets
{"code": "developer_only", "plan": "personal", "error": "…"}.
Upgrade to Starter or Pro in the
dashboard to let other people in.+tag and dots ignored, so
one inbox counts once.
Once the month is full, someone new is still sent a link, and is refused
when they continue from it, with HTTP 402; everyone already counted that
month keeps signing in. The sign-in form answers every address the same
way, so it never shows who uses your app. A client that asks for JSON
gets
{"code": "over_limit", "meter": "monthly_active_users", "limit": 100, "plan": "starter", "error": "…"}.
Your app's dashboard page shows the month's count.wicketauth.com and says only that a sign-in was asked for.
The sign-in page shows your app's name, on Wicket's own host, and the
host of the redirect URI the person returns to.The dashboard's operations are also a JSON API. The CLI uses it, and so can your code:
| Call | Body | Answer |
|---|---|---|
GET <issuer>/api/apps | {"apps": [...]}, yours | |
POST <issuer>/api/apps | {"name", "redirect_uris": [...]} | 201, the app |
GET <issuer>/api/apps/{client_id} | the app | |
PUT <issuer>/api/apps/{client_id} | {"name", "redirect_uris": [...]} | the app; replaces both |
DELETE <issuer>/api/apps/{client_id} | 204; its sign-ins stop at once | |
POST <issuer>/api/apps/{client_id}/checkout | {"plan": "starter"} or {"plan": "pro"} | {"url"}: Stripe Checkout for that plan |
DELETE <issuer>/api/credential | 204; revokes the credential that sent it |
An app is {"client_id", "name", "redirect_uris"}.
Every call sends Authorization: Bearer wkt_live_…: the
credential an approval in a signed-in browser
grants, from wicket setup or /cli/start
and /cli/poll. Nothing else is accepted, the dashboard's
sign-in included. Errors are {"error": "..."}: 401 for a
missing, revoked or expired credential, and 404 for an app that isn't
yours, the same as one that doesn't exist.
Registering an app, by POST /api/apps as anywhere else,
means you accept Wicket's terms.
The credential is your own key for managing your apps. It signs nobody in to anything, Wicket's dashboard included, and no app ever sees it. A person holds at most 10 at once, and one unused for 90 days expires. The dashboard's CLI credentials page lists and revokes them.