{"id":19486242,"url":"https://github.com/textbook/fauxauth","last_synced_at":"2025-10-20T12:48:31.734Z","repository":{"id":39674412,"uuid":"153947713","full_name":"textbook/fauxauth","owner":"textbook","description":"Helper application for testing OAuth clients","archived":false,"fork":false,"pushed_at":"2024-03-29T11:14:18.000Z","size":4174,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-11T03:03:58.612Z","etag":null,"topics":["oauth","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/textbook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-10-20T20:57:42.000Z","updated_at":"2024-05-11T03:03:58.613Z","dependencies_parsed_at":"2024-04-01T10:31:58.954Z","dependency_job_id":null,"html_url":"https://github.com/textbook/fauxauth","commit_stats":null,"previous_names":[],"tags_count":116,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textbook%2Ffauxauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textbook%2Ffauxauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textbook%2Ffauxauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/textbook%2Ffauxauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/textbook","download_url":"https://codeload.github.com/textbook/fauxauth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250872207,"owners_count":21500774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["oauth","testing-tools"],"created_at":"2024-11-10T20:35:59.172Z","updated_at":"2025-10-20T12:48:26.696Z","avatar_url":"https://github.com/textbook.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fauxauth\n\n[![License](https://img.shields.io/github/license/textbook/fauxauth.svg)](https://github.com/textbook/fauxauth/blob/main/LICENSE)\n[![Build Status](https://github.com/textbook/fauxauth/actions/workflows/push.yml/badge.svg)](https://github.com/textbook/fauxauth/actions/workflows/push.yml)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/ec914e9fdeba3ccb3e0b/test_coverage)](https://codeclimate.com/github/textbook/fauxauth/test_coverage)\n[![Maintainability](https://api.codeclimate.com/v1/badges/ec914e9fdeba3ccb3e0b/maintainability)](https://codeclimate.com/github/textbook/fauxauth/maintainability)\n[![npm Version](https://img.shields.io/npm/v/fauxauth.svg)](https://www.npmjs.com/package/fauxauth)\n[![Docker Image](https://img.shields.io/docker/image-size/textbook/fauxauth?sort=semver)](https://hub.docker.com/r/textbook/fauxauth/)\n\nHelper application for testing OAuth clients\n\n## What is this?\n\n`fauxauth` is a mock server for testing applications that are using OAuth\nauthentication. Specifically, it was created to pretend to be GitHub's OAuth\nflow, as documented [here][4].\n\n## How can I use it?\n\n`fauxauth` is set up for two primary use cases:\n\n- **Docker**: if you're developing or testing your app using Docker containers,\n  you can make `fauxauth` part of a multi-container network using [Compose][1].\n\n  Assuming an app that will locate the OAuth provider via an `OAUTH_URL`\n  environment variable, your `docker-compose.yml` could look something like:\n\n  ```yaml\n  ---\n  services:\n      some_app:\n          ...\n          links:\n            - oauth\n          environment:\n              OAUTH_URL: http://oauth\n      ...\n      oauth:\n          image: textbook/fauxauth\n  ```\n\n  You should generally specify a tag to use, rather than use the default\n  `:latest`; the build process for release `vX.Y.Z` creates the tags `:vX`,\n  `:vX.Y` and `:vX.Y.Z` and publishes them all to Docker Hub, so you can pick\n  a level of stability you're comfortable with (e.g. `:v2` is equivalent to\n  npm semver's `^2.0.0`, whereas `:v2.1` is equivalent to `~2.1.0`).\n\n- **Node Dependency**: alternatively, you may want to run `fauxauth` directly.\n  You can install it from npm as follows:\n\n  ```bash\n  npm install fauxauth --save-dev  # or \"yarn add fauxauth -D\"\n  ```\n\n  Once installed, you can add it to one of your `package.json` scripts. I find\n  [`concurrently`][2] useful for simplifying development tasks like this, e.g.\n\n  ```json\n  {\n      ...\n      \"scripts\": {\n          ...\n          \"dev\": \"concurrently -n \\\"fauxauth,some_app\\\" \\\"npm run fauxauth\\\" \\\"npm start\\\"\"\n      }\n  }\n  ```\n\n### Roll your own\n\n_(New in v4.2)_\n\nYou can also import the app factory and create your own app:\n\n```js\nimport appFactory from \"fauxauth\";\n\nconst app = appFactory({ callbackUrl: \"http://localhost:3001\" });\n\napp.listen(4200, () =\u003e {\n\tconsole.log(\"I'm listening...\");\n});\n```\n\n#### Core router\n\n_(New in v8.1)_\n\nAlternatively, you can get direct access to the core router, although you have\nto take more responsibility for setup:\n\n```js\nimport express from \"express\";\nimport { coreRouter } from \"fauxauth\";\n\nconst app = express();\nconst { middleware, routes, views } = coreRouter({/* any configuration */});\n\n// Ensure the select page can render\napp.set(\"view engine\", views.engine);\napp.set(\"views\", views.directory);\n\n// Register required middleware\napp.use(middleware);\n\n// Mount the routes wherever you like\napp.use(\"/login/oauth\", routes);\n```\n\nNote that only the `/authorize` and `/access_token` routes are exposed this way.\n\n### Compatibility\n\nThe compiled version of `fauxauth`, as released to npm, is tested against the\nlatest versions of the active Node LTS releases, currently Hydrogen (18), Iron\n(20) and Jod (22). Compilation is carried out using TypeScript in the Node\nversion specified in `.nvmrc`. The lowest supported version is documented in\n`package.json`'s `engines` field.\n\n### Options\n\n#### PORT\nYou can configure the port that the `fauxauth` server runs on by setting the\n`PORT` environment variable, e.g. using [`cross-env`][3] in your scripts:\n\n```json\n{\n    ...\n    \"scripts\": {\n        ...\n        \"fauxauth\": \"cross-env PORT=3210 fauxauth\"\n    }\n}\n```\n\n#### DEBUG\n\n_(New in v4.2.2)_\n\nYou can configure debug logging using the `DEBUG` environment variable.\n`fauxauth` uses the standard [`debug`][6] package, so you can enable all logs\nby setting `DEBUG=fauxauth:*` or enable more specific namespaces as needed.\n\n#### Configuration\n\nYou can also set the OAuth configuration; it is initially hardcoded as follows:\n\n| Name           | Description                                                | Initial value                                |\n|----------------|------------------------------------------------------------|----------------------------------------------|\n| `appendScopes` | Add the scopes to the token (e.g. `\"token/scope1/scope2\"`) | `false`                                      |\n| `callbackUrl`  | The base URL to return or validate `redirect_uri` against  | `\"http://example.org/\"`                      |\n| `clientId`     | The client ID to be accepted by the `/authorize` endpoint  | `\"1ae9b0ca17e754106b51\"`                     |\n| `clientSecret` | The client secret required by the `/access_token` endpoint | `\"3efb56fdbac1cb21f3d4fea9b70036e04a34d068\"` |\n| `codes`        | The codes accepted by `/access_token` and their tokens     | `{}`                                         |\n| `tokenMap`     | A map from choices (e.g. roles) to a token for that choice | `undefined`                                  |\n\nYou can update this configuration by sending a `PATCH` to the `/_configuration`\nendpoint, which accepts the changes as a [JSON patch][5] request. A `GET` to the\nsame endpoint provides the current configuration. You can reset to the initial\nconfiguration using a `DELETE` request.\n\nAlternatively, use the following methods to override all or part of the default\nconfiguration (in priority order, highest first):\n\n_(Options other than `FAUXAUTH_CONFIG` new in v5.0)_\n\n- CLI flags, e.g. `fauxauth --client-id=my-client-id`\n- A `fauxauth` key in your `package.json`:\n    ```json\n    {\n      ...\n      \"fauxauth\": {\n        \"callbackUrl\": \"http://localhost:4321\"\n      }\n    }\n    ```\n- Individual environment variables, e.g. `FAUXAUTH_CLIENT_SECRET=supersecret fauxauth`\n- A JSON string as the `FAUXAUTH_CONFIG` environment variable\n\n### Token map\n\n_(New in v4.0)_\n\nIf you set a token map, instead of immediately redirecting to the specified\nredirect URI, `fauxauth` will render a page where the user can select which\ntoken they want to use. For example, given the following `FAUXAUTH_CONFIG`:\n\n```json\n{\n  \"tokenMap\": {\n    \"Headteacher\": \"86d66c5b7532a0083612\",\n    \"Teacher\": \"1d4fdc5bb3aefa5a01dd\",\n    \"Student\": \"4d39f64b071e49aeedce\"\n  }\n}\n```\n\nsomething like the following form will be rendered:\n\n```html\n\u003cform action=\"/authorize\" method=\"post\" id=\"root-form\"\u003e\n    \u003clabel for=\"role-select\"\u003e\n        Select identity:\n        \u003cselect id=\"role-select\" name=\"code\"\u003e\n            \u003coption value=\"288e5e60aa9220000000\"\u003eHeadteacher\u003c/option\u003e\n            \u003coption value=\"c4f9e4bfffa600000000\"\u003eTeacher\u003c/option\u003e\n            \u003coption value=\"76555f344527c0000000\"\u003eStudent\u003c/option\u003e\n        \u003c/select\u003e\n    \u003c/label\u003e\n\n    \u003c!-- hidden inputs --\u003e\n\n    \u003c!-- scope checkboxes (if relevant, see below) --\u003e\n\n    \u003cbutton id=\"submit-button\" type=\"submit\"\u003eAuthenticate\u003c/button\u003e\n\u003c/form\u003e\n```\n\nWhen the form is submitted, the location will be changed to the specified\nredirect URI but with the code replaced with the choice value (e.g.\n`http://example.org/?code=c4f9e4bfffa600000000`). The correct request to the\n`/access_token` endpoint with that code will recover the specified token,\n`1d4fdc5bb3aefa5a01dd`.\n\nFor example, this allows you to configure tokens representing different roles,\nso that a developer or automated test can choose the appropriate role to \"log\nin\" as.\n\n### Scopes\n\n_(New in v8.0)_\n\nFrom v8, `fauxauth` handles the scopes in the `GET /authorize` request. By\ndefault these will simply be retained through the process and included in the\nresponse to `POST /access_token`. For example if the initial request was:\n\n```none\nGET .../authorize?client_id=...\u0026scope=foo+bar\n```\n\nthen the response to the `POST /access_token` request using the resulting\ncode would include `foo,bar` as the value of the `scope` property.\n\nIf you use the `tokenMap` browser-based flow, the scopes will be rendered as\na set of checkboxes (all checked by default). The user can remove any or all\nof these scopes; the response to `POST /access_token` will reflect this in the\n`scope` property.\n\nIf you set the `appendScopes` configuration option, the scopes are appended to\nthe token returned in the response to `POST /access_token`. For example, if\nthe scopes were `read:user` and `user:email` and the token (whether generated\nautomatically or provided in a token map) was `somerandomtoken`, the token in\nthe response would be `somerandomtoken/read:user/user:email`. This allows\ntesting of workflows where the user doesn't accept all of the requested\nscopes.\n\n## How can I work on it?\n\nFork and clone the repository to your local machine and run `npm install` or\n`npm ci`to install the relevant dependencies.\n\nTo run the full automated validation suite (lint, build and test), run `npm\nrun ship`.\n\n[1]: https://docs.docker.com/compose/\n[2]: https://www.npmjs.com/package/concurrently\n[3]: https://www.npmjs.com/package/cross-env\n[4]:\n  https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow\n[5]: http://jsonpatch.com/\n[6]: https://www.npmjs.com/package/debug\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftextbook%2Ffauxauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftextbook%2Ffauxauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftextbook%2Ffauxauth/lists"}