https://github.com/axa-group/oauth2-mock-server
A development and test oriented OAuth2 mock server
https://github.com/axa-group/oauth2-mock-server
hacktoberfest mock-server nodejs oauth2 oauth2-server testing
Last synced: 5 months ago
JSON representation
A development and test oriented OAuth2 mock server
- Host: GitHub
- URL: https://github.com/axa-group/oauth2-mock-server
- Owner: axa-group
- License: mit
- Created: 2018-07-20T12:55:47.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2026-01-26T17:50:12.000Z (5 months ago)
- Last Synced: 2026-01-27T04:40:14.036Z (5 months ago)
- Topics: hacktoberfest, mock-server, nodejs, oauth2, oauth2-server, testing
- Language: TypeScript
- Homepage:
- Size: 1.9 MB
- Stars: 227
- Watchers: 10
- Forks: 57
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-starred - axa-group/oauth2-mock-server - A development and test oriented OAuth2 mock server (nodejs)
README
# `oauth2-mock-server`
[](https://www.npmjs.com/package/oauth2-mock-server)
[](https://nodejs.org/)
> _OAuth 2 mock server. Intended to be used for development or testing purposes._
When developing an application that exposes or consumes APIs that are secured with an [OAuth 2](https://oauth.net/2/) authorization scheme, a mechanism for issuing access tokens is needed. Frequently, a developer needs to create custom code that fakes the creation of tokens for testing purposes, and these tokens cannot be properly verified, since there is no actual entity issuing those tokens.
The purpose of this package is to provide an easily configurable OAuth 2 server, that can be set up and teared down at will, and can be programmatically run while performing automated tests.
> **Warning:** This tool is _not_ intended to be used as an actual production grade OAuth 2 server. It lacks many features that would be required in a proper implementation.
## Development prerequisites
- [Node.js 20.19+](https://nodejs.org/)
## How to use
### Installation
Add it to your Node.js project as a development dependency:
```shell
npm install --save-dev oauth2-mock-server
```
### Quickstart
Here is an example for creating and running a server instance with a single random RSA key:
```js
import { OAuth2Server } from 'oauth2-mock-server';
// ...or in CommonJS style:
// const { OAuth2Server } = require('oauth2-mock-server');
let server = new OAuth2Server();
// Generate a new RSA key and add it to the keystore
await server.issuer.keys.generate('RS256');
// Start the server
await server.start(8080, 'localhost');
console.log('Issuer URL:', server.issuer.url); // -> http://localhost:8080
// Do some work with the server
// ...
// Stop the server
await server.stop();
```
Any number of existing JSON-formatted keys can be added to the keystore.
```js
// Add an existing JWK key to the keystore
await server.issuer.keys.add({
kid: 'some-key',
alg: 'RS256',
kty: 'RSA',
// ...
});
```
JSON Web Tokens (JWT) can be built programmatically:
```js
import axios from 'axios';
// Build a new token
let token = await server.issuer.buildToken();
// Call a remote API with the token
axios
.get('https://server.example.com/api/endpoint', {
headers: {
authorization: `Bearer ${token}`,
},
})
.then((response) => {
/* ... */
})
.catch((error) => {
/* ... */
});
```
### Supported grant types
- No authentication
- Client Credentials grant
- Resource Owner Password Credentials grant
- Authorization Code grant, with Proof Key for Code Exchange (PKCE) support
- Refresh token grant
### Supported JWK formats
| Algorithm | kty | alg |
| ----------------- | --- | ------------------- |
| RSASSA-PKCS1-v1_5 | RSA | RS256, RS384, RS512 |
| RSASSA-PSS | RSA | PS256, PS384, PS512 |
| ECDSA | EC | ES256, ES384, ES512 |
| EdDSA | OKP | Ed25519 |
### Customization hooks
It also provides a convenient way, through event emitters, to programmatically customize the server processing. This is particularly useful when expecting the OIDC service to behave in a specific way on one single test.
#### beforeTokenSigning
Typed signature: `(token: MutableToken, req: TokenRequestIncomingMessage) => void`
```js
// Modify the expiration time on next produced token
service.once('beforeTokenSigning', (token, req) => {
const timestamp = Math.floor(Date.now() / 1000);
token.payload.exp = timestamp + 400;
});
```
```js
const basicAuth = require('basic-auth');
// Add the client ID to a token
service.once('beforeTokenSigning', (token, req) => {
const credentials = basicAuth(req);
const clientId = credentials ? credentials.name : req.body.client_id;
token.payload.client_id = clientId;
});
```
#### beforeResponse
Typed signature: `(tokenEndpointResponse: MutableResponse, req: TokenRequestIncomingMessage) => void`
```js
// Force the oidc service to provide an invalid_grant response
// on next call to the token endpoint
service.once('beforeResponse', (tokenEndpointResponse, req) => {
tokenEndpointResponse.body = {
error: 'invalid_grant',
};
tokenEndpointResponse.statusCode = 400;
});
```
#### beforeUserinfo
Typed signature: `(userInfoResponse: MutableResponse, req: IncomingMessage) => void`
```js
// Force the oidc service to provide an error
// on next call to userinfo endpoint
service.once('beforeUserinfo', (userInfoResponse, req) => {
userInfoResponse.body = {
error: 'invalid_token',
error_message: 'token is expired',
};
userInfoResponse.statusCode = 401;
});
```
#### beforeRevoke
Typed signature: `(revokeResponse: StatusCodeMutableResponse, req: IncomingMessage) => void`
```js
// Simulates a custom token revocation result code
service.once('beforeRevoke', (revokeResponse, req) => {
revokeResponse.statusCode = 418;
});
```
#### beforeAuthorizeRedirect
Typed signature: `(authorizeRedirectUri: MutableRedirectUri, req: IncomingMessage) => void`
```js
// Modify the uri and query parameters
// before the authorization redirect
service.once('beforeAuthorizeRedirect', (authorizeRedirectUri, req) => {
authorizeRedirectUri.url.searchParams.set('foo', 'bar');
});
```
#### beforePostLogoutRedirect
Typed signature: `(postLogoutRedirectUri: MutableRedirectUri, req: IncomingMessage) => void`
```js
// Modify the uri and query parameters
// before the post_logout_redirect_uri redirect
service.once('beforePostLogoutRedirect', (postLogoutRedirectUri, req) => {
postLogoutRedirectUri.url.searchParams.set('foo', 'bar');
});
```
#### beforeIntrospect
Typed signature: `(introspectResponse: MutableResponse, req: IncomingMessage) => void`
```js
// Simulate a custom token introspection response body
service.once('beforeIntrospect', (introspectResponse, req) => {
introspectResponse.body = {
active: true,
scope: 'read write email',
client_id: '',
username: 'dummy',
exp: 1643712575,
};
});
```
### HTTPS support
It also provides basic HTTPS support, an optional cert and key can be supplied to start the server with SSL/TLS using the in-built NodeJS [HTTPS](https://nodejs.org/api/https.html) module.
We recommend using a package to create a locally trusted certificate, like [mkcert](https://github.com/FiloSottile/mkcert).
```js
let server = new OAuth2Server(
'test-assets/mock-auth/key.pem',
'test-assets/mock-auth/cert.pem'
);
```
NOTE: Enabling HTTPS will also update the issuer URL to reflect the current protocol.
## Supported endpoints
### GET `/.well-known/openid-configuration`
Returns the [OpenID Provider Configuration Information](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) for the server.
### GET `/jwks`
Returns the JSON Web Key Set (JWKS) of all the keys configured in the server.
### POST `/token`
Issues access tokens.
### GET `/authorize`
Simulates the user authentication. It will automatically redirect to the callback endpoint sent as parameter.
It currently supports only 'code' response_type.
### GET `/userinfo`
Provides extra userinfo claims.
### POST `/revoke`
Simulates a token revocation. This endpoint should always return 200 as stated by [RFC 7009](https://tools.ietf.org/html/rfc7009#section-2.2).
### GET `/endsession`
Simulates the end session endpoint. It will automatically redirect to the post_logout_redirect_uri sent as parameter.
### POST `/introspect`
Simulates the [token introspection endpoint](https://www.oauth.com/oauth2-servers/token-introspection-endpoint/).
## Command-Line Interface
The server can be run from the command line.
```shell
npx oauth2-mock-server --help
```
## Attributions
- [`jose`](https://www.npmjs.com/package/jose)