OAuth Authorisation Wizard

This is work in progress which is neither available in latest nor in tested. The corresponding features will be available shortly. Please check the JOSM Message of the Day.

TOC(inline)

OAuth in a nutshell

​OAuth is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.

Standard use case - keep your OSM password private

The standard use case in OSM for OAuth is to keep your OSM password more private than with Basic Authentication.

OAuth has two major advantages over Basic Authentication:

1. Your OSM password doesn't have to be saved in clear text in the JOSM preferences file.
2. Your OSM password has to be transferred only once over the Internet, in contrast to basic authentication where your OSM password is trasferred as part of every request sent from JOSM to the OSM server.

Warning!
Currently, the OSM server doesn't offer a secure communication channel. Even if you use OAuth your password is therefore transferred once in clear text over the Internet. Do not use a valuable password until the OSM server provides a secure communication channel (HTTPS).

In OAuth terminology, a JOSM user authorises JOSM to access the OSM server on his behalf. During the authorisation process he never has to enter his OSM password into a JOSM dialog if he or she doesn't fully trust JOSM (unless he wants to for convenience reasons see here). Rather, the OSM server issues an Access Token which JOSM presents to the OSM server when it uploads data on behalf of the user. Access Tokens don't reveal the users password and they can be revoked at any time.

Advanced use case - delegate access to other mappers

A more advanced use case for OAuth is to delegate access to your OSM account to other mappers. OAuth allows you to grant another user restricted access to your account if necessary.

Example: Mapper A can grant mapper B the right to download its private GPS traces from the OSM website. Mapper A would generate an OAuth Access Token and restrict to the privilege "Download my private GPS traces". He would then send an email with the Access Token to mapper B. B can enter the Access Token in JOSM and he is now allowed to download A's private GPS traces from the OSM server. He wouldn't be allowed to upload date on A's behalf, though, and he doesn't know A's OSM password. At any time, A can revoke the Access Token issued for B.

The OAuth Authorisation Wizard

What does authorization mean?

Fully automatic authorization process

The easiest way to get an Access Token is to let JOSM fully automatically retrieve one from the OSM server.

1. Step 1/2 - Get the Access Token

Enter your OSM username and your OSM password and click on Authorise now.

2. Step 2/2 - Accept the Access Token

JOSM displays the retrieved Access Token. Click on Accept Access Token to accept it.

Restricting the granted privileges

When JOSM fully-automatically requests and authorises an Access Token, it grants it five privileges:

• the right to upload data to the OSM server
• the right to upload GPS traces to the OSM server
• the right to download private GPS traces from the OSM server
• the right to read the preferences stored on the OSM server
• the right to write preferences stored on the OSM server

These are the default settings. If you want to restrict the granted privileges

1. Click the tab Granted rights
2. Unselect each privilege which should not be granted to the requested Access Token

Advanced OAuth parameters

When JOSM fully-automatically requests and authorises an Access Token, it uses default values for the OAuth parameters. Advanced users may want to change these parameters

• in order to use a different Consumer Token (consisting of a Consumer Key and a Consumer Secret). This allows you to create your own Consumer Token for JOSM and then use it in JOSM.
• in order to use it on a different than the standard OSM server. For instance, this allows users to use OAuth with a OSM development server or with a local installation of the OSM server application.

In order to edit the Advanced OAuth parameters

1. Click the tab Advanced OAuth parameters
2. Unselect the checkbox Use default settings
3. Enter your values for the five OAuth parameters

Semi-automatic authorization process

You can also retrieve an Access Token semi-automatically. If you use this process you have to use both dialogs in JOSM and the OSM website launched in an external browser to create and authorise the Access Token. In contrast to the fully automatic process you never have to enter your OSM username or your OSM password into a JOSM dialog. This process is therefore suitable for user which - for whatever reason - never want to use their OSM password outside of the OSM website. Note however, that the semi-automatic process is not significantely more secure than the fully automatic process. Your OSM password will be transferred in cleartext over the Internet, too, because the OSM website currently doesn't provide a login page protected by HTTPS. The fully automatic process runs exactly the same steps you run manually in the semi-automatic process, just without your intervention.

1. Step 1/3 - Get the Request Token

Click on Retrieve Request Token to retrieve an OAuth Request Token.

2. Step 2/3 - Authorise the Request Token in an external browser

JOSM now launches an external browser with the OSM website. Please login and follow the instructions. Then switch back to the OAuth Authorisation Wizard and click on Retrieve Access Token.

2. Step 3/3 - Accept the Access Token

JOSM displays the retrieved Access Token. Click on Accept Access Token to accept it.

Advanced OAuth parameters

When JOSM semi-automatically requests and authorises an Access Token, it uses default values for the OAuth parameters. Advanced users may want to change these parameters

• in order to use a different Consumer Token (consisting of a Consumer Key and a Consumer Secret). This allows you to create your own Consumer Token for JOSM and then use it in JOSM.
• in order to use it on a different than the standard OSM server. For instance, this allows users to use OAuth with a OSM development server or with a local installation of the OSM server application.

In order to edit the Advanced OAuth parameters

1. Select the checkbox Display Advanced OAuth Parameters
2. Enter your values for the five OAuth parameters

Manual authorization process