Skip to content

Doc: Replace heroku service with postman in tutorial part 1 #1251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Feb 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AUTHORS
Original file line number Diff line number Diff line change
Expand Up @@ -90,3 +90,4 @@ Víðir Valberg Guðmundsson
Will Beaufoy
pySilver
Łukasz Skarżyński
Marcus Sonestedt
40 changes: 26 additions & 14 deletions docs/tutorial/tutorial_01.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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*.
Expand All @@ -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 <http://django-oauth-toolkit.herokuapp.com/consumer/>`_ 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 <http://django-oauth-toolkit.herokuapp.com/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
+++++++++++++++++++++++++
Expand All @@ -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`.

Expand Down