diff --git a/AUTHORS b/AUTHORS index 9bd1ea3fc..8914badcc 100644 --- a/AUTHORS +++ b/AUTHORS @@ -90,3 +90,4 @@ Víðir Valberg Guðmundsson Will Beaufoy pySilver Łukasz Skarżyński +Marcus Sonestedt diff --git a/docs/tutorial/tutorial_01.rst b/docs/tutorial/tutorial_01.rst index f0b8cb3ed..1d53de78a 100644 --- a/docs/tutorial/tutorial_01.rst +++ b/docs/tutorial/tutorial_01.rst @@ -89,7 +89,7 @@ point your browser to http://localhost:8000/o/applications/ and add an Applicati * `Redirect uris`: Applications must register at least one redirection endpoint before using the authorization endpoint. The :term:`Authorization Server` will deliver the access token to the client only if the client specifies one of the verified redirection uris. For this tutorial, paste verbatim the value - `http://django-oauth-toolkit.herokuapp.com/consumer/exchange/` + `https://www.getpostman.com/oauth2/callback` * `Client type`: this value affects the security level at which some communications between the client application and the authorization server are performed. For this tutorial choose *Confidential*. @@ -105,17 +105,28 @@ process we'll explain shortly) Test Your Authorization Server ------------------------------ Your authorization server is ready and can begin issuing access tokens. To test the process you need an OAuth2 -consumer; if you are familiar enough with OAuth2, you can use curl, requests, or anything that speaks http. For the rest -of us, there is a `consumer service `_ deployed on Heroku to test -your provider. +consumer; if you are familiar enough with OAuth2, you can use curl, requests, or anything that speaks http. + +For this tutorial, we suggest using [Postman](https://www.postman.com/downloads/) : + +Open up the Authorization tab under a request and, for this tutorial, set the fields as follows: + +* Grant type: `Authorization code (With PKCE)` +* Callback URL: `https://www.getpostman.com/oauth2/callback` <- need to be in your added application +* Authorize using browser: leave unchecked +* Auth URL: `http://localhost:8000/o/authorize/` +* Access Token URL: `http://localhost:8000/o/token/` +* Client ID: `random string for this app, as generated` +* Client Secret: `random string for this app, as generated` <- must be before hashing, should not begin with 'pbkdf2_sha256' or similar + +The rest can be left to their (mostly empty) default values. Build an Authorization Link for Your Users ++++++++++++++++++++++++++++++++++++++++++ Authorizing an application to access OAuth2 protected data in an :term:`Authorization Code` flow is always initiated -by the user. Your application can prompt users to click a special link to start the process. Go to the -`Consumer `_ page and complete the form by filling in your -application's details obtained from the steps in this tutorial. Submit the form, and you'll receive a link your users can -use to access the authorization page. +by the user. Your application can prompt users to click a special link to start the process. + +Here, we click "Get New Access Token" in postman, which should open your browser and show django's login. Authorize the Application +++++++++++++++++++++++++ @@ -125,18 +136,19 @@ page is login protected by django-oauth-toolkit. Login, then you should see the her authorization to the client application. Flag the *Allow* checkbox and click *Authorize*, you will be redirected again to the consumer service. -__ loginTemplate_ +Possible errors: -If you are not redirected to the correct page after logging in successfully, -you probably need to `setup your login template correctly`__. +* loginTemplate: If you are not redirected to the correct page after logging in successfully, you probably need to `setup your login template correctly`__. +* invalid client: client id and client secret needs to be correct. Secret cannot be copied from Django admin after creation. + (but you can reset it by pasting the same random string into Django admin and into Postman, to avoid recreating the app) +* invalid callback url: Add the postman link into your app in Django admin. +* invalid_request: Use "Authorization Code (With PCKE)" from postman or disable PKCE in Django Exchange the token ++++++++++++++++++ At this point your authorization server redirected the user to a special page on the consumer passing in an :term:`Authorization Code`, a special token the consumer will use to obtain the final access token. -This operation is usually done automatically by the client application during the request/response cycle, but we cannot -make a POST request from Heroku to your localhost, so we proceed manually with this step. Fill the form with the -missing data and click *Submit*. + If everything is ok, you will be routed to another page showing your access token, the token type, its lifetime and the :term:`Refresh Token`.