OAuth
OAuth on OpenStreetMap is a mechanism which allows users to authorize third party applications to do things with their OSM user account - without that application handling the user's password.
Usage for developers (OAuth 2.0)
You can register your consumer application on your OpenStreetMap user settings page via the OAuth 2 applications link at the top of the page. OpenStreetMap supports only OAuth 2.0. The access tokens currently do not expire automatically.
Make sure, to use the dev server API, you have created an account in dev server also. The live server and dev server do not share the same database. So you need to create an account with new username and password and use its consumer secret and key.
Supported Grant types: Authorization Code, Authorization Code with PKCE
Add authorization data to Request Headers
Production:
- Auth URL: https://www.openstreetmap.org/oauth2/authorize
- Access Token URL: https://www.openstreetmap.org/oauth2/token
Development:
- Auth URL: https://master.apis.dev.openstreetmap.org/oauth2/authorize
- Access Token URL: https://master.apis.dev.openstreetmap.org/oauth2/token
Supported scopes:
Note: scope names differ from the list of permissions used for OAuth 1.0a: the previously used "allow_" prefix has been dropped
- read_prefs: read their user preferences
- write_prefs: modify their user preferences
- write_diary: create diary entries, comments and make friends
- write_api: modify the map
- read_gpx: read their private GPS traces
- write_gpx: upload GPS traces
- write_notes: modify notes
- write_redactions: redact element versions
- consume_messages: read, mark and delete messages received from other users
- send_messages: send messages to other users
OAuth 2.0 Authorization Server Metadata (RFC 8414): https://www.openstreetmap.org/.well-known/oauth-authorization-server
The basic idea
An application, for example JOSM, or a website, for example OSMCha could receive permission to make edits to OpenStreetMap data with the user's account.
OAuth is used by some other sites such as twitter and flickr. If you use a flickr uploader app for example, you can see how the authorisation would work from a user perspective. When you try to use the app, it needs to direct the user to the website, where you log in as usual, and then grant permissions. The app then receives a token which it can use in its requests. It eliminates the need for the app to know about the user's login credentials. Nifty.
Development (OAuth 2.0)
Registering your application as OAuth 2.0 consumer
Before an application can use the OAuth protocol to gain authorized access to the protected resources on the OSM server it has to be registered as OAuth consumer. Every registered user can register applications as consumer.
- Log in to your account
- Go to https://www.openstreetmap.org/oauth2/applications/new
- Name
- This is the display name of your application. Which will be presented to the user.
- Redirect URI
- List of allowed URIs to which the user can be redirected after authorizing the application. All URIs must use https unless an URL starting with http://127.0.0.1 is used. The special URI of urn:ietf:wg:oauth:2.0:oob should be used for non-web application where the user will copy the authorization code to the application.
- Confidential application
- Application will be used where the client secret can be kept confidential (native mobile apps and single page apps are not confidential)
- Scopes
- Select all scopes which may be requested by a client
Basics of the protocol
- Register an application with application's name, redirect URIs and scope(s) (See Registering your application as OAuth 2.0 consumer). The next page will display the "client ID", and the "client secret". Theses two settings are needed for next steps. The "client ID" can be retrieved again from "OAuth2 Applications" in user account, but the "client secret" must be saved since it cannot be shown again.
- The user need to log in within the application from a specific OpenStreetMap login page, crafted as such:
{AUTHORIZE_URL}?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPE1}%20{SCOPE2}, for example:https://master.apis.dev.openstreetmap.org/oauth2/authorize?response_type=code&client_id=1234567890-client-id&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=read_prefs%20write_api. Note the client secret is not needed for this step. - If CLIENT_ID and REDIRECT_URI match the informations, and SCOPE1 and SCOPE2 are one of the specified scopes, specified when registering the application, the user will be redirected to a login page, or directly to the "Authorization Required" page if already logged-in, to authorize the application access.
- Once authorized, the user will be redirected to the REDIRECT_URI that will include the "Application code". If the special value urn:ietf:wg:oauth:2.0:oob has been used, the user is redirected to another page that displays this "Application code" (in red monospace font) that the user need to copy and paste into the application/script for the next steps. This application code has a short lifetime (can be few minutes, and could even be used once) so this step is mandatory a each use of the API, as it is needed to get an Access token.
- With a valid and not expired "Application code", a POST request must be sent to the Access Token URL to get an access token, using this payload:
grant_type=authorization_code&code={APPLICATION_CODE}&redirect_uri={REDIRECT_URI}&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}. Note that this request needs the client secret, so it must be saved into application/script to request a new token each time the previous token has expired (e.g. the user has revoked the application authorization). Requesting an access token using cURL can be done as:curl -X POST -d 'grant_type=authorization_code&code=1234567890-application-code&redirect_uri=urn:ietf:wg:oauth:2.0:oob&client_id=1234567890-client-id&client_secret=1234567890-client-s3cr3t' 'https://master.apis.dev.openstreetmap.org/oauth2/token' - On success, the API returns a JSON response with the access token known as "Bearer". For example:
{ "access_token": "1234567890-access-token", "token_type": "Bearer", "scope": "read_prefs write_api", "created_at":1646669786 }. Since this token can be reused as long as valid, it should be stored by the client for other requests, to avoid the need for the user to enter its credentials again. - Finally, when submitting an API request, the client always needs to add the "Authorization" header in HTTP request, with the access token prefixed by "Bearer", as value, such as
Authorization: Bearer 1234567890-access-token. The API will return an error if the token has expired. If so, the client must request another access token as described from step 5.
Using OpenStreetMap as identity provider
If you want to setup a third party service (e.g. a panoramax server, Forgejo instance, Mastodon instance) where you want to enable log in with OpenStreetMap, start with registering an application as described above. You'll need to enable the scope Signing in with OpenStreetMap (openid).
Then, you'll have to configure the third party software. If the software supports a OpenID Connect Discovery URL, use https://www.openstreetmap.org/.well-known/openid-configuration
Extra notes
- https://api.openstreetmap.org/api/0.6/user/details is the xml of the logged in user (requires the "read their user preferences" scope/permission)
- https://api.openstreetmap.org/api/0.6/user/details.json is the json of the logged in user (requires the "read their user preferences" scope/permission)
Examples
Examples of implementations in various languages.
External resources
- Basics of the protocol (oauth_verifier not needed)
- https://oauth.net
- https://oauth.net/2
- https://en.wikipedia.org/wiki/OAuth
- https://blog.stakeventures.com/articles/developing-oauth-clients-in-ruby