OAuth
Contents |
Usage for developers
You can register your Consumer application on your OpenStreetMap user page via the View my OAuth details link on the bottom of the page.
Here are the relevant URLs for reference:
- Request Token URL: http://www.openstreetmap.org/oauth/request_token
- Access Token URL: http://www.openstreetmap.org/oauth/access_token
- Authorize URL: http://www.openstreetmap.org/oauth/authorize
For development and testing purposes, the API instance on the dev server also has OAuth endpoints. Their URLs are:
- Request Token URL: http://api06.dev.openstreetmap.org/oauth/request_token
- Access Token URL: http://api06.dev.openstreetmap.org/oauth/access_token
- Authorize URL: http://api06.dev.openstreetmap.org/oauth/authorize
A few more details:
- OpenStreetMap currently implements version 1.0 (not 1.0a) of the OAuth protocol.
- Access tokens currently do not expire automatically
The basic idea
An application, for example JOSM, or a website, for example OpenCycleMap 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 users login credentials. Nifty.
Development
Oauth is live on production.
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 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.
- Login to your account
- Scroll to the bottom of your preferences page
- Click on View my OAuth details
- Click on Register your application
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 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". Don't enter the value "oob" - it is reserved for OAuth 1.0a which is not supported by OSM yet.
- Support URL - leave it empty. I have no idea what it is used for.
Basics of the protocol
- you register your application (consumer) and supply CONSUMER_KEY + CONSUMER_SECRET into it
- some user runs your application, it calls Request Token URL and recieves: oauth_token + oauth_token_secret
- then it redirects the user to Authorize URL + '?oauth_token=' + oauth_token
- user logs in on OpenStretMap.org, the site asks him to grant permissions
- if callback url is supllied during registration, user is redirected to Callback URL + '?oauth_token=' + the_same_oauth_token
- your application gets the same oauth_token, calls Access Token URL and recieves: oauth_token + oauth_token_secret
- these are used for further communication
Extra notes
- http://api.openstreetmap.org/api/0.6/user/details is xml of the logged in user
