Meet npm Pro: unlimited public & private packages + package-based permissions.Learn more »


2.1.0 • Public • Published


License Build Status Test Coverage Maintainability NPM Version Docker Image

Helper application for testing OAuth clients

What is this?

fauxauth is a mock server for testing applications that are using OAuth authentication. Specifically, it was created to pretend to be GitHub's OAuth flow, as documented here.

How can I use it?

fauxauth is set up for two primary use cases:

  • Docker: if you're developing or testing your app using Docker containers, you can make fauxauth part of a multi-container network using Compose.

    Assuming an app that will locate the OAuth provider via an OAUTH_URL environment variable, your docker-compose.yml could look something like:

    version: '3'
              - oauth
                OAUTH_URL: http://oauth
            image: textbook/fauxauth
  • Node Dependency: alternatively, you may want to run fauxauth directly. You can install it from NPM as follows:

    npm install fauxauth --save-dev  # or "yarn add fauxauth -D" 

    Once installed, you can add it to one of your package.json scripts. I find concurrently useful for simplifying development tasks like this, e.g.

        "scripts": {
            "dev": "concurrently -n \"fauxauth,some_app\" \"npm run fauxauth\" \"npm start\""


The compiled version of fauxauth, as released to NPM, is tested against the latest versions of three Node LTS releases: Carbon (8), Dubnium (10) and Erbium (12). Compilation is carried out using TypeScript in the Node version specified in .nvmrc.


You can configure the port that the fauxauth server runs on by setting the PORT environment variable, e.g. using cross-env in your scripts:

    "scripts": {
        "fauxauth": "cross-env PORT=3210 fauxauth"

You can also set the OAuth configuration; it is initially hardcoded as follows:

Name Description Initial value
accessToken The access token to return (randomly generated otherwise) null
callbackUrl The base URL to return or validate redirect_uri against ""
clientId The client ID to be accepted by the /authorize endpoint "1ae9b0ca17e754106b51"
clientSecret The client secret required by the /access_token endpoint "3efb56fdbac1cb21f3d4fea9b70036e04a34d068"
codes The array of valid codes accepted by /access_token []

You can update this configuration by sending a PATCH to the /_configuration endpoint, which accepts the changes as a JSON patch request. A GET to the same endpoint provides the current configuration. You can reset to the default configuration using a DELETE request.

Alternatively, provide a JSON string as the FAUXAUTH_CONFIG environment variable to override all or part of the initial configuration (note that a DELETE reset will return to the combination of the hardcoded configuration above and whatever is provided via this environment variable).


npm i fauxauth

DownloadsWeekly Downloads






Unpacked Size

13.6 kB

Total Files


Last publish


  • avatar
  • avatar