Skip to content
Helper application for testing OAuth clients
TypeScript JavaScript Shell Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.vscode
e2e
src
tests
.dockerignore
.envrc
.gitignore
.nvmrc
Dockerfile
LICENSE
README.md
deploy-docker.sh
docker-compose.yml
jest.config.js
package-lock.json
package.json
tsconfig.json
tslint.json

README.md

fauxauth

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'
    services:
        some_app:
            ...
            links:
              - oauth
            environment:
                OAUTH_URL: http://oauth
        ...
        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\""
        }
    }

Compatibility

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.

Configuration

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 "http://example.org/"
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).

You can’t perform that action at this time.