diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/decorators.rst | 21 | ||||
-rw-r--r-- | docs/server2.rst | 98 |
2 files changed, 25 insertions, 94 deletions
diff --git a/docs/decorators.rst b/docs/decorators.rst deleted file mode 100644 index a005c85..0000000 --- a/docs/decorators.rst +++ /dev/null @@ -1,21 +0,0 @@ -========== -Decorators -========== - -Hopefully, it should be quite straightforward to port the django decorator to other web frameworks as the decorator mainly provide a means for translating the framework specific request object into uri, http_method, headers and body. - -Django OAuth 2 Decorator ------------------------- - -TODO: hows and important notes about csrf, xss, etc - -Implementing a new OAuth 2 Provider Decorator ---------------------------------------------- - -TODO: what needs to be done, what to keep an eye out for - -Extensions per web framework ----------------------------- - -If you are currently developing an extension, please let us know and we will -list it here. Or better yet, send a PR! diff --git a/docs/server2.rst b/docs/server2.rst index 3b648e6..5c50d1a 100644 --- a/docs/server2.rst +++ b/docs/server2.rst @@ -2,35 +2,23 @@ OAuth 2: Creating a Provider ============================ -Note that OAuth 2 provider is still very much a work in progress, consider it a -preview of a near future =) +OAuthLib is a dependency free library that may be used with any web +framework. That said, there are framework specific helper libraries +to make your life easier. -**1. Which framework are you using?** +- For Django there is `django-oauth-toolkit`_. +- For Flask there is `flask-oauthlib`_. - OAuthLib is a dependency free library that may be used with any web - framework. That said, there are framework specific helper decorator classes - to make your life easier. The one we will be using in this example is for - Django. For others, and information on how to create one, check out - :doc:`decorators`. +If there is no support for your favourite framework and you are interested +in providing it then you have come to the right place. OAuthLib can handle +the OAuth logic and leave you to support a few framework and setup specific +tasks such as marshalling request objects into URI, headers and body arguments +as well as provide an interface for a backend to store tokens, clients, etc. - The main purpose of these decoraters is to help marshall between the - framework specific request object and framework agnostic url, headers, body - and http method parameters. They may also be useful for making sure common - best security practices are followed. +.. _`django-oauth-toolkit`: https://github.com/evonove/django-oauth-toolkit +.. _`flask-oauthlib`: https://github.com/lepture/flask-oauthlib - Their purpose is not to be a full solution to all your needs as a provider, - for that you will want to seek out framework specific extensions building - upon OAuthLib. See the section on :doc:`decorators` for a list of - extensions. - - Relevant sections include: - - .. toctree:: - :maxdepth: 1 - - decorators - -**2. Create your datastore models** +**1. Create your datastore models** These models will represent various OAuth specific concepts. There are a few important links between them that the security of OAuth is based on. Below @@ -191,7 +179,7 @@ preview of a near future =) expires_at = django.db.models.DateTimeField() -**3. Implement a validator** +**2. Implement a validator** The majority of the work involved in implementing an OAuth 2 provider relates to mapping various validation and persistence methods to a storage @@ -232,7 +220,7 @@ preview of a near future =) security -**4. Create your composite endpoint** +**3. Create your composite endpoint** Each of the endpoints can function independently from each other, however for this example it is easier to consider them as one unit. An example of a @@ -246,7 +234,6 @@ preview of a near future =) validator = MyRequestValidator() server = WebApplicationServer(validator) - provider = OAuth2ProviderDecorator('/error', server) # See next section Relevant sections include: @@ -256,55 +243,20 @@ preview of a near future =) preconfigured_servers -**5. Decorate your endpoint views** +**4. Create your endpoint views** We are implementing support for the Authorization Code Grant and will therefore need two views for the authorization, pre- and post-authorization together with the token view. We also include an error page to redirect users to if the client supplied invalid credentials in their redirection, - for example an invalid redirect URI:: - - @login_required - @provider.pre_authorization_view - def authorize(request, client_id=None, scopes=None, state=None, - redirect_uri=None, response_type=None): - # This is the traditional authorization page - # Scopes will be the list of scopes client requested access too - # You will want to present them in a nice form where the user can - # select which scopes they allow the client to access. - return render(request, 'authorize.html', {'scopes': scopes}) - - - @login_required - @provider.post_authorization_view - def authorization_response(request): - # This is where the form submitted from authorize should end up - # Which scopes user authorized access to + extra credentials you want - # appended to the request object passed into the validator methods. - # In almost every case, you will want to include the current - # user in these extra credentials in order to associate the user with - # the authorization code or bearer token. - return request.POST.getlist['scopes'], {'user': request.user} - - - @provider.access_token_view - def token_response(request): - # Not much too do here for you, return a dict with extra credentials - # you want appended to request.credentials passed to the save_bearer_token - # method of the validator. - return {'extra': 'creds'} - - def error(request): - # The /error page users will be redirected to if there was something - # wrong with the credentials the client included when redirecting the - # user to the authorization form. Mainly if the client was invalid or - # included a malformed / invalid redirect url. - # Error and description can be found in - # GET['error'] and GET['error_description'] - return HttpResponse('Bad client! Warn user!') - - -**6. Protect your APIs using scopes** + for example an invalid redirect URI. + + The rest of this section will come soon. + +**5. Protect your APIs using scopes** + + The definition of ``protected_resource_view`` will come soon. Please see + the framework specific extensions outlined in the beginning for now. At this point you are ready to protect your API views with OAuth. Take some time to come up with a good set of scopes as they can be very powerful in @@ -330,7 +282,7 @@ preview of a near future =) # A view that has its views functionally set. return HttpResponse('pictures of cats') -**7. Let us know how it went!** +**6. Let us know how it went!** Drop a line in our `G+ community`_ or open a `GitHub issue`_ =) |