Neurological Phenomenon Multiplexer

    TypeScript icon, indicating that this package has built-in type declarations

    5.0.12 • 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

      You should generally specify a tag to use, rather than use the default :latest; the build process for release vX.Y.Z creates the tags :vX, :vX.Y and :vX.Y.Z and publishes them all to Docker Hub, so you can pick a level of stability you're comfortable with (e.g. :v2 is equivalent to NPM semver's ^2.0.0, whereas :v2.1 is equivalent to ~2.1.0).

    • 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\""

    Roll your own

    (New in v4.2)

    You can also import the app factory and create your own app:

    import appFactory from "fauxauth";
    // or `const { default: appFactory } = require("fauxauth");`
    const app = appFactory({ redirectUrl: "http://localhost:3001" });
    app.listen(4200, () => {
    	console.log("I'm listening...");


    The compiled version of fauxauth, as released to NPM, is tested against the latest versions of the active Node LTS releases, currently Erbium (12), Fermium (14) and Gallium (16). 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"


    (New in v4.2.2)

    You can configure debug logging using the DEBUG environment variable. fauxauth uses the standard debug package, so you can enable all logs by setting DEBUG=fauxauth:* or enable more specific namespaces as needed.


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

    Name Description Initial value
    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 codes accepted by /access_token and their tokens {}
    tokenMap A map from choices (e.g. roles) to a token for that choice undefined

    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 initial configuration using a DELETE request.

    Alternatively, use the following methods to override all or part of the default configuration (in priority order, highest first):

    (Options other than FAUXAUTH_CONFIG new in v5.0)

    • CLI flags, e.g. fauxauth --client-id=my-client-id
    • A fauxauth key in your package.json:
        "fauxauth": {
          "callbackUrl": "http://localhost:4321"
    • Individual environment variables, e.g. FAUXAUTH_CLIENT_SECRET=supersecret fauxauth
    • A JSON string as the FAUXAUTH_CONFIG environment variable

    Token map

    (New in v4.0)

    If you set a token map, instead of immediately redirecting to the specified redirect URI, fauxauth will render a page where the user can select which token they want to use. For example, given the following FAUXAUTH_CONFIG:

      "tokenMap": {
        "Headteacher": "86d66c5b7532a0083612",
        "Teacher": "1d4fdc5bb3aefa5a01dd",
        "Student": "4d39f64b071e49aeedce"

    something like the following form will be rendered:

    <form action="/authorize" method="post" id="root-form">
        <label for="role-select">
            Select token
            <select id="role-select" name="code">
                <option value="288e5e60aa9220000000">Headteacher</option>
                <option value="c4f9e4bfffa600000000">Teacher</option>
                <option value="76555f344527c0000000">Student</option>
        <!-- hidden inputs -->
        <button id="submit-button" type="submit">Authenticate</button>

    When the form is submitted, the location will be changed to the specified redirect URI but with the code replaced with the choice value (e.g. The correct request to the /access_token endpoint with that code will recover the specified token, 1d4fdc5bb3aefa5a01dd.

    For example, this allows you to configure tokens representing different roles, so that a developer or automated test can choose the appropriate role to "log in" as.

    How can I work on it?

    Fork and clone the repository to your local machine, then run npm run install:all to install the relevant dependencies in both the root directory and e2e/. If you need to install a specific version of Chromedriver, you can set the CHROME_VERSION environment variable while running install:all.

    To run the full automated validation suite (lint, build and test), run npm run ship.


    npm i fauxauth

    DownloadsWeekly Downloads






    Unpacked Size

    23.1 kB

    Total Files


    Last publish


    • textbook
    • fauxauth-service