oauth2-mock-server is a JavaScript/TypeScript library designed to provide a configurable OAuth2/OpenID Connect server for automated testing and development purposes. It allows developers to simulate an OAuth2 provider to issue verifiable access tokens without needing a full-fledged identity provider, making it ideal for unit and integration tests. The library supports various OAuth2 grant types, including Client Credentials, Resource Owner Password Credentials, Authorization Code (with PKCE), and Refresh Token grants. It also supports multiple JWK formats for signing tokens (RSA, EC, EdDSA). The current stable version is 8.2.2, with recent releases indicating an active maintenance and development cadence focused on dependency updates, minor feature additions, and bug fixes. A key differentiator is its programmatic control via event emitters for customizing server behavior, allowing for specific test scenarios, such as modifying token expiration or adding custom claims. It is explicitly not intended for production use due to a lack of full feature parity and security hardening.
npm install oauth2-mock-serverVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize, configure, and operate the `oauth2-mock-server`. It shows how to generate cryptographic keys, start the server on a dynamic port, build JWTs programmatically, and apply customization hooks to modify token claims before signing, simulating an OAuth2 flow for testing purposes.
Upgrade your Node.js environment to a supported version (20.19+, 22.12+, or 24+).
Ensure your project is configured for ES modules (e.g., `'type': 'module'` in `package.json` and using `import` statements), or confirm your Node.js version is within the range that supports the CJS fallback.
Do not deploy `oauth2-mock-server` in production environments. Use a robust, production-ready OAuth2/OIDC provider instead.
Call `await server.issuer.keys.generate('RS256')` (or another supported algorithm) or `await server.issuer.keys.add(yourJwk)` after initializing `OAuth2Server` and before starting the server or building tokens.Update your Node.js version to ^20.19 || ^22.12 || ^24, or configure your project to use ES Modules by adding `'type': 'module'` to your `package.json` and using `import` statements.
Choose an alternative port for `server.start(port, 'localhost')`, or set the port to `0` to have the operating system automatically assign a free port (e.g., `await server.start(0, 'localhost')`). Ensure previous instances of the server are properly stopped.
Before making requests to token endpoints or programmatically building tokens, ensure you call `await server.issuer.keys.generate('RS256')` or `await server.issuer.keys.add(yourJwk)` to populate the server's keystore.No dependency data recorded yet.