{"id":13555503,"url":"https://github.com/osmlab/osm-auth","last_synced_at":"2025-08-24T18:45:18.121Z","repository":{"id":7618770,"uuid":"8977732","full_name":"osmlab/osm-auth","owner":"osmlab","description":"Easy authentication for OpenStreetMap over OAuth2.0","archived":false,"fork":false,"pushed_at":"2025-01-17T21:57:42.000Z","size":653,"stargazers_count":71,"open_issues_count":4,"forks_count":26,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-13T00:49:01.149Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://osmlab.github.io/osm-auth/","language":"JavaScript","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/osmlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-03-23T22:01:57.000Z","updated_at":"2025-04-07T07:47:06.000Z","dependencies_parsed_at":"2023-02-17T07:45:31.015Z","dependency_job_id":"5929bfbb-5482-4fde-8616-d8a85c179b1a","html_url":"https://github.com/osmlab/osm-auth","commit_stats":{"total_commits":130,"total_committers":16,"mean_commits":8.125,"dds":0.7692307692307692,"last_synced_commit":"76d0195accce32671b0a38ca74855dcb6dad25b7"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osmlab%2Fosm-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osmlab","download_url":"https://codeload.github.com/osmlab/osm-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650436,"owners_count":21139672,"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":[],"created_at":"2024-08-01T12:03:14.969Z","updated_at":"2025-08-24T18:45:18.078Z","avatar_url":"https://github.com/osmlab.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"readme":"[![build](https://github.com/osmlab/osm-auth/workflows/build/badge.svg)](https://github.com/osmlab/osm-auth/actions?query=workflow%3A%22build%22)\n[![npm version](https://badge.fury.io/js/osm-auth.svg)](https://badge.fury.io/js/osm-auth)\n\n# osm-auth\n\nEasy authentication with [OpenStreetMap](http://www.openstreetmap.org/) over [OAuth 2.0](https://oauth.net/2/).\u003cbr/\u003e\nSee also: https://wiki.openstreetmap.org/wiki/OAuth\n\n\u003e [!IMPORTANT]\n\u003e Due to [security changes on 8 July 2025](https://github.com/openstreetmap/openstreetmap-website/commit/2ff4d6), authentication using the `popup` mode will not work until you:\n\u003e\n\u003e 1. update this library to v3.0.0\n\u003e 2. AND update the code snippet in your `land.html` file to the latest version (see [this example](https://github.com/osmlab/osm-auth/tree/master/land.html))\n\n\nNote that openstreetmap.org currently only supports OAuth2.0. [OAuth1.0 is turned off](https://github.com/openstreetmap/operations/issues/867). If you want the older version of this library that supports **OAuth 1.0a** (e.g. for a sister project that uses an older OSM-stack), use [the v1 branch](https://github.com/osmlab/osm-auth/tree/v1) and pin your software to older [release versions \u003c2](https://github.com/osmlab/osm-auth/releases).  Going forward, the v1 branch will receive limited attention.\n\n\n## Demo\n\nTry it out now at: https://osmlab.github.io/osm-auth/\n\nOr you can run the demo locally by cloning this project, then run:\n\n```sh\n$ npm install\n$ npm run build\n$ npm start\n```\n\nThis will start a local server on port 8080. Then open `http://127.0.0.1:8080/` in a browser.\n\n\n## Usage\n\n### Use in Node\n\nTo install osm-auth as a dependency in your project:\n```bash\n$  npm install --save osm-auth\n```\n\n**osm-auth** is distributed in CJS and ESM module formats for maxmimum compatibility. ([Read more about Javascript module formats](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm))\n\n\n```js\nconst osmAuth = require('osm-auth').osmAuth;   // CJS named import\n// or\nimport { osmAuth } from 'osm-auth';   // ESM named import\n```\n\n\n### Use in Browsers\n\nYou can also use **osm-auth** directly in a web browser.  A good way to do this is to fetch the [\"iife\"](https://esbuild.github.io/api/#format-iife) bundle from the [jsDelivr CDN](https://www.jsdelivr.com/), which can even deliver minified versions.\n\nWhen you load this file in a `\u003cscript\u003e` tag, you'll get a `osmAuth` global to use elsewhere in your scripts:\n```html\n\u003chead\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/osm-auth@3/dist/osm-auth.iife.min.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n…\n\u003cscript\u003e\n// example here\n\u003c/script\u003e\n```\n\n\u0026nbsp;\n\n\n**Requires `land.html` to be accessible, or a page that does the same thing -\ncalls an auth complete function - to be available.**\n\n\n### Support\n\nThis project is tested in supported node versions and modern browsers.\nWe attempt to use JavaScript syntax that will work in legacy environments like ES5 or Internet Explorer, but offer no guarantee that it will work.\nIf you're targeting an environment like this, you're probably already building your own bundle with something like [Babel](https://babeljs.io/docs/en/index.html).\n\n\n## Registering an application\nSee: https://wiki.openstreetmap.org/wiki/OAuth#OAuth_2.0_2\n\nRegister a new OAuth2.0 application on openstreetmap.org:\n\n1. Go to your user page\n2. Click 'My Settings'\n3. Click 'OAuth 2 applications'\n4. At the bottom, 'Register new application'\n5. Fill in the form (keeping the _Confidential application?_ checkbox unchecked) \u0026 submit\n6. Copy \u0026 Paste the client ID, redirect URI, and scope(s) into the osmAuth config object as below\n\n👉 Important:\n- The \"Redirect URIs\" are URIs that OSM is allowed to redirect the user back to.  You can supply multiple Redirect URIs separated by spaces, and change them later.\n- Redirect URIs must use `https`, except for `127.0.0.1`, which may use `http`\n\n\n### Example\n\n```js\nvar redirectPath = window.location.origin + window.location.pathname;\nvar auth = osmAuth.osmAuth({\n  client_id: \"JWXSAzNp64sIRMStTnkhMRaMxSR964V4sFgn3KUZNTA\",\n  redirect_uri: redirectPath + \"land.html\",\n  scope: \"read_prefs\",\n  auto: true  // show a login form if the user is not authenticated and you try to do a call\n});\n\ndocument.getElementById(\"authenticate\").onclick = function () {\n  // Signed method call - since `auto` is true above, this will\n  // automatically start an authentication process if the user isn't\n  // authenticated yet.\n  auth.xhr({ method: \"GET\", path: \"/api/0.6/user/details\" },\n    function (err, result) {\n      // result is an XML DOM containing the user details\n    }\n  );\n};\n```\n\n### Example with single-page\n```js\nvar redirectPath = window.location.origin + window.location.pathname;\nvar auth = osmAuth.osmAuth({\n  client_id: \"JWXSAzNp64sIRMStTnkhMRaMxSR964V4sFgn3KUZNTA\",\n  redirect_uri: redirectPath,\n  scope: \"read_prefs\", // scopes should be separated by a space, e.g. \"read_prefs write_prefs\". See https://wiki.openstreetmap.org/wiki/OAuth#OAuth_2.0 for all scopes\n  auto: true  // show a login form if the user is not authenticated and you try to do a call\n  singlepage: true,\n});\n\ndocument.getElementById(\"authenticate\").onclick = function () {\n  // Signed method call - since `auto` is true above, this will\n  // automatically start an authentication process if the user isn't\n  // authenticated yet.\n  auth.xhr({ method: \"GET\", path: \"/api/0.6/user/details\" },\n    function (err, result) {\n      // result is an XML DOM containing the user details\n    }\n  );\n};\n\nif (window.location.search.slice(1).split('\u0026').some(p =\u003e p.startsWith('code='))) {\n  auth.authenticate(function() {\n    // Fully authed at this point\n  });\n}\n```\n\n# API\n\n## `.osmAuth(options)`\n\nConstructs an `osmAuth` instance.\u003cbr/\u003e\nAt a minimum, `options` must contain OAuth2 client ID, redirect URI, and scope(s):\n\n```js\nvar redirectPath = window.location.origin + window.location.pathname;\n{\n  client_id: \"JWXSAzNp64sIRMStTnkhMRaMxSR964V4sFgn3KUZNTA\",\n  redirect_uri: redirectPath + \"land.html\",\n  scope: \"read_prefs\"\n}\n```\n\nAdditional options are:\n\n - `access_token` - Can pre-authorize with an OAuth2 bearer token if you have one\n - `apiUrl` - A base url for the OSM API (default: \"https://api.openstreetmap.org\")\n - `url` - A base url for the OAuth2 handshake (default: \"https://www.openstreetmap.org\")\n - `auto` - If `true`, attempt to authenticate automatically when calling `.xhr()` or `fetch()` (default: `false`)\n - `singlepage` - If `true`, use page redirection instead of a popup (default: `false`)\n - `loading` - Function called when auth-related xhr calls start\n - `done` - Function called when auth-related xhr calls end\n\n\n## `.logout()`\n\nRemoves any stored authentication tokens (legacy OAuth1 tokens too)\u003cbr/\u003e\n\u003cbr/\u003e\nReturns: `self`\u003cbr/\u003e\n\n\n## `.authenticated()`\n\nTest whether the user is currently authenticated\u003cbr/\u003e\n\u003cbr/\u003e\nReturns: `true` if authenticated, `false` if not\u003cbr/\u003e\n\n\n## `.authenticate(callback, options?)`\n\nFirst logs out, then runs the authentiation flow, finally calls the callback.\u003cbr/\u003e\n\u003cbr/\u003e\nParam:   `callback`  An \"errback\"-style callback (`err`, `result`), called when complete\u003cbr/\u003e\nParam:   `options`  Optional, an object which can contain `switchUser`. If `switchUser` is `true`, then the user will first be prompted to logout, then login, then go to the oauth flow.\u003cbr/\u003e\nReturns:  none\u003cbr/\u003e\n\n\n## `.authenticateAsync(options?)`\n\nPromisified version of `.authenticate()`\u003cbr/\u003e\nFirst logs out, then runs the authentication flow and resolves if successful, or rejects if not.\u003cbr/\u003e\n\u003cbr/\u003e\nParam:   `callback`  An \"errback\"-style callback (`err`, `result`), called when complete\u003cbr/\u003e\nParam:   `options`  Optional, an object which can contain `switchUser`. If `switchUser` is `true`, then the user will first be prompted to logout, then login, then go to the oauth flow.\u003cbr/\u003e\nReturns:  `Promise` settled with whatever authenticate did.\u003cbr/\u003e\n\n\n## `.bringPopupWindowToFront()`\n\nTries to bring an existing authentication popup to the front.\u003cbr/\u003e\n\u003cbr/\u003e\nReturns: `true` on success or `false` if there is no authentication popup or if it couldn't be brought to the front (e.g. because of cross-origin restrictions).\u003cbr/\u003e\n\n\n## `.bootstrapToken(auth_code, callback)`\n\nThe authorization code is a temporary code that a client can exchange for an access token. If using this library in single-page mode, you'll need to call this once your application has an `auth_code` and wants to get an access_token.\n\u003cbr/\u003e\nParam:  `auth_code`  The OAuth2 `auth_code`\u003cbr/\u003e\nParam:  `callback`   An \"errback\"-style callback (`err`, `result`), called when complete\u003cbr/\u003e\nReturns:  none\u003cbr/\u003e\n\n\n## `.fetch(resource, options)`\n\nA `fetch` wrapper that includes the Authorization header if the user is authenticated.\u003cbr/\u003e\nSee: https://developer.mozilla.org/en-US/docs/Web/API/fetch\u003cbr/\u003e\n\u003cbr/\u003e\nParam: `resource`  Resource passed to `fetch`\u003cbr/\u003e\nParam: `options`   Options passed to `fetch`\u003cbr/\u003e\nReturn: `Promise` that wraps `authenticateAsync` then `fetch`\u003cbr/\u003e\n\n\n## `.xhr(options, callback)`\n\nA `XMLHttpRequest` wrapper that does authenticated calls if the user has logged in.\u003cbr/\u003e\nSee: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest\u003cbr/\u003e\n\u003cbr/\u003e\nParam: `options`:\u003cbr/\u003e\n  `options.method`   Passed to `xhr.open`  (e.g. 'GET', 'POST')\u003cbr/\u003e\n  `options.prefix`   If `true` path contains a path, if `false` path contains the full url\u003cbr/\u003e\n  `options.path`     The URL path (e.g. \"/api/0.6/user/details\") (or full url, if `prefix`=`false`)\u003cbr/\u003e\n  `options.content`  Passed to `xhr.send`\u003cbr/\u003e\n  `options.headers`  optional `Object` containing request headers\u003cbr/\u003e\nParam: `callback`  An \"errback\"-style callback (`err`, `result`), called when complete\u003cbr/\u003e\nReturn: `XMLHttpRequest` if authenticated, otherwise `null`\u003cbr/\u003e\n\n\n## `rawxhr(method, url, access_token, data, headers, callback)`\n\nCreates the XMLHttpRequest set up with a header and response handling.\u003cbr/\u003e\nSee: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest\u003cbr/\u003e\n\u003cbr/\u003e\nParam:  `method`         Passed to `xhr.open`  (e.g. 'GET', 'POST')\u003cbr/\u003e\nParam:  `url`            Passed to `xhr.open`\u003cbr/\u003e\nParam:  `access_token`   The OAuth2 bearer token\u003cbr/\u003e\nParam:  `data`           Passed to `xhr.send`\u003cbr/\u003e\nParam:  `headers`        `Object` containing request headers\u003cbr/\u003e\nParam:  `callback`       An \"errback\"-style callback (`err`, `result`), called when complete\u003cbr/\u003e\nReturn: `XMLHttpRequest`\u003cbr/\u003e\n\n\n## `.preauth(val)`\n\nPre-authorize this object, if we already have the bearer token from the start.\u003cbr/\u003e\n\u003cbr/\u003e\nParam:   `val`   `Object` containing `access_token` property\u003cbr/\u003e\nReturn:  `self`\u003cbr/\u003e\n\n\n## `.options(options)`\n\nOptions  (getter / setter)\u003cbr/\u003e\n If passed with no arguments, just return the options\u003cbr/\u003e\n If passed an Object, set the options then attempt to pre-authorize\u003cbr/\u003e\n\u003cbr/\u003e\nParam:  `val?`   Object containing options\u003cbr/\u003e\nReturn:  current `options` (if getting), or `self` (if setting)\u003cbr/\u003e\n\u003cbr/\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmlab%2Fosm-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosmlab%2Fosm-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosmlab%2Fosm-auth/lists"}