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


Ignore:
Timestamp:
2010-01-19T22:47:58+01:00 (16 years ago)
Author:
pinkduck
Comment:

Proof read

Legend:

Unmodified
Added
Removed
Modified

  • Help/Dialog/OAuthAuthorisationWizard

    v19 v20  
    44
    55== OAuth in a nutshell ==
    6 [http://oauth.net/ OAuth] is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.
     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.
    77
    88=== Standard use case - keep your OSM password private ===
    9 The standard use case in OSM for OAuth is to keep your OSM password more private than with Basic Authentication.
     9The standard use case in OSM is for OAuth to keep your OSM password more private than with Basic Authentication.
    1010
    1111OAuth has two major advantages over Basic Authentication:
    1212  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 trasferred as part of every request sent from JOSM to the OSM server.
     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.
    1414
    1515{{{
    … …  
    2121}}}
    2222
    23 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 [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 users password and they can be revoked at any time.
     23In 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.
    2424
    2525=== Advanced use case - delegate access to other mappers ===
    2626A 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.
    2727
    28 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.
     28Example: 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 it to the privilege "Download my private GPS traces". The mapper would then send an email with the Access Token to Mapper B. B can enter the Access Token in JOSM and is now allowed to download A's private GPS traces from the OSM server. B wouldn't be allowed to upload date on A's behalf, though, and doesn't know A's OSM password. At any time, A can revoke the Access Token issued to B.
    2929
    3030
    3131== The OAuth Authorisation Wizard ==
    3232
    33 === What does authentication/authorization mean? ===
    34 When you upload geodata to the OSM server you have to tell the server who you are. The OSM server asks every uploading mapper to '''identify''' himself with an OSM username. The OSM server furthermore needs to '''authenticate''' this identity, i.e. to reliably determine whether the mapper is indeed who he or she claims to be. For this purpose, it asks for a password in addition to the username. The servers assumption is, that whoever knows the secret password for username xyz is reliably authenticated to ''be'' xyz. A mapper logging in with his username and password is entitled to run a broad range of operations on the server. He or she 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 which 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 do on the server.
     33=== What does authentication/authorisation mean? ===
     34When 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.
    3535
    3636This 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:
    … …  
    4141In 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.
    4242
    43 The OAuth Authorisation Wizard supports you to receive a valid OAuth Access Token, provided that you have an OSM username and an 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.
     43The 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.
    4444
    45 === Fully automatic authorization process ===
     45=== Fully automatic authorisation process ===
    4646The easiest way to get an Access Token is to let JOSM fully automatically retrieve one from the OSM server.
    4747
    … …  
    7171  * the right to write preferences stored on the OSM server
    7272
    73 These are the default settings. If you want to restrict the granted privileges
     73These are the default settings. If you want to restrict the granted privileges:
    7474
    7575  1. Click the tab '''Granted rights'''
    … …  
    8181When 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
    8282 * 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 a OSM development server or with a local installation of the OSM server application.
     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.
    8484
    8585In order to edit the Advanced OAuth parameters
    … …  
    9191      [[Image(fully-automatic-advanced.png)]]
    9292
    93 === Semi-automatic authorization 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 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.
     93=== Semi-automatic authorisation process ===
     94You 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.
    9595
    9696
    97  1. '''Step 1/3'''  - Get the Request Token
     97 1. '''Step 1/3''' - Get the Request Token
    9898
    9999   Click on '''Retrieve Request Token''' to retrieve an OAuth Request Token.
    … …  
    117117When 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
    118118 * 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 a OSM development server or with a local installation of the OSM server application.
     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.
    120120
    121121In order to edit the Advanced OAuth parameters
    … …  
    126126  [[Image(semi-automatic-advanced.png)]]
    127127
    128 === Manual authorization process ===
     128=== Manual authorisation process ===
    129129The manual authorisation process allows you to enter an arbitrary Access Token. You can use this process
    130130
    131131  * 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 access to his OSM account
     132  * to enter an Access Token you have received from somebody else, for instance from another mapper who granted you restricted account access
    133133
    134134 1. '''Step 1/1'''  - Enter the Access Token and accept it