OAuth

From OpenStreetMap Wiki
Jump to navigation Jump to search
Oauth logo.svg

broom

This article or section may contain out-of-date information: Some details on the new OAuth 2.0 support are not yet included on this page.
If you know about the current state of affairs, please help keep everyone informed by updating this information. (Discussion)

OAuth on OpenStreetMap is a mechanism which allows users to authorise third party applications to do things with their OSM user account - without that application handling the user's password. The User Credentials Policy recommends application developers should use OAuth in preference to HTTP Basic Auth or other methods for access to the API.

Usage for developers

You can register your consumer application on your OpenStreetMap user settings page via the OAuth 1 settings link or the OAuth 2 applications link at the top of the page. OpenStreetMap supports OAuth 1.0a and 2.0. OAuth 2.0 should be used for any new application. 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.

OAuth 1.0a

Here are the relevant URLs for reference:

For development and testing purposes, the API instance on the dev server also has OAuth endpoints. Their URLs are:

There are multiple scopes to assign selected permissions to a customer app.

OAuth 2.0

Supported Grant types: Authorization Code, Authorization Code with PKCE

Add authorization data to Request Headers

Production:

Development:

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

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 1.0a

See OAuth examples for code snippets and links to working tools' source code in various languages, to help you create OpenStreetMap OAuth clients.

Registering your application as OAuth 1.0a 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.

  1. Login to your account
  2. Go to https://www.openstreetmap.org/user/username/oauth_clients/new

In the following form you have to enter four parameters:

Name
this is the display name of your application. Which will be presented to the user.
Main Application URL (Required)
this is an information URL with information about your application. It isn't related to the OAuth protocol at all. When a user authorises access from your application on the OSM website, the OSM website will display a link <a href="info-url-to-your-app">Name of your App</a>.
Callback URL
if you register a web application you can enter a callback URL the OSM website will invoke redirect the user at the end of the OAuth handshake. The URL is optional. Leave it empty if your web application doesn't provide a callback URL. If you are registering a rich client application then either leave it empty or point it to a page that says something like "now close the browser and go back to the application".
Support URL
leave it empty. I have no idea what it is used for.

Basics of the protocol

  1. you register your application (consumer) and supply CONSUMER_KEY + CONSUMER_SECRET into it
  2. some user runs your application, it calls Request Token URL and receives: oauth_token + oauth_token_secret
  3. then it redirects the user to Authorize URL + '?oauth_token=' + oauth_token
  4. user logs in on OpenStreetMap.org, the site asks them to grant permissions
  5. if callback url is supplied during registration, user is redirected to Callback URL + '?oauth_token=' + the_same_oauth_token + '&oauth_verifier=' + verifier_needed_to_retreive_access_token
  6. your application gets the same oauth_token, calls Access Token URL and receives: access_token + access_token_secret
  7. access token and its secret are used for further communication

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.

  1. Login to your account
  2. 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

  1. Register an application with application's name, redirect URIs and scope(s). Then, receive client ID and client secret. Typically, these settings are saved on the client application.
  2. When users login from the application, they must first log in to OSM to authenticate their identity by calling the Auth URL and the client application redirects to <REDIRECT_URI>?code=AUTHORIZATION_CODE where the application receives authorization code, (<REDIRECT_URI> is specified during the client application registration)
  3. An access token is requested by the client application from the Access Token URL by passing the authorization code along with authentication details, including the client secret.
  4. If the authorization is valid, the OSM API will send the access token to the application as a response. The response will look something like this {"access_token":"<ACCESS_TOKEN>","token_type":"Bearer","scope":"read_prefs write_api","created_at":1646669786}
  5. Now the application is authorized. It may use the token to access OSM APIs, limited to the scope of access, until the token expires or is revoked.

Extra notes

External resources