Changes between Version 33 and Version 36 of Help/Dialog/OAuthAuthorisationWizard
- Timestamp:
- (multiple changes)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Help/Dialog/OAuthAuthorisationWizard
v33 v36 4 4 5 5 == 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.6 [https://oauth.net/ OAuth] is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications. 7 7 8 8 === Standard use case - keep your OSM password private === … … 11 11 OAuth has two major advantages over Basic Authentication: 12 12 1. Your OSM password doesn't have to be saved in clear text in the JOSM preferences file. 13 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.13 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. 14 14 15 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.15 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 [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. 16 16 17 17 === Advanced use case - delegate access to other mappers === … … 22 22 23 23 == The OAuth Authorisation Wizard == 24 The Oauth authorisation wizard is located in the preferences under [ Preferences/Connection Connection settings].25 === What does authentication/authori sation mean? ===26 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.24 The Oauth authorisation wizard is located in the preferences under [wikitr:/Help/Preferences/Connection Connection settings]. 25 === What does authentication/authorization mean? === 26 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 ***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. 27 27 28 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:28 This 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: 29 29 * 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 30 30 * an Access Token is only valid for specific operations, i.e. only for uploading GPS traces, but not for uploading map data … … 33 33 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. 34 34 35 The OAuth Authori sation 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.35 The 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. 36 36 37 === Fully automatic authori sation process ===#FullyAutomaticAuthorisation37 === Fully automatic authorization process ===#FullyAutomaticAuthorisation 38 38 The easiest way to get an Access Token is to let JOSM fully automatically retrieve one from the OSM server. 39 39 40 1. '''Step 1/3'''- Open the preferences dialog40 1. **Step 1/3** - Open the preferences dialog 41 41 42 Click on the '''Preferences''' button in the toolbar. In the dialog, select the [wiki:Help/Preferences/Connection Connection Setting] tab.42 Click on the **Preferences** button in the toolbar. In the dialog, select the [wikitr:/Help/Preferences/Connection Connection Setting] tab. 43 43 44 2. '''Step 2/3'''- Get the Access Token44 2. **Step 2/3** - Get the Access Token 45 45 46 Enter your OSM username and your OSM password and click on '''Authorise now'''.46 Enter your OSM username and your OSM password and click on **Authorize now**. 47 47 48 [[Image(fully-authomatic-1.png )]]48 [[Image(fully-authomatic-1.png,link=)]] 49 49 50 3. '''Step 3/3'''- Accept the Access Token50 3. **Step 3/3** - Accept the Access Token 51 51 52 52 JOSM displays the retrieved Access Token. 53 53 54 [[Image(fully-authomatic-2.png )]]54 [[Image(fully-authomatic-2.png,link=)]] 55 55 56 56 * 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. 57 * Click on ''Test Access Token"to test the token58 * Click on '''Accept Access Token'''to accept it.57 * Click on **Test Access Token** to test the token 58 * Click on **Accept Access Token** to accept it. 59 59 60 60 ==== Restricting the granted privileges ==== 61 When JOSM fully-automatically requests and authori ses an Access Token, it grants it fiveprivileges:61 When JOSM fully-automatically requests and authorizes an Access Token, it grants it six privileges: 62 62 * the right to upload data to the OSM server 63 63 * the right to upload GPS traces to the OSM server … … 65 65 * the right to read the preferences stored on the OSM server 66 66 * the right to write preferences stored on the OSM server 67 * the right to modify notes stored on the OSM server 67 68 68 69 These are the default settings. If you want to restrict the granted privileges: 69 70 70 1. Click the tab '''Granted rights'''71 1. Click the tab **Granted rights** 71 72 1. Deselect each privilege which should not be granted to the requested Access Token 72 73 73 [[Image(fully-authomatic-privileges.png )]]74 [[Image(fully-authomatic-privileges.png,link=)]] 74 75 75 76 ==== Advanced OAuth parameters ==== #FullyAutomaticAdvanced … … 80 81 In order to edit the Advanced OAuth parameters 81 82 82 1. Click the tab '''Advanced OAuth parameters'''83 1. Deselect the checkbox '''Use default settings'''84 1. Enter your values for the fiveOAuth parameters83 1. Click the tab **Advanced OAuth parameters** 84 1. Deselect the checkbox **Use default settings** 85 1. Enter your values for the seven OAuth parameters 85 86 86 [[Image(fully-automatic-advanced.png )]]87 [[Image(fully-automatic-advanced.png,link=)]] 87 88 88 === Semi-automatic authori sation process ===#Semi-automaticauthorisationprocess89 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 authori se 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.89 === Semi-automatic authorization process ===#Semi-automaticauthorisationprocess 90 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 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. 90 91 92 1. **Step 1/3** - Get the Request Token 91 93 92 1. '''Step 1/3''' - Get the Request Token 94 Click on **Retrieve Request Token** to retrieve an OAuth Request Token. 95 96 [[Image(semi-automatic-step-1.png,link=)]] 93 97 94 Click on '''Retrieve Request Token''' to retrieve an OAuth Request Token. 98 2. **Step 2/3** - Authorise the Request Token in an external browser 99 100 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**. 95 101 96 [[Image(semi-automatic-step- 1.png)]]102 [[Image(semi-automatic-step-2.png,link=)]] 97 103 98 2. '''Step 2/3''' - Authorise the Request Token in an external browser 104 3. **Step 3/3** - Accept the Access Token 99 105 100 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 JOSM displays the retrieved Access Token. Click on **Accept Access Token** to accept it. 101 107 102 [[Image(semi-automatic-step-2.png)]] 103 104 3. '''Step 3/3''' - Accept the Access Token 105 106 JOSM displays the retrieved Access Token. Click on '''Accept Access Token''' to accept it. 107 108 [[Image(semi-automatic-step-3.png)]] 108 [[Image(semi-automatic-step-3.png,link=)]] 109 109 110 110 111 111 ==== Advanced OAuth parameters ==== #AdvancedOAuthparameters 112 When JOSM semi-automatically requests and authori ses an Access Token, it uses default values for the OAuth parameters. Advanced users may want to change these parameters112 When 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: 113 113 * 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. 114 114 * 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. … … 116 116 In order to edit the Advanced OAuth parameters 117 117 118 1. Select the checkbox '''Display Advanced OAuth Parameters''' 119 1. Enter your values for the fiveOAuth parameters118 1. Select the checkbox **Display Advanced OAuth Parameters** 119 1. Enter your values for the seven OAuth parameters 120 120 121 [[Image(semi-automatic-advanced.png )]]121 [[Image(semi-automatic-advanced.png,link=)]] 122 122 123 === Manual authori sation process ===124 The manual authori sation process allows you to enter an arbitrary Access Token. You can use this process123 === Manual authorization process === 124 The manual authorization process allows you to enter an arbitrary Access Token. You can use this process: 125 125 126 126 * to enter an Access Token you have kept in a secure place, for instance in a secure store for credentials 127 127 * to enter an Access Token you have received from somebody else, for instance from another mapper who granted you restricted account access 128 128 129 1. '''Step 1/1'''- Enter the Access Token and accept it129 1. **Step 1/1** - Enter the Access Token and accept it 130 130 131 Enter the Access Token and click on '''Accept Access Token'''.131 Enter the Access Token and click on **Accept Access Token**. 132 132 133 [[Image(manual.png )]]133 [[Image(manual.png,link=)]] 134 134 135 135 136 136 ==== Advanced OAuth parameters ==== 137 * See [wiki :/Help/Dialog/OAuthAuthorisationWizard#FullyAutomaticAdvanced advanced preferences in the fully automatic process].137 * See [wikitr:/Help/Dialog/OAuthAuthorisationWizard#FullyAutomaticAdvanced advanced preferences in the fully automatic process]. 138 138 139 139 == Troubleshooting == 140 * If you are working on a university or corporate network, a firewall may prevent the OAuth authenti fication request.[[BR]]140 * If you are working on a university or corporate network, a firewall may prevent the OAuth authentication request. \\ 141 141 Please check the corresponding connection with your network engineer. 142 142 ---- 143 Back to [wiki :/Help/Preferences/Connection Connection settings][[Br]]144 Back to [wiki :Help Main Help]143 Back to [wikitr:/Help/Preferences/Connection Connection settings] \\ 144 Back to [wikitr:/Help Main Help]
