Mockin is a mock of the Hellō of the OpenID Connect Login Service and implements the authorization, token, introspection, and userinfo endpoints.
-
Development - speeds up development as you won't be redirecting through the Hellō production server. Start the login flow by clicking on the
[ ō Continue with Hellō ]button. Your browser will redirect to Mockin and then back to your app which will then complete the login flow. -
Testing - simplifies creating end to end tests, and with the
/mockAPIs, you can simulate expired and invalid responses allowing you to ensure your app properly handles all exceptions, improving your security posture.
Mockin is available as both an npm module and a docker image:
npx @hellocoop/mockin@latest
docker run -d -p 3333:3333 hellocoop/mockin:latest
Mockin defaults to http://127.0.0.1:3333 as the Issuer. Override by setting the ISSUER environment variable.
The mock API can change the returned claims, simulate errors, and invalid ID Tokens.
Mockin also acts as a mock Person Server for draft-hardt-oauth-aauth-protocol — useful for testing agent clients without spinning up a real PS. Endpoints include /aauth/bootstrap, /aauth/token/person (person_token_endpoint), /aauth/token/auth (auth_token_endpoint), /aauth/permission, /aauth/audit, /aauth/interaction, plus R3 (Rich Resource Requests) support. Agents should read the endpoint URLs from /.well-known/aauth-person.json rather than hard-coding paths. Auto-approves all consent steps in default mode. See the docs for details.
The mock API at PUT /mock/aauth switches the simulated behaviours:
| Key | Effect |
|---|---|
requirement |
interaction | approval | clarification — defers /aauth/token/auth with a 202 |
person_requirement |
interaction | approval — defers /aauth/token/person with a 202 |
auto_approve |
false makes a deferred interaction wait for GET /aauth/consent?code=… instead of resolving on the first poll |
error / error_endpoint |
inject a token endpoint error code, optionally scoped to token, person, bootstrap or permission |
token_lifetime, claims, r3_grants, tenant |
shape the issued tokens (r3_grants takes { granted, per_call }) |
require_body_signing |
false accepts a body signature that does not cover content-digest and content-type |
The auth token request (POST /aauth/token/auth) follows AAuth -11: resource_token and presented_token are REQUIRED. presented_token is the token the agent presented to the resource — the person token from /aauth/token/person, or on a step-up the auth token — and the resource token's presented_jti must name it. Mockin verifies the presented token under its own key (aud = the resource, cnf.jwk = the resource token's agent_jkt) and rejects any ps / sub / mission_s256 / tenant mismatch with invalid_resource_token; a bad or missing presented token is invalid_request, invalid_presented_token or expired_presented_token. The auth token never outlives the presented token.
Expiry is judged against mockin's clock with no tolerance (AAuth -11 §Expiry and the Refresh Margin). A signature created, an agent token iat, or a presented token iat more than 60 seconds ahead of mockin's clock is clock_skew — a 401 with Signature-Error: error=clock_skew for the signature or the agent token, a 400 problem for a presented token — so an agent knows to wait the difference out rather than refresh.
AAuth errors are RFC 9457 problem details — Content-Type: application/problem+json with the AAuth error code in error and the explanation in detail. The OIDC endpoints keep the OAuth 2.0 {error, error_description} shape they are specified to use.
Mockin also mirrors Hellō's invite flow — useful for testing how your app handles the events_uri SET (Security Event Token) JWT and the initiate_login_uri redirect for newly invited users. Endpoints include POST /invite, GET /invitation/:id, PUT /invitation/:id (accept), DELETE /invitation/:id (decline), DELETE /invite/:id (retract), and POST /invitation/:id/report (abuse). SET JWT is RS256-signed and delivered to events_uri on accept. See the docs for details.
For detailed information on installation, usage, and examples, visit the documentation.