diff options
author | Jonathan Huot <jonathan.huot@gmail.com> | 2019-10-28 18:09:27 +0100 |
---|---|---|
committer | Jonathan Huot <jonathan.huot@gmail.com> | 2019-10-28 18:09:27 +0100 |
commit | 1645cd3f0f3142384b76b402859474a6d0cd68e7 (patch) | |
tree | f479dfe250e9c5f8bd45693cdfb35c6d6fb3bd0e | |
parent | f68ec220d9ff5ec8e710d3e916318dad0de3e2d2 (diff) | |
download | oauthlib-1645cd3f0f3142384b76b402859474a6d0cd68e7.tar.gz |
Improve clarity around howto define a grant.
-rw-r--r-- | docs/oauth2/grants/custom_grant.rst | 67 |
1 files changed, 41 insertions, 26 deletions
diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst index 7408cf6..b47131c 100644 --- a/docs/oauth2/grants/custom_grant.rst +++ b/docs/oauth2/grants/custom_grant.rst @@ -7,10 +7,9 @@ which is in an early draft, or implement a grant provided by a specific OAuth2.0 Authorization Server documentation but not provided by oauthlib. For information, any grant types with a clear specification can be integrated in oauthlib, just make a PR for that -!. See :doc:`how to contribute here </contributing>`. +! See :doc:`how to contribute here </contributing>`. -Please find below an example of how to create a new grant and use it -in an endpoint: +Please find how to create a new grant and use it in an endpoint: .. contents:: Tutorial Contents :depth: 3 @@ -18,46 +17,62 @@ in an endpoint: 1. Define your Grant Type ------------------------- - The heart of your code is done by subclassing -:py:class:`oauthlib.oauth2.rfc6749.grant_types.base.GrantTypeBase`. -If you want to use it in the Authorize endpoint, you will have to -implement `create_authorization_response`, if in the Token endpoint, -implement `create_token_response`. +:py:class:`GrantTypeBase`. If you want to use it in the Authorize +endpoint, you will have to implement +:py:meth:`create_authorization_response`, if you want to use the Token +endpoint, implement :py:meth:`create_token_response`. You can also +implement both. + +2. Implement the grant +---------------------- +Inside the method's implementation, you will have to: +* add validations of the request (syntax, parameters, ...) +* call and orchestrate one or multiple Request Validators calls +* generate and return HTTP response -2. Associate it with Endpoints +You can define new Request Validator methods if needed, or reuse the +existing ones. + +3. Associate it with Endpoints ------------------------------ -Then, once declared, you have to create an instance of your grant and -add it to your -endpoint. I.e. :py:class:`oauthlib.oauth2.rfc6749.endpoints.AuthorizationEndpoint` -or :py:class:`oauthlib.oauth2.rfc6749.endpoints.TokenEndpoint`. You -can see concrete examples in -:py:class:`oauthlib.oauth2.rfc6749.endpoints.pre_configured.Server` -for examples. - -3. Example +Then, once implemented, you have to instanciate the grant object and +bind it to your endpoint. Either :py:class:`AuthorizationEndpoint`, +:py:class:`TokenEndpoint` or both. + +4. Example ---------- +This example shows how to add a simple extension to the `Token endpoint`: -Sample below shows the creation of a new custom `grant_type` parameter -and declare it in the `/token` endpoint of your `Server`. Note that -you can reuse `pre_configured.Server` or use your own class inheriting -of the `Endpoint` classes you have decided. +* creation of a new class ``MyCustomGrant``, and implement ``create_token_response``. +* do basics and custom request validations, then call a custom method + of `Request Validator` to extend the interface for the implementor. +* instanciate the new grant, and bind it with an existing ``Server``. .. code-block:: python + grant_name = 'urn:ietf:params:oauth:grant-type:my-custom-grant' + class MyCustomGrant(GrantTypeBase): def create_token_response(self, request, token_handler): - if not request.grant_type == 'urn:ietf:params:oauth:grant-type:my-custom-grant': + if not request.grant_type == grant_name: raise errors.UnsupportedGrantTypeError(request=request) + # implement your custom validation checks # .. + self.request_validator.your_custom_check(request) - token = token_handler.create_token(request, - refresh_token=self.issue_new_refresh_tokens) + token = token_handler.create_token(request) return self._get_default_headers(), json.dumps(token), 200 def setup_oauthlib(): my_custom_grant = MyCustomGrant() server = Server(request_validator) - server.grant_types["urn:ietf:params:oauth:grant-type:my-custom-grant"] = my_custom_grant + server.grant_types[grant_name] = my_custom_grant + + +You can find concrete examples directly in the code source of existing +grants and existing servers. See Grant Types in +:py:mod:`oauthlib.oauth2.rfc749.grant_types`, and Servers in +:py:mod:`oauthlib.oauth2.rfc749.endpoints.pre_configured` |