Changes between Version 20 and Version 37 of Help/Dialog/OAuthAuthorisationWizard


Ignore:
Timestamp:
(multiple changes)
Author:
(multiple changes)
Comment:
(multiple changes)

Legend:

Unmodified
Added
Removed
Modified

  • Help/Dialog/OAuthAuthorisationWizard

    v20 v37  
    1 [[TranslatedPages]]
    2 = OAuth Authorisation Wizard =
    3 [[TOC(inline)]]
     1[[TranslatedPages(outdated=The Authorization Wizard was removed from JOSM with the deprecation of OAuth 1.0a. This page still exist mainly for historical reasons.)]]
     2
     3= OAuth Authorization Wizard =
     4[[PageOutline(2-10,Table of Contents)]]
    45
    56== OAuth in a nutshell ==
    6 [http://oauth.net/ OAuth] is an open protocol to allow secure API authorisation in a simple and standard method from desktop and web applications.
     7[https://oauth.net/ OAuth] is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.
    78
    89=== Standard use case - keep your OSM password private ===
    … …  
    1011
    1112OAuth has two major advantages over Basic Authentication:
    12   1. Your OSM password doesn't have to be saved in clear text in the JOSM preferences file.
    13   2. Your OSM password has to be transferred '''only once''' over the Internet, in contrast to basic authentication where your OSM password is transferred as part of every request sent from JOSM to the OSM server.
     13 1. Your OSM password doesn't have to be saved in clear text in the JOSM preferences file.
     14 1. Your OSM password has to be transferred **only once** over the Internet on a **secure connection**, in contrast to basic authentication where your OSM password is transferred as part of every request sent from JOSM to the OSM server in clear text.
    1415
    15 {{{
    16 #!html
    17 <p style="background-color:rgb(253,255,221);padding: 10pt; border-color:rgb(128,128,128);border-style: solid; border-width: 1px;">
    18 <strong>Warning!</strong><br/>
    19 Currently, the OSM server doesn't offer a secure communication channel. Even if you use OAuth your password is therefore transferred <strong>once in clear text</strong> over the Internet. <strong>Do not use a valuable password</strong> until the OSM server provides a secure communication channel (HTTPS).
    20 </p>
    21 }}}
    22 
    23 In OAuth terminology, a JOSM user authorises JOSM to access the OSM server on the user's behalf. During the authorisation process the OSM password never needs to be entered into a JOSM dialog if the user doesn't fully trust JOSM (unless wanting to for convenience reasons [wiki:/Help/Dialog/OAuthAuthorisationWizard#FullyAutomaticAuthorisation 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 user's password and they can be revoked at any time.
     16In OAuth terminology, a JOSM user authorizes JOSM to access the OSM server on the user's behalf. During the authorization process the OSM password never needs to be entered into a JOSM dialog if the user doesn't fully trust JOSM (unless wanting to for convenience reasons [wikitr:/Help/Dialog/OAuthAuthorisationWizard#FullyAutomaticAuthorisation 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 user's password and they can be revoked at any time.
    2417
    2518=== Advanced use case - delegate access to other mappers ===
    … …  
    2922
    3023
    31 == The OAuth Authorisation Wizard ==
     24== The OAuth Authorization Wizard ==
     25The Oauth authorization wizard is located in the preferences under [wikitr:/Help/Preferences/Connection OSM Server preferences].
    3226
    33 === What does authentication/authorisation mean? ===
    34 When you upload geodata to the OSM server you have to tell the server who you are. The OSM server will '''identify''' every uploading mapper by asking for an OSM username. The OSM server furthermore needs to '''authenticate''' this identity, i.e. to reliably determine whether the mapper is indeed the claimed user. For this purpose, it asks for a password in addition to the username. The server's assumption is that whoever knows the secret password for username xyz is reliably authenticated to ''be'' xyz. A mapper logged in with an authenticated username and password is entitled to run a broad range of operations on the server. The mapper is '''authorised''' to upload data, to create changesets, to close changesets, to upload GPS traces, to read and changes personal preferences on the server, to invite others as friends, to send emails to other accounts, etc. Currently, it isn't possible to create an OSM account with an OSM username and a password with restricted rights, i.e. an account that would only be able to upload GPS traces, but not map data. Whoever has successfully '''authenticated''' with an OSM username and an OSM password is '''fully authorised''' to do everything an OSM user can normally do on the server.
     27=== What does authentication/authorization mean? ===
     28When you upload geodata to the OSM server you have to tell the server who you are. The OSM server will **identify** every uploading mapper by asking for an OSM username. The OSM server furthermore needs to **authenticate** this identity, i.e. to reliably determine whether the mapper is indeed the claimed user. For this purpose, it asks for a password in addition to the username. The server's assumption is that whoever knows the secret password for username xyz is reliably authenticated to ''be'' xyz. A mapper logged in with an authenticated username and password is entitled to run a broad range of operations on the server. The mapper is ***authorized** to upload data, to create changesets, to close changesets, to upload GPS traces, to read and changes personal preferences on the server, to invite others as friends, to send emails to other accounts, etc. Currently, it isn't possible to create an OSM account with an OSM username and a password with restricted rights, i.e. an account that would only be able to upload GPS traces, but not map data. Whoever has successfully **authenticated** with an OSM username and an OSM password is **fully authorized** to do everything an OSM user can normally do on the server.
    3529
    36 This is where OAuth comes into play: OAuth allows you to '''authorise''' somebody else to act in a restricted way on your behalf. Instead of giving away your OSM username and your OSM password, which would fully entitle the recipient to act on your behalf at the OSM server, you only give away a "ticket" on which the granted rights are listed. This ticket is called an '''Access Token'''. Restrictions applied to an Access Token include:
     30This is where OAuth comes into play: OAuth allows you to **authorize** somebody else to act in a restricted way on your behalf. Instead of giving away your OSM username and your OSM password, which would fully entitle the recipient to act on your behalf at the OSM server, you only give away a "ticket" on which the granted rights are listed. This ticket is called an **Access Token**. Restrictions applied to an Access Token include:
    3731  * an Access Token is only valid for a specific client (called a Consumer in OAuth terminology), i.e. only for JOSM, but not for OpenStreetBugs
    3832  * an Access Token is only valid for specific operations, i.e. only for uploading GPS traces, but not for uploading map data
    3933  * an Access Token could only be valid for a certain time, i.e. only today, but this is not yet supported by the OSM server
    4034
    41 In addition to username/password pairs, the OSM server also accepts OAuth Access Tokens to authenticate and authorise a user. More specifically, it accepts requests ''signed with such a token'', but this is beyond of the scope of this online help.
     35In addition to username/password pairs, the OSM server also accepts OAuth Access Tokens to authenticate and authorize a user. More specifically, it accepts requests ''signed with such a token'', but this is beyond of the scope of this online help.
    4236
    43 The OAuth Authorisation Wizard allows you to receive a valid OAuth Access Token, provided that you have an OSM username and OSM password, or to enter and use an OAuth Access Token in JOSM, provided that you got one from somebody else who has an OSM username and an OSM password.
     37The OAuth Authorization Wizard allows you to receive a valid OAuth Access Token, provided that you have an OSM username and OSM password, or to enter and use an OAuth Access Token in JOSM, provided that you got one from somebody else who has an OSM username and an OSM password.
    4438
    45 === Fully automatic authorisation process ===
     39=== Fully automatic authorization process ===#FullyAutomaticAuthorisation
    4640The easiest way to get an Access Token is to let JOSM fully automatically retrieve one from the OSM server.
    4741
    48  1. '''Step 1/3'''  - Open the preferences dialog
     421. **Step 1/3**  - Open the preferences dialog
    4943
    50     Click on the '''Preferences''' button in the toolbar. In the dialog, select the '''Connection Setting''' tab.
     44    Click on the **Preferences** button in the toolbar. In the dialog, select the [wikitr:/Help/Preferences/Connection Connection Setting] tab.
     45
     462. **Step 2/3**  - Get the Access Token
     47
     48 Enter your OSM username and your OSM password and click on **Authorize now**.
    5149   
     50 [[Image(fully-authomatic-1.png,link=)]]
    5251
    53  2. '''Step 2/3'''  - Get the Access Token 
     523. **Step 3/3** - Accept the Access Token
    5453
    55     Enter your OSM username and your OSM password and click on '''Authorise now'''.
     54 JOSM displays the retrieved Access Token.
    5655   
    57     [[Image(fully-authomatic-1.png)]]
     56 [[Image(fully-authomatic-2.png,link=)]]
    5857
    59  3. '''Step 3/3''' - Accept the Access Token
    60 
    61     JOSM displays the retrieved Access Token. Click on '''Accept Access Token''' to accept it.
    62    
    63     [[Image(fully-authomatic-2.png)]]
     58* Deselect the checkbox Save to preferences if you don't want to save the Access Token in the JOSM preferences. If you don't save it the Access Token will be lost when you close JOSM. If you later startup JOSM again you will have to retrieve a new Access Token to work with OAuth based authentication again.
     59* Click on **Test Access Token** to test the token
     60* Click on **Accept Access Token** to accept it.
    6461
    6562==== Restricting the granted privileges ====
    66 When JOSM fully-automatically requests and authorises an Access Token, it grants it five privileges:
    67   * the right to upload data to the OSM server
    68   * the right to upload GPS traces to the OSM server
    69   * the right to download private GPS traces from the OSM server
    70   * the right to read the preferences stored on the OSM server
    71   * the right to write preferences stored on the OSM server
     63When JOSM fully-automatically requests and authorizes an Access Token, it grants it six privileges:
     64* the right to upload data to the OSM server
     65* the right to upload GPS traces to the OSM server
     66* the right to download private GPS traces from the OSM server
     67* the right to read the preferences stored on the OSM server
     68* the right to write preferences stored on the OSM server
     69* the right to modify notes stored on the OSM server
    7270
    7371These are the default settings. If you want to restrict the granted privileges:
    7472
    75   1. Click the tab '''Granted rights'''
    76   2. Deselect each privilege which should not be granted to the requested Access Token
     731. Click the tab **Granted rights**
     741. Deselect each privilege which should not be granted to the requested Access Token
    7775
    78     [[Image(fully-authomatic-privileges.png)]]
     76[[Image(fully-authomatic-privileges.png,link=)]]
    7977
    8078==== Advanced OAuth parameters ==== #FullyAutomaticAdvanced
    81 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
    82  * 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.
    83  * in order to use it on a different than the standard OSM server. For instance, this allows users to use OAuth with an OSM development server or with a local installation of the OSM server application.
     79When JOSM fully-automatically requests and authorises an [https://oauth.net/core/1.0/#anchor3 Access Token], it uses default values for the OAuth parameters. Advanced users may want to change these parameters
     80* 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.
     81* in order to use it on a different than the standard OSM server. For instance, this allows users to use OAuth with an OSM development server or with a local installation of the OSM server application.
    8482
    8583In order to edit the Advanced OAuth parameters
    8684
    87   1. Click the tab '''Advanced OAuth parameters'''
    88   2. Deselect the checkbox '''Use default settings'''
    89   3. Enter your values for the five OAuth parameters
     85 1. Click the tab **Advanced OAuth parameters**
     86 1. Deselect the checkbox **Use default settings**
     87 1. Enter your values for the seven OAuth parameters
    9088
    91       [[Image(fully-automatic-advanced.png)]]
     89[[Image(fully-automatic-advanced.png,link=)]]
    9290
    93 === Semi-automatic authorisation process ===
    94 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 a user which - for whatever reason - never wants to use their OSM password outside of the OSM website. Note however, that the semi-automatic process is '''not''' significantly more secure than the fully automatic process. Your OSM password will be transferred in clear-text over the Internet, too, because the OSM website doesn't currently provide a login page protected by HTTPS. The fully automatic process runs exactly the same steps that would run manually in the semi-automatic process, just without your intervention.
     91=== Semi-automatic authorization process ===#Semi-automaticauthorisationprocess
     92You 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 authorize 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 a user which - for whatever reason - never wants to use their OSM password outside of the secure login page of the OSM website. The fully automatic process runs exactly the same steps that would run manually in the semi-automatic process, just without your intervention.
     93
     941. **Step 1/3** - Get the Request Token
     95
     96 Click on **Retrieve Request Token** to retrieve an OAuth Request Token.
     97   
     98 [[Image(semi-automatic-step-1.png,link=)]]
     99
     1002. **Step 2/3** - Authorize the Request Token in an external browser
     101
     102 JOSM now launches an external browser with the OSM website. Please login and follow the instructions. Then switch back to the OAuth Authorization Wizard and click on **Retrieve Access Token**.
     103   
     104 [[Image(semi-automatic-step-2.png,link=)]]
     105
     1063. **Step 3/3** - Accept the Access Token
     107
     108 JOSM displays the retrieved Access Token. Click on **Accept Access Token** to accept it.
     109   
     110 [[Image(semi-automatic-step-3.png,link=)]]
    95111
    96112
    97  1. '''Step 1/3''' - Get the Request Token
    98 
    99    Click on '''Retrieve Request Token''' to retrieve an OAuth Request Token.
    100    
    101     [[Image(semi-automatic-step-1.png)]]
    102 
    103  2. '''Step 2/3''' - Authorise the Request Token in an external browser
    104 
    105     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'''.
    106    
    107     [[Image(semi-automatic-step-2.png)]]
    108 
    109  2. '''Step 3/3''' - Accept the Access Token
    110 
    111     JOSM displays the retrieved Access Token. Click on '''Accept Access Token''' to accept it.
    112    
    113     [[Image(semi-automatic-step-3.png)]]
    114 
    115 
    116 ==== Advanced OAuth parameters ====
    117 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
    118  * 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.
    119  * in order to use it on a different than the standard OSM server. For instance, this allows users to use OAuth with an OSM development server or with a local installation of the OSM server application.
     113==== Advanced OAuth parameters ==== #AdvancedOAuthparameters
     114When JOSM semi-automatically requests and authorizes an Access Token, it uses default values for the OAuth parameters. Advanced users may want to change these parameters:
     115* 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.
     116* in order to use it on a different than the standard OSM server. For instance, this allows users to use OAuth with an OSM development server or with a local installation of the OSM server application.
    120117
    121118In order to edit the Advanced OAuth parameters
    122119
    123   1. Select the checkbox '''Display Advanced OAuth Parameters'''
    124   2. Enter your values for the five OAuth parameters
     1201. Select the checkbox **Display Advanced OAuth Parameters**
     1211. Enter your values for the seven OAuth parameters
    125122
    126   [[Image(semi-automatic-advanced.png)]]
     123[[Image(semi-automatic-advanced.png,link=)]]
    127124
    128 === Manual authorisation process ===
    129 The manual authorisation process allows you to enter an arbitrary Access Token. You can use this process
     125=== Manual authorization process ===
     126The manual authorization process allows you to enter an arbitrary Access Token. You can use this process:
    130127
    131   * to enter an Access Token you have kept in a secure place, for instance in a secure store for credentials
    132   * to enter an Access Token you have received from somebody else, for instance from another mapper who granted you restricted account access
     128* to enter an Access Token you have kept in a secure place, for instance in a secure store for credentials
     129* to enter an Access Token you have received from somebody else, for instance from another mapper who granted you restricted account access
    133130
    134  1. '''Step 1/1'''  - Enter the Access Token and accept it
     1311. **Step 1/1**  - Enter the Access Token and accept it
    135132
    136    Enter the Access Token and click on '''Accept Access Token'''.
     133 Enter the Access Token and click on **Accept Access Token**.
    137134
    138   [[Image(manual.png)]]
     135 [[Image(manual.png,link=)]]
    139136 
    140137
    141138==== Advanced OAuth parameters ====
    142  * See [wiki:/Help/Dialog/OAuthAuthorisationWizard#FullyAutomaticAdvanced advanced preferences in the fully automatic process].
     139* See [wikitr:/Help/Dialog/OAuthAuthorisationWizard#FullyAutomaticAdvanced advanced preferences in the fully automatic process].
    143140
     141== Troubleshooting ==
     142* If you are working on a university or corporate network, a firewall may prevent the OAuth authentication request. \\
     143 Please check the corresponding connection with your network engineer.
     144----
     145Back to [wikitr:/Help/Preferences/Connection OSM Server preferences] \\
     146Back to [wikitr:/Help Main Help]